WEB READ QUERYPARM

Description

The WEB READ QUERYPARM command reads a keyword parameter, consisting of a name and value pair, from a query string in a URL, and returns it in a specified code page. Escaped characters in the query string data are unescaped into the code page.

The WEB READ QUERYPARM command processes query string data for all HTTP methods, including GET, POST, PUT, and DELETE. You can continue to use the existing WEB READ FORMFIELD command for forms (messages with the media types application/x-www-form-urlencoded or multipart/form-data). Although the WEB READ FORMFIELD command can read name and value pairs from a query string, it does so only when the HTTP method is GET, because it assumes that the message is an HTML form.

You can use the query string browsing commands (WEB STARTBROWSE QUERYPARM, WEB READNEXT QUERYPARM, and WEB ENDBROWSE QUERYPARM) to browse through all the query parameters in a URL.

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

Options

QUERYPARM(data-value)

Specifies the name of the query parameter to extract. Specify a string of text containing the name of the requested parameter. The string of text supplied is not case-sensitive. If you specify the HOSTCODEPAGE option, you must supply the name of the query parameter in the code page that you specify for that option.

HOSTCODEPAGE(data-value)

Specifies the 8-character name of the CICS (host) code page required by the application program. This code page is normally an EBCDIC code page. CICS converts the value of the query parameter into this code page before returning it as the VALUE option.

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 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 query parameter name.

SET(ptr-ref)

Specifies a pointer reference that is to be set to the address of data received.

VALUE(data-area)

Specifies the buffer to contain the value of the named query parameter. CICS unescapes any escaped characters before placing them in the buffer.

VALUELENGTH(data-area)

Specifies the length, as a fullword binary value, of the query parameter value. The real 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, the value is truncated. If the length of the query parameter value is less than the size of the buffer, the query parameter 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.

12

The host code page cannot be found.

13

No keyword parameters were supplied in the HTTP request.

14

The code page combination for client and server is invalid.

17

Invalid keyword parameters found in the HTTP request.

22 LENGERR

RESP2 values are:

1

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

5

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

13 NOTFND

RESP2 value is:

1

The keyword parameter with the given name could not be found.