Skip to main content development
   toolset
 
  Easy400   |       iSeries home
Public-Source
 
Introduction
Tutorial
Examples
FAQ
Index
Download
 
 

 
2.1 - Receiving the input from the client browser


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.

  1.  The input string 
    There are three ways a remote client browser may send input to a CGI program:
    1. 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>
      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 hello is:
             firstname=George&lastname=Brown
      where George and Brown are the values entered into the two input fields of the form.

    2. 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.

    3. 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.

  2.  GET and POST methods 
    There are two ways an input string may be sent to a CGI program.
    1. 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.
    2. 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.

  3.  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:
    CGIConvMode %%EBCDIC%%
    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.

  4.  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:

    1.  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.
    2.  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.
    3.  QZhbGetVarCnt 
      There might be cases, where the input string contains several times a given input variable. In such cases, one should
      1. retrieve the number of occurrences of such an input variable through procedure QZhbGetVarCnt
      2. 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.



    Contact