Parse QUERY_STRING Environment Variable or Post stdin data (QzhbCgiParse) API

Important: Information for this topic supports the latest PTF levels for HTTP Server for i5/OS . It is recommended that you install the latest PTFs to upgrade to the latest level of the HTTP Server for i5/OS. Some of the topics documented here are not available prior to this update. See http://www.ibm.com/servers/eserver/iseries/software/http/services/service.htm Link outside Information Center for more information.
Required Parameter Group:
1 Command string Input Char(*)
2 Output format Input Char(8)
3 Target Buffer Output Char(*)
4 Length of Target Buffer Input Binary(4)
5 Length of response Output Binary(4)
6 Error Code I/O Char(*)

Use QzhbCgiParse API to parse the QUERY_STRING environment variable, in the case of the GET method, or standard input, in the case of POST method, for CGI scripts. If the QUERY_STRING environment variable is not set, the QzhbCgiParse API reads the CONTENT_LENGTH characters from its input. All return output is written to its standard output.

You can only call QzhbCgiParse once for the POST method. To use this API with the POST method, you would first want to read all of stdin and assign it to the QUERY_STRING environment variable. You would then change the environment variable REQUEST_METHOD to GET.

This API does not work with the %%MIXED%% CGI input mode.

Required parameter group

Command string
Input:CHAR(20)

The command string is a null ended string for flags and modifiers. At least one space must separate each flag. There is a one-character equivalent for each flag. The following flags are supported:

-a[gain] continuation-handle
The continuation-handle is the value returned to the caller in the target buffer when only partial information is returned. This flag is not valid on the first call to this API. It is used to retrieve the next set of information that would have been returned on a previous call if there had been enough space in the target buffer. All other flags must be the same as the previous call. Incomplete or inaccurate information may result if all other flags are not the same.
Note: This flag can only be used for the CGII0200 format.
-k[eywords]
Parses QUERY-STRING for keywords. Keywords are decoded and written to the target buffer, one per line.
-f[orm]
Parses QUERY_STRING as form request. The field names will be set as environment variables with the prefix FORM_. Field values are the contents of the variables.
-v[alue] field-name
Parses QUERY_STRING as form request. Returns only the value of field-name in the target buffer.
-r[ead]
Reads CONTENT_LENGTH characters from standard input and writes them to the target buffer.
-i[nit]
If QUERY_STRING is not set, reads the value of standard input and returns a string that can be used to set QUERY_STRING.
-s[ep] separator
Specifies the string that is used to separate multiple values. If you are using the -value flag, the default separation is newline. If you are using the -form flag, the default separator is a comma (,).
-p[refix] prefix
Used with -POST and -form to specify the prefix to use when creating environment variable names. The default is ″FORM_″.
-c[ount]
Used with -keywords, -form, and -value, returns a count of items in the target buffer that is related to these flags:
  • -keywords: Returns the number of keywords.
  • -form: Returns the number of unique fields (multiple values are counted as one).
  • -value field-name: Returns the number of values for field-name. If there is no field that is named field-name, the output is 0.
-number
Used with -keywords, -form, and -value. Returns the specified occurrence in the target buffer related to the following flags:
  • -keywords: Returns the n’th keyword. For example, -2 -keywords writes the second keyword.
  • -form: Returns all the values of the n’th field.
  • -value field-name: Returns the n’th of the multiple values of field field-name.
-Post
Information from standard input is directly decoded and parsed into values that can be used to set environment variables. This flag is the equivalent to consecutive use of the -init and -form options.
-F[sccsid] FileCCSID
The FileCCSID is the name of the file system CCSID used in CCSID conversion when processing the CGI input data. The CGI program wants the data to be returned in this CCSID. It only applies when the server is using %%BINARY%% CGI conversion mode. When an unknown CCSID is set, the current value of the CGI_EBCDIC_CCSID environment variable is used.
-N[etccsid] NetCCSID
The NetCCSID is the network CCSID used in CCSID conversion when processing the CGI input data. This is the CCSID that the data is presumed to be in at this time (as assumed or as set in a charset tag). It only applies when the server is using %%BINARY%% CGI Input mode. When an unknown CCSID is set, the current value of the CGI_ASCII_CCSID environment variable is used.
Output format
INPUT:CHAR(*)

The format of the data to be returned in the target buffer. You must use one of the following format names:

  • CGII0100 - This format is the free-form format returned to standard output on other platforms.
  • CGII0200 - CGI form variable format. This format only applies to the -form and -POST option.
Target Buffer
OUTPUT:CHAR(*)

This is output buffer that contains the information requested by the command string (if any).

Length of Target Buffer
INPUT:BINARY(4)

The length of the target buffer provided to receive the API output.

Length of Response
OUTPUT:BINARY(4)

The actual length of the information returned in the target buffer.

Error Code
I/O:CHAR(*)

The structure in which to return error information. For the format of the structure and for details on how to process API errors, see the API error reporting topic in the iSeries™ Information Center.

CGII0200 Format

Offset Decimal Offset Hexadecimal Type Field
0 0 Binary(4) Bytes returned
4 4 Binary(4) Bytes available
8 8 Char(20) Continuation handle
28 1C Binary(4) Offset to first variable entry
32 20 Binary(4) Number of variable entries returned
36 24 Char(*) Reserved
    Binary(4) Length of variable entry (see note below)
    Binary(4) Length of variable name (see note below)
    Char(*) Variable name (see note below)
    Binary(4) Length of variable value (see note below)
    Char(*) Variable value (see note below)
    Char(*) Reserved (see note below)
Note: These fields contain variable entry information and are repeated for each variable entry returned.

Field descriptions

Bytes returned
The number of bytes of data returned.
Bytes available
The number of bytes of data available to be returned. All available data is returned if enough space is available.
Continuation handle
The handle that is returned when more data is available to return, but the target buffer is not large enough. The handle indicates the point in the repository that the retrieval stopped. If the handle is used on the next call to the API (using the -again flag), the API returns more data starting at the point that the handle indicates. This field is set to blanks when all information is returned.
Offset to first variable entry
The offset to the first variable entry returned. The offset is from the beginning of the structure. If no entries are returned, the offset is set to zero.
Number of variable entries returned
The number of variable entries returned. If the target buffer is not large enough to hold the information, this number contains only the number of variables actually returned.
Reserved
This field is ignored.
Length of variable entry
The length of this variable entry. This value is used in determining the offset to the next variable entry. Note that this value is always set to a multiple of four.
Length of variable name
The length of the variable name for this entry.
Variable name
A field name as found in the form data. If the server is using %%EBCDIC%% or %%MIXED%% CGI mode, this value is in the CCSID of the job. If the server is using %%BINARY%% CGI mode, this value is in the codepage as sent from the browser unless -fsccsid is specified on the API invocation. If -fsccsid is specified, the value is in that CCSID.
Length of variable value
The length of the variable value for this entry.
Variable value
A field name as found in the form data. If the server is using %%EBCDIC%% or %%MIXED%% CGI mode, this value is in the CCSID of the job. If the server is using %%BINARY%% CGI mode, this value is in the codepage as sent from the browser unless -fsccsid is specified on the API invocation. If -fsccsid is specified, the value is in that CCSID.

Error messages

CPF24B4 E
Severe Error while addressing parameter list.
CPF3C17 E
Error occurred with input data parameter.
CPF3C19 E
Error occurred with receiver variable specified.
CPF3CF1 E
Error code parameter not valid.
Note: Error messages are added to the error log or script log except for those listed.