Parse QUERY_STRING Environment Variable or Post stdin data (QzhbCgiParse) API
The QzhbCgiParse() API allows you 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.
| Required Parameter Group: | |||
| 1 | Command string | Input | Char(*) |
| 2 | Output format | Input | Char(*) |
| 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(*) |
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(*)
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 IBM® i 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.