WEB READ FORMFIELD

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 Escaped and unescaped data 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

CHARACTERSET(name)

specifies the 40–character name of the character set that is required for encoding the form data. This option should match the forms encoding determined by the corresponding HTML form (see How the client encoding is determined for more information). CICS does not support all the character sets named by IANA. HTML coded character sets lists the IANA character sets that are supported by CICS for code page conversion.

CLNTCODEPAGE(name)

This option is supported for upgrade purposes only. CHARACTERSET replaces it. The action taken by CICS is the same for both keywords.

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 CICS (host) code page required by the application program, into which the form data is to be converted. This code page is normally an EBCDIC code page.

The standard CICS form of a host code page name consists of the code page number (or more generally CCSID) written using 3 to 5 decimal digits as necessary then padded with trailing spaces to 8 characters. For code page 37, which is fewer than 3 digits, the standard form is 037. CICS now also accepts any decimal number of up to 8 digits (padded with trailing spaces) in the range 1 to 65535 as a code page name, even if it is not in the standard form.

If the code page is not specified, the data is returned in the EBCDIC code page specified by the LOCALCCSID system initialization parameter (which applies to the local CICS region, and has a default of 037), provided that the specified code page is supported by the CICS web interface. The code page is supported if it is one of a list of EBCDIC code pages that are recognized by CICS as being sufficiently standard to allow successful parsing of the web headers (this includes all SBCS CECP and Euro code pages). Otherwise, CICS returns the data in 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 form field value. The actual length of the value is returned in this data area. 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

16 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 forms data has been supplied in the HTTP request.

14

The code page combination for client and server is invalid.

17

Invalid forms data was found in the input message.

22 LENGERR

RESP2 values are:

1

The length in NAMELENGTH or VALUELENGTH is less than or equal to zero.

4

The form field name has been truncated during a read operation because the receiving buffer is too small.

5

The form field value has been truncated during a read operation because the receiving buffer is too small.

153

The form type is unknown.

154

A boundary string was expected in the forms data, but was not found.

13 NOTFND

RESP2 values are:

1

The form field with the given name cannot be found.