When a client Browser (Internet Explorer, Netscape, Mozilla, etc.)
invokes a CGI program, it may provide the program with a set of
parameters by which the program would understand what
it should do.
However, this is not a parameter list as we are used with on iSeries.
This is a so called "query string", a string containing keywords and values.
This string can be sent in two different ways (methods), one called GET,
the other one called POST.
- 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 |
which shows as |
<form method="post" action="/cgicbldev2p/hello.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>
|
|
|
In this case, when the remote user, after entering data in the
two input fields, presses the Send button, the string sent
to program hello 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="/cgicbldev2p/hello.pgm?firstname=George&lastname=Brown">Say hello
to George Brown</a>
will send the same string to program
hello.
- From the command line (location line)
For istance, if in this line one types
http://.../cgicbldev2/hello.pgm?firstname=George&lastname=Brown
the same string will be sent to program
hello.
- GET and 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.
It should be also noted that with the GET method the input string
has a limited length, depending on the client browser.
- 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. With the POST method the input string length
can reach 32767 characters.
Though these two methods have implications on the way
a CGI should retrieve its input string,
our service 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.
- Procedure to read the input string
To have your COBOL program acquiring the buffer containing
the query string sent from the client browser, use procedure
QZhbGetInput .
This procedure takes advantage of the HTTP server
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
QZhbGetVarCnt,
QZhbGetVar,
QZhbGetVarUpper
input variable parsing procedures.
|
Warning.
For the QzhbCgiParse API to work properly,
the following HTTP directive should be specified:
This can be done either via a global directive or acting at a detail level,
as follow:
<Directory /qsys.lib/mycgilib.lib>
Options None
order allow,deny
allow from all
CGIConvMode %%EBCDIC%%
</Directory>
|
|
Example of calling procedure QZhbGetInput:
... ... ...
SPECIAL-NAMES.
copy CPYSPCNAME of CGICBLDEV2-QCBLLESRC.
... ... ...
* Get input data from POST or GET
call 'QZHBGETINPUT'. |
Also, please checkout the COBOL source of the
HELLO sample program.
- Procedures to parse the input string
Sample input string:
firstname=George&lastname=Brown
Once a CGI has read the input string sent from the remote
browser, it must understand what the request is.
To do this there must be some routine that scans
the input (query) string for all the possible keywords
and saves their values into program variables,
so that the program may then test them and process the
user request. This scan_and_break operation
is commonly referrred to as "parsing".
There are three procedures to perform string parsing:
- QZhbGetVar
The basic call to this procedure
allows to receive the first (or only) instance of an input variable
into a program variable.
If the specified input variable is not found in the input string, a blank
value is returned.
Example:
... ... ...
SPECIAL-NAMES.
copy CPYSPCNAME of CGICBLDEV2-QCBLLESRC.
... ... ...
* Variables to parse the input string:
* 1-Variable (must be 50 char) containing
* the name of the input variable to be received:
05 varnamein PIC X(50).
* 2-Variables (must be 1000 char) containing
* the values of the received input variables:
05 firstname PIC X(1000).
05 lastname PIC X(1000).
... ... ...
* Receive input variable "firstname="
move 'firstname' to varnamein.
call 'QZHBGETVAR' using
by content varnamein
returning into firstname. |
Also, please checkout the COBOL source of the
HELLO sample program.
- QZhbGetVarUpper
Use this procedure, instead of QzhbGetVar,
to receive an input variable in uppercase characters.
Example:
... ... ...
SPECIAL-NAMES.
copy CPYSPCNAME of CGICBLDEV2-QCBLLESRC.
... ... ...
* Variables to parse the input string
* 1-Variable (must be 50 char) containing
* the name of the input variable to be received:
05 varnamein PIC X(50).
* 2-Variables (must be 1000 char) containing
* the values of the received input variables:
05 firstname PIC X(1000).
05 lastname PIC X(1000).
... ... ...
* Receive input variable "firstname=" in uppercase characters
move 'request' to varnamein.
call 'QZHBGETVARUPPER' using
by content varnamein
returning into request. |
Also, please checkout the COBOL source of the
HELLO sample program.
- QZhbGetVarCnt
There might be cases, where the input string contains several times
a given input variable. In such cases, one should
- retrieve the number of occurrences of such an input variable
through procedure QZhbGetVarCnt
- retrieve one by one the individual occurrences of the input variable
specifying the occurrence number to procedure QZhbGetVar
Example:
... ... ...
SPECIAL-NAMES.
copy CPYSPCNAME of CGICBLDEV2-QCBLLESRC.
... ... ...
* Variables to parse the input string
05 varnamein PIC X(50).
05 nbroccurs PIC S9(9) binary.
05 occurrence PIC S9(9) binary.
*
05 ordernbr PIC X(10).
... ... ...
* Retrieve the number of occurrences of input variable
* "ordernbr=" and save it in pgm variable 'nbroccurs'
move 'ordernbr' to varnamein.
call 'QZHBGETVARCNT' using varnamein
returning into nbroccurs.
* Retrieve the value of each input variable
* "ordernbr=" and perform the appropriate processing
compute occurrence = 1
perform until occurrence > nbroccurs
move 'ordernbr' to varnamein
call 'QZHBGETVARUPPER' using
by content varnamein
by content occurrence
returning into ordernbr.
if ordernbr not = ' '
perform OrdProc thru z-OrdProc
end-if.
compute occurrence = occurrence + 1
end-perform. |
Cases of multiple occurrences of an input variable
do usually arise when the input form includes a table
with the same input field (for instance, a check box)
on each row of the table.
For a live example of such a case, please check out
BREAKFAST2 sample program.
|