WEB READ FORMFIELD

Retrieve the value of a field from an HTML form.

Read syntax diagramSkip visual syntax diagram
WEB READ FORMFIELD

>>-WEB--READ--FORMFIELD(data-area)------------------------------>

>--+------------------------+--+-VALUE(data-area)-+------------->
   '-NAMELENGTH(data-value)-'  '-SET(ptr-ref)-----'   

>--VALUELENGTH(data-area)--------------------------------------->

>--+----------------------------------------------------+------><
   '-CLNTCODEPAGE(data-value)--HOSTCODEPAGE(data-value)-'   

Conditions: INVREQ, LENGERR, NOTFND

This command is threadsafe.

Description

WEB READ FORMFIELD retrieves the value of a specific field from an HTML form. The name of the form field is given in the FORMFIELD parameter. The form data is sent as part of an HTTP request being processed by the current CICS® task.

The Web client sends form data in a query string when the GET method is used, and in the entity body when the POST method is used. CICS can extract the data from either of these locations.

The form data is returned in its unescaped form (see the CICS Internet Guide for an explanation of this).

If the data that is received represents a file, the uploaded file does not undergo code page conversion.

CICS only reads form data when CICS is the HTTP server. The facility is not available when CICS is an HTTP client.

Options

CLNTCODEPAGE(data-value)
specifies the name of the character set that was used by the Web client for the HTTP request. The name of the character set can consist of up to 40 alphanumeric characters, including appropriate punctuation. If this is not specified, CICS obtains it from the Content-Type header of the HTTP request. If the Content-Type header is not present, CICS assumes the ISO-8859-1 character set. If you specify CLNTCODEPAGE you must also specify HOSTCODEPAGE. The CICS Internet Guide lists the IANA character sets that are supported by CICS for code page conversion.
FORMFIELD(data-area)
specifies the name of the form field to extract. It is a string of text containing the name of the requested field. The string of text supplied is not case sensitive.
HOSTCODEPAGE(data-value)
Start of changespecifies the 8–character name of the host code page used by the application program, into which the form data is to be converted. If you specify HOSTCODEPAGE you must also specify CLNTCODEPAGE. This code page is normally an EBCDIC code page. If this is not specified, the default is the EBCDIC code page 037.

If the form data is in a query string (GET method), this option is ignored, and the data is returned in the EBCDIC code page specified by the LOCALCCSID system initialization parameter (which applies to the whole of the local CICS region, and has a default of 037). If the ASCII Latin-1 character set ISO-8859-1 (code page 819) cannot be converted into that code page, CICS uses the default EBCDIC code page 037 instead.

End of change
NAMELENGTH(data-value)
specifies the length, as a fullword binary value, of the form field name.
SET(ptr-ref)
specifies a pointer reference that is to be set to the address of data received. The pointer reference is valid until the end of the task.
VALUE(data-area)
specifies the buffer to contain the value of the named form field. CICS unescapes any escaped characters before placing them in the buffer.
VALUELENGTH(data-area)
specifies the length, as a fullword binary value, of the buffer that is to contain the form field value. If you specify the VALUE option, VALUELENGTH specifies the maximum length of the data that the program accepts. If the value exceeds the length of the buffer, it is truncated. If the length of the form field value is less than the size of the buffer, the form field value is placed in the leftmost byte positions.

Conditions

INVREQ
RESP2 values are:
1
The command is being issued in a non-CICS Web support application.
3
The command is being issued for a non-HTTP request.
11
The client code page cannot be found.
12
The host code page cannot be found.
13
No form data has been supplied in the body of the HTTP request.
14
The code page combination for client and server is invalid.
Start of change17End of change
Start of changeInvalid forms data was found in the input message.End of change
LENGERR
RESP2 values are:
1
The length in VALUELENGTH is less than or equal to zero.
5
The form field value has been truncated during a read operation because the receiving buffer is too small.
NOTFND
RESP2 values are:
1
The form field with the given name cannot be found.