ibm-information-center/dist/eclipse/plugins/i5OS.ic.rzaie_5.4.0.1/rzaieapi_qzhbcgiparse.htm

351 lines
18 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="security" content="public" />
<meta name="Robots" content="index,follow" />
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
<meta name="DC.Type" content="topic" />
<meta name="DC.Title" content="Parse QUERY_STRING Environment Variable or Post stdin data (QzhbCgiParse) API" />
<meta name="copyright" content="(C) Copyright IBM Corporation 2002,2006" />
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2002,2006" />
<meta name="DC.Format" content="XHTML" />
<meta name="DC.Identifier" content="rzaieapi_qzhbcgiparse" />
<meta name="DC.Language" content="en-us" />
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
<link rel="stylesheet" type="text/css" href="./ic.css" />
<title>Parse QUERY_STRING Environment Variable or Post stdin data (QzhbCgiParse)
API</title>
</head>
<body id="rzaieapi_qzhbcgiparse"><a name="rzaieapi_qzhbcgiparse"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<!--Java sync-link--><h1 class="topictitle1">Parse QUERY_STRING Environment Variable or Post stdin data (QzhbCgiParse)
API</h1>
<div><div class="important"><span class="importanttitle">Important:</span> 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 <a href="http://www-03.ibm.com/servers/eserver/iseries/software/http/services/service.html" target="_blank">http://www.ibm.com/servers/eserver/iseries/software/http/services/service.htm</a> <img src="www.gif" alt="Link outside Information Center" /> for more information. </div>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" class="figborder" frame="void" border="0" rules="none"><tbody><tr><td colspan="4" valign="top">Required Parameter Group:</td>
</tr>
<tr><td align="right" valign="top" width="6.313131313131313%">1</td>
<td valign="top" width="31.313131313131315%">Command string</td>
<td valign="top" width="31.060606060606062%">Input</td>
<td valign="top" width="31.313131313131315%">Char(*)</td>
</tr>
<tr><td align="right" valign="top" width="6.313131313131313%">2</td>
<td valign="top" width="31.313131313131315%">Output format</td>
<td valign="top" width="31.060606060606062%">Input</td>
<td valign="top" width="31.313131313131315%">Char(8)</td>
</tr>
<tr><td align="right" valign="top" width="6.313131313131313%">3</td>
<td valign="top" width="31.313131313131315%">Target Buffer</td>
<td valign="top" width="31.060606060606062%">Output</td>
<td valign="top" width="31.313131313131315%">Char(*)</td>
</tr>
<tr><td align="right" valign="top" width="6.313131313131313%">4</td>
<td valign="top" width="31.313131313131315%">Length of Target Buffer</td>
<td valign="top" width="31.060606060606062%">Input</td>
<td valign="top" width="31.313131313131315%">Binary(4)</td>
</tr>
<tr><td align="right" valign="top" width="6.313131313131313%">5</td>
<td valign="top" width="31.313131313131315%">Length of response</td>
<td valign="top" width="31.060606060606062%">Output</td>
<td valign="top" width="31.313131313131315%">Binary(4)</td>
</tr>
<tr><td align="right" valign="top" width="6.313131313131313%">6</td>
<td valign="top" width="31.313131313131315%">Error Code</td>
<td valign="top" width="31.060606060606062%">I/O</td>
<td valign="top" width="31.313131313131315%">Char(*)</td>
</tr>
</tbody>
</table>
</div>
<p>Use <em>QzhbCgiParse</em> 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. </p>
<p>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. </p>
<p>This API does not work with the %%MIXED%% CGI input mode.</p>
</div>
<div class="nested1" id="required"><a name="required"><!-- --></a><h2 class="topictitle2">Required parameter group</h2>
<div><dl><dt class="dlterm"><strong>Command string</strong></dt>
<dd>Input:CHAR(20) <p>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:</p>
<dl><dt class="dlterm"><strong>-a[gain]</strong> <em>continuation-handle</em></dt>
<dd>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.<div class="note"><span class="notetitle">Note:</span> This flag can only be used for the CGII0200 format.</div>
</dd>
</dl>
<dl><dt class="dlterm"><strong>-k[eywords]</strong></dt>
<dd>Parses QUERY-STRING for keywords. Keywords are decoded and written to
the target buffer, one per line.</dd>
</dl>
<dl><dt class="dlterm"><strong>-f[orm]</strong></dt>
<dd>Parses QUERY_STRING as form request. The field names will be set as environment
variables with the prefix <strong>FORM_</strong>. Field values are the contents of the
variables.</dd>
</dl>
<dl><dt class="dlterm"><strong>-v[alue]</strong> <em>field-name</em></dt>
<dd>Parses QUERY_STRING as form request. Returns only the value of <em>field-name</em> in
the target buffer.</dd>
</dl>
<dl><dt class="dlterm"><strong>-r[ead]</strong></dt>
<dd>Reads CONTENT_LENGTH characters from standard input and writes them to
the target buffer.</dd>
</dl>
<dl><dt class="dlterm"><strong>-i[nit]</strong></dt>
<dd>If QUERY_STRING is not set, reads the value of standard input and returns
a string that can be used to set QUERY_STRING.</dd>
</dl>
<dl><dt class="dlterm"><strong>-s[ep]</strong> <em>separator</em></dt>
<dd>Specifies the string that is used to separate multiple values. If you
are using the <strong>-value</strong> flag, the default separation is newline. If you
are using the <strong>-form</strong> flag, the default separator is a comma (,).</dd>
</dl>
<dl><dt class="dlterm"><strong>-p[refix]</strong> <em>prefix</em></dt>
<dd>Used with <strong>-POST</strong> and <strong>-form </strong>to specify the prefix to use when
creating environment variable names. The default is ″<strong>FORM_</strong>″.</dd>
</dl>
<dl><dt class="dlterm"><strong>-c[ount]</strong></dt>
<dd>Used with -<strong>keywords</strong>, <strong>-form</strong>, and <strong>-value</strong>, returns a
count of items in the target buffer that is related to these flags:<ul><li><strong>-keywords</strong>: Returns the number of keywords.</li>
<li><strong>-form</strong>: Returns the number of unique fields (multiple values are
counted as one).</li>
<li><strong>-value</strong> <em>field-name</em>: Returns the number of values for <em>field-name</em>.
If there is no field that is named <em>field-name</em>, the output is 0.</li>
</ul>
</dd>
</dl>
<dl><dt class="dlterm"><strong>-number</strong></dt>
<dd>Used with <strong>-keywords</strong>, <strong>-form</strong>, and <strong>-value</strong>. Returns the
specified occurrence in the target buffer related to the following flags:<ul><li><strong>-keywords</strong>: Returns the nth keyword. For example, <strong>-2 -keywords</strong> writes
the second keyword.</li>
<li><strong>-form</strong>: Returns all the values of the nth field.</li>
<li><strong>-value</strong> <em>field-name</em>: Returns the nth of the multiple values
of field <em>field-name</em>.</li>
</ul>
</dd>
</dl>
<dl><dt class="dlterm"><strong>-Post</strong></dt>
<dd>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 <strong>-init</strong> and <strong>-form</strong> options.</dd>
</dl>
<dl><dt class="dlterm"><strong>-F[sccsid]</strong> <em>FileCCSID</em></dt>
<dd>The <em>FileCCSID</em> 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.</dd>
</dl>
<dl><dt class="dlterm"><strong>-N[etccsid]</strong> <em>NetCCSID</em></dt>
<dd>The <em>NetCCSID</em> 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.</dd>
</dl>
</dd>
</dl>
<dl><dt class="dlterm"><strong>Output format</strong></dt>
<dd>INPUT:CHAR(*) <p>The format of the data to be returned in the target buffer.
You must use one of the following format names:</p>
<ul><li><strong>CGII0100</strong> - This format is the free-form format returned to standard
output on other platforms.</li>
<li><strong>CGII0200</strong> - CGI form variable format. This format only applies to
the -form and -POST option.</li>
</ul>
</dd>
</dl>
<dl><dt class="dlterm"><strong>Target Buffer</strong></dt>
<dd>OUTPUT:CHAR(*) <p>This is output buffer that contains the information
requested by the command string (if any).</p>
</dd>
</dl>
<dl><dt class="dlterm"><strong>Length of Target Buffer</strong></dt>
<dd>INPUT:BINARY(4) <p>The length of the target buffer provided to receive
the API output.</p>
</dd>
</dl>
<dl><dt class="dlterm"><strong>Length of Response</strong></dt>
<dd>OUTPUT:BINARY(4) <p>The actual length of the information returned in the
target buffer.</p>
</dd>
</dl>
<dl><dt class="dlterm"><strong>Error Code</strong></dt>
<dd>I/O:CHAR(*) <p>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.</p>
</dd>
</dl>
</div>
</div>
<div class="nested1" id="cgiio200format"><a name="cgiio200format"><!-- --></a><h2 class="topictitle2">CGII0200 Format</h2>
<div>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><thead align="left"><tr><th valign="top" id="d0e382">Offset Decimal</th>
<th valign="top" id="d0e384">Offset Hexadecimal</th>
<th valign="top" id="d0e386">Type</th>
<th valign="top" id="d0e388">Field</th>
</tr>
</thead>
<tbody><tr><td valign="top" headers="d0e382 ">0</td>
<td valign="top" headers="d0e384 ">0</td>
<td valign="top" headers="d0e386 ">Binary(4)</td>
<td valign="top" headers="d0e388 ">Bytes returned</td>
</tr>
<tr><td valign="top" headers="d0e382 ">4</td>
<td valign="top" headers="d0e384 ">4</td>
<td valign="top" headers="d0e386 ">Binary(4)</td>
<td valign="top" headers="d0e388 ">Bytes available</td>
</tr>
<tr><td valign="top" headers="d0e382 ">8</td>
<td valign="top" headers="d0e384 ">8</td>
<td valign="top" headers="d0e386 ">Char(20)</td>
<td valign="top" headers="d0e388 ">Continuation handle</td>
</tr>
<tr><td valign="top" headers="d0e382 ">28</td>
<td valign="top" headers="d0e384 ">1C</td>
<td valign="top" headers="d0e386 ">Binary(4)</td>
<td valign="top" headers="d0e388 ">Offset to first variable entry</td>
</tr>
<tr><td valign="top" headers="d0e382 ">32</td>
<td valign="top" headers="d0e384 ">20</td>
<td valign="top" headers="d0e386 ">Binary(4)</td>
<td valign="top" headers="d0e388 ">Number of variable entries returned</td>
</tr>
<tr><td valign="top" headers="d0e382 ">36</td>
<td valign="top" headers="d0e384 ">24</td>
<td valign="top" headers="d0e386 ">Char(*)</td>
<td valign="top" headers="d0e388 ">Reserved</td>
</tr>
<tr><td valign="top" headers="d0e382 ">&nbsp;</td>
<td valign="top" headers="d0e384 ">&nbsp;</td>
<td valign="top" headers="d0e386 ">Binary(4)</td>
<td valign="top" headers="d0e388 ">Length of variable entry (see note below)</td>
</tr>
<tr><td valign="top" headers="d0e382 ">&nbsp;</td>
<td valign="top" headers="d0e384 ">&nbsp;</td>
<td valign="top" headers="d0e386 ">Binary(4)</td>
<td valign="top" headers="d0e388 ">Length of variable name (see note below)</td>
</tr>
<tr><td valign="top" headers="d0e382 ">&nbsp;</td>
<td valign="top" headers="d0e384 ">&nbsp;</td>
<td valign="top" headers="d0e386 ">Char(*)</td>
<td valign="top" headers="d0e388 ">Variable name (see note below)</td>
</tr>
<tr><td valign="top" headers="d0e382 ">&nbsp;</td>
<td valign="top" headers="d0e384 ">&nbsp;</td>
<td valign="top" headers="d0e386 ">Binary(4)</td>
<td valign="top" headers="d0e388 ">Length of variable value (see note below)</td>
</tr>
<tr><td valign="top" headers="d0e382 ">&nbsp;</td>
<td valign="top" headers="d0e384 ">&nbsp;</td>
<td valign="top" headers="d0e386 ">Char(*)</td>
<td valign="top" headers="d0e388 ">Variable value (see note below)</td>
</tr>
<tr><td valign="top" headers="d0e382 ">&nbsp;</td>
<td valign="top" headers="d0e384 ">&nbsp;</td>
<td valign="top" headers="d0e386 ">Char(*)</td>
<td valign="top" headers="d0e388 ">Reserved (see note below)</td>
</tr>
</tbody>
</table>
</div>
<div class="note"><span class="notetitle">Note:</span> These fields contain variable entry information and are repeated for
each variable entry returned.</div>
</div>
</div>
<div class="nested1" id="fielddescrip"><a name="fielddescrip"><!-- --></a><h2 class="topictitle2">Field descriptions</h2>
<div><dl><dt class="dlterm"><strong>Bytes returned</strong></dt>
<dd>The number of bytes of data returned.</dd>
</dl>
<dl><dt class="dlterm"><strong>Bytes available</strong></dt>
<dd>The number of bytes of data available to be returned. All available data
is returned if enough space is available.</dd>
</dl>
<dl><dt class="dlterm"><strong>Continuation handle</strong></dt>
<dd>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 <strong>-again</strong> 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.</dd>
</dl>
<dl><dt class="dlterm"><strong>Offset to first variable entry</strong></dt>
<dd>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.</dd>
</dl>
<dl><dt class="dlterm"><strong>Number of variable entries returned</strong></dt>
<dd>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.</dd>
</dl>
<dl><dt class="dlterm"><strong>Reserved</strong></dt>
<dd>This field is ignored.</dd>
</dl>
<dl><dt class="dlterm"><strong>Length of variable entry</strong></dt>
<dd>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.</dd>
</dl>
<dl><dt class="dlterm"><strong>Length of variable name</strong></dt>
<dd>The length of the variable name for this entry.</dd>
</dl>
<dl><dt class="dlterm"><strong>Variable name</strong></dt>
<dd>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 <strong>-fsccsid</strong> is specified on the API invocation. If <strong>-fsccsid</strong> is
specified, the value is in that CCSID.</dd>
</dl>
<dl><dt class="dlterm"><strong>Length of variable value</strong></dt>
<dd>The length of the variable value for this entry.</dd>
</dl>
<dl><dt class="dlterm"><strong>Variable value</strong></dt>
<dd>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 <strong>-fsccsid</strong> is specified on the API invocation. If <strong>-fsccsid</strong> is
specified, the value is in that CCSID.</dd>
</dl>
</div>
</div>
<div class="nested1" id="error"><a name="error"><!-- --></a><h2 class="topictitle2">Error messages</h2>
<div><dl><dt class="dlterm"><strong>CPF24B4 E</strong></dt>
<dd>Severe Error while addressing parameter list.</dd>
</dl>
<dl><dt class="dlterm"><strong>CPF3C17 E</strong></dt>
<dd>Error occurred with input data parameter.</dd>
</dl>
<dl><dt class="dlterm"><strong>CPF3C19 E</strong></dt>
<dd>Error occurred with receiver variable specified.</dd>
</dl>
<dl><dt class="dlterm"><strong>CPF3CF1 E</strong></dt>
<dd>Error code parameter not valid.</dd>
</dl>
<div class="note"><span class="notetitle">Note:</span> Error messages are added to the error log or script log except for those
listed.</div>
</div>
</div>
</body>
</html>