Retrieve the value of a field from an HTML form.

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)
specifies
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.

- 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.
17
Invalid forms data was found in the input message.
- 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.