switch to Italian
Giovanni's logo Map input string into program variables
index
M
power search
blue line
Sample input string:
       cgiinp01=George&cgiinp02=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".

The following parsing subprocedures are available:

1. "zhbGetVar" parsing procedure

Parsing procedure zhbgetvar lets you retrieve fields from the input string one at a time into program-defined fields.
If you want to uppercase a field while retrieving it from the input string, you may use the parsing procedure zhbgetvarupper.
If you want to lowercase a field while retrieving it from the input string, you may use the parsing procedure zhbgetvarlower.

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

 * Prototype definitions and
 * standard system API error structure
 /copy CGIDEV2/qrpglesrc,prototypeb
 /copy CGIDEV2/qrpglesrc,usec
 * Number of variables
D nbrVars         s             10i 0
 *
 * Saved query string
Dsavedquerystring...
D                 s          32767    varying
 *
 * Client input variables
D custname        s             40
D emailadd        s             40
D state           s              2
            ... etc. ...
 /free
    // Get input
    nbrVars=zhbgetinput(savedquerystring:qusec);
    // Parse variables
    //  from QUERY_STRING environment variable:
    // -Customer name
    custname=zhbgetvar('custname');
    // -E-mail address
    emailadd=zhbgetvar('emailadd'):
    // -State
    state=zhbgetvar('state');
        

For a complete example see the source of program TEMPLATE3.

2. "zhbGetVarPtr" parsing procedure

Parsing procedure zhbgetvarptr returns a pointer to an input variable. This is useful when an input variable's length might exceed ZhbGetVar's maximum size of 32767.
The maximum length of such a variable is 64000.
If the input variable is not found or length is 0, returns *null .
Service program CGISRVPGM2 allocates a memory area for the input variable and the return pointer is used to address it. It is a user program responsibility to free this memory area once the input variable data is no longer needed. If that is not done, the memory used by the service program activation group will steadily increase and in the long run that will cause problems.

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

 * Prototype definitions and
 * standard system API error structure
 /copy CGIDEV2/qrpglesrc,prototypeb
 /copy CGIDEV2/qrpglesrc,usec
 * Number of variables
D nbrVars         s             10i 0
 *
 * Saved query string
Dsavedquerystring...
D                 s          32767    varying
 *
 * Pointer returned from zhbGetVarPtr
D ReturnVarP      s               *
 * Variables for zhbGetVarPtr
D  varnamein      s             50
D  occurrence     s             10i 0
D  varLenOut      s             10i 0
            ... etc. ...
 /free
    // Get input
    nbrVars=zhbgetinput(savedquerystring:qusec);
    // Retrieve the pointer
    //  to input variable named 'longstring':
    occurrence=1;
    ReturnVarP=zhbGetVarPtr('longstring':
               occurrence:varLenOut);
       // ... process the input variable data,
       //     then, ...
    dealloc ReturnVarP;  // release memory
        

Notes.

  • Do not use this subprocedure for reading a file being uploaded from the browser. See Uploading PC files.
  • Make sure to deallocate the memory acquired for the input variable data.

3. Other zhbGet... subprocedures
  • ZhbCountAllVars: returns the number of occurrences of all variables in the input string (ZhbGetInput must have been run before calling this subprocedure)
  • ZhbGetVarDetails: returns the following information on the user-specified nth input variable (out of those counted with ZhbCountAllVars): variable name, variable occurrence number, indicator (char 0/1) whether variable was found.
D  nbrInpVars     s             10i 0
D  ThisVarVal     s           1000a
D  ThisOccur      s             10i 0
D  ThisVarName    s             50
D  ThisVarOccur   s             10i 0
D  FoundInd       s               n
 /free
    // Get input
    nbrVars=zhbgetinput(savedquerystring:qusec);
    // Example of retrieving
    //  the number of occurrences
    //  of all variables in the CGI input
    nbrInpVars=ZhbCountAllVars();
    // Example of retrieving
    //  detailed information
    //  for all the input variables
    if nbrInpVars>0;
       for ThisOccur 1 to nbrInpVars;
           ThisVarVal=ZhbGetVarDetails(ThisOccur:
                      ThisVarName:
                      ThisVarOccur:
                      FoundInd);
       endfor;
    endif;


4. Receiving names of input variables

There may be cases where the CGI program cannot predict the names of the input variables, and must find out what they are.
Such cases can be easily solved by using, in sequence, the following subprocedures:

  1. ZhbGetInput
  2. ZhbCountAllVars
  3. ZhbGetVarDetails