Read input from client browser

index

power search

1. The input string
2. GET and POST methods
3. Procedure to read the input string

1. The input string

There are three ways a remote client browser may send input to a CGI program:

From an HTML form. As an example:

html

<form method="post" action="/cgidev2p/hello1.pgm">
Your first name:
<input type="text" name="firstname"
size="10" maxlength="30"><br>
Your last name:
<input type="text" name="lastname"
size="10" maxlength="30"><br>
<center>
<input type="submit" value="Send">
</center>
</form>

which shows as

Your first name:
Your last name:

In this case, when the remote user, after entering data in the two input fields, presses the Send button, the string sent to program hello1 is:
firstname=George&lastname=Brown
where George and Brown are the values entered into the two input fields of the form.

From an anchor tag (<a>...</a>) in an HTML script. As an example, the following anchor

<a href="/cgidev2p/hello1.pgm?
firstname=George&lastname=Brown">Say hello to George Brown</a>

will send the same string to program hello1.
From the command line (location line) of the browser.
For instance, if in this line one types

http://.../cgidev2p/hello1.pgm?
George&lastname=Brown

the same string will be sent to program hello1.

2. The GET and the POST methods

There are two ways an input string may be sent to a CGI program.

With the GET method.
This is implicitly done when the sending is performed either through an anchor tag (<a> href=...</a>) or through the browser command line.
The GET method may also be used in a form tag. This is usually done for test purposes.
In fact, when using the GET method, the input string is always visible in the browser command line.
The GET method has some restrictions, which do not exist for the POST method:
1. The input string (containing parameters after character "?"; usually called query string) has a maximum length of about 3 thousand characters. The maximum length depends on the type of browser.
2. The values of the parameters can just be alphanumeric strings: no special characters, no inbedded spaces. Special characters and inbedded spaces must be replaced by URL escaped sequences.
With the POST method.
This is commonly done in a form tag.
In fact, when using the POST method, the input string is not visible to the end user.

Though these two methods have implications on the way a CGI should retrieve its input string, Mel Rothman's service program provides procedures which would take care to retrieve the input string whichever way it was sent.
Therefore your CGI programs are not sensitive to the method used by the remote browser.

If you wish, you can run a Demo program on GET and POST methods.
This program lets you select between GET and POST, so that you can see the difference in the URL.
Besides, it teaches how you can dynamically output a link from your CGI program.

blue line

3. Procedure to read the input string

In order to acquire the input buffer sent from the browser, your CGI program must use the zhbGetInput subprocedure

ZhbGetInput uses the server's QzhbCgiParse API to get the browser's input and places it into a set of internal, dynamically allocated arrays for subsequent high performance use by the ZhbGetVarCnt, ZhbGetVar, ZhbGetVarUpper input variable parsing procedures.

Warning. For the QzhbCgiParse API to work properly, the CGIConvMode must contain value %%EBCDIC/EBCDIC%% (not the value %%MIXED/MIXED%%). If that does not happen, ZhbGetInput writes an error message into the debugging file and allows the program to continue until it fails.
To use the zhbGetInput correctly you must add the following Apache HTTP directive:

CGIConvMode %%EBCDIC/EBCDIC%%

This is how you can use the ZhbGetInput subprocedure in your CGI program:

 * Prototype definitions and
 * standard system API error structure
 /copy CGIDEV2/qrpglesrc,prototypeb
 /copy CGIDEV2/qrpglesrc,usec
 * Number of variables
DnbrVars          s             10i 0
 *
 * Saved query string
Dsavedquerystring...
D                 s          32767    varying
 *
            ... etc. ...
 /free
    // Get the input buffer sent from the browser
    nbrVars=zhbGetInput(savedquerystring:qusec);

or you can use the following code:

 * Prototype definitions and
 * standard system API error structure
 /copy CGIDEV2/qrpglesrc,prototypeb
 /copy CGIDEV2/qrpglesrc,usec
 * Predefined variables
 /copy CGIDEV2/qrpglesrc,variables3
            ... etc. ...
 * Get the input buffer sent from the browser
 /copy CGIDEV2/qrpglesrc,prolog3

Once procedure ZhbGetInput has been issued, your program may start receiving the input variables for the CGI transaction. Input variables must be receives one at a time using procedure ZhbGetVar.

Important note on ZhbGetInput. When method POST is used, procedure ZhbGetInput can be used only once in a CGI program. If you call it twice, input program variables can no longer be received.
For instance: if the methos is POST, the transaction is processed from a program made of two modules/programs A and B, A calls B, and both A and B start with procedure ZhbGetInput, A has no problem in receiving the input variables, while B - after issuing its ZhbGetInput - receives blank values for the input variables. However, if you remove ZhbGetInput from B, also B can receive the input variables.
This limitation comes from IBM developed QzhbCgiParse API, see this IBM page.

For a live example of using procedure ZhbGetInput, please see the source of the template3 program.