Map input string into program variables

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

In Mel's service program there are three ways you can perform parsing:

for getInput read procedure:
1. "cvtDB" parsing procedure
2. "cgiVarVal" parsing procedure
for zhbGetInput read procedure:

1. "cvtDB" parsing procedure (for input string read via getInput procedure)

Parsing procedure CvtDb uses QtmhCvtDb API. This API moves the values of the input string keywords into omonymous fields of an externally defined data structure.
Basically, what you have to do is

define a physical file with the needed fields
mention this file in your CGI as an external data structure
invoke the API through the CvtDB subprocedure to have the parsing done in the fields of this external data structure.

Example:

D InData          s          32767          Area to accept input
D InActLn         s             10i 0       Actual length Rcvd
D ReqMethod       s              4          Returns GET or POST
            ... etc. ...
D CGIEXTERDS    e ds
D DBDSLn          S             10i 0 inz(%size(CGIEXTERDS))    Size of DS
D DBActLn         S             10i 0                           Data Ln returned
D DBRespCd        S             10i 0                           Response code
            ... etc. ...
 * Get input data from POST or GET.
C                   callp     getinput(indata:inactln:ReqMethod)
 * Parse the input data into the externally described data structure
C                   callp     cvtDB(DBFileName:InData:
C                                   InActLn:
C                                   CGIEXTERDS:
C                                   DBDSLn:DBActLn:DBRespCd:qusec)

For a complete example see the source of program TEMPLATE.

However you do not have to type in this code. To read the input string and parse it into the externally described data structure, just include our prolog1 member as follow:

/copy mysrclib/qrpglesrc,prototypeb
/copy mysrclib/qrpglesrc,usec
/copy mysrclib/qrpglesrc,variables1
            ... etc. ...
/copy mysrclib/qrpglesrc,prolog1

For a complete example, please see the source of the hello1 program.

Important to be read
We have some tips for optimum use of an external DS.

2. cgiVarVal parsing procedure (for input string read via getInput procedure)

Parsing procedure cgivarval lets you retrieve fields from the input string one at a time into program-defined fields.

Example:

 * Prototype definitions and standard system API error structure
 /copy mysrclib/qrpglesrc,prototypeb
 /copy mysrclib/qrpglesrc,usec
D InData          s          32767          Area to accept input
D InActLn         s             10i 0       Actual length Rcvd
D ReqMethod       s              4          Returns GET or POST
            ... etc. ...
 * Client input variables
D custname        s             40
D emailadd        s             40
D state           s              2
            ... etc. ...
 * Get input data from POST or GET.
C                   callp     getinput(indata:inactln:ReqMethod)
 * Parse variables from input
 *
 * Customer name
C                   eval      custname = cgivarval('custname':1:InData:
C                             InActLn:rc)
 * E-mail address
C                   eval      emailadd = cgivarval('emailadd':1:InData:
C                             InActLn:rc)
 * State
C                   eval      state = cgivarval('state':1:InData:
C                             InActLn:rc)

For a complete example see the source of program TEMPLATE2.

3. "zhbGetVar" parsing procedure (for input string read via ZhbGetInput 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.

Example:

 * Prototype definitions and standard system API error structure
 /copy mysrclib/qrpglesrc,prototypeb
 /copy mysrclib/qrpglesrc,usec
 * Number of variables
DnbrVars          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. ...
 * Get input
C                   eval      nbrVars =
C                             zhbgetinput(savedquerystring:qusec)
 * Parse variables from QUERY_STRING environment variable:
 * Customer name
C                   eval      custname = zhbgetvar('custname')
 * E-mail address
C                   eval      emailadd = zhbgetvar('emailadd')
 * State
C                   eval      state = zhbgetvar('state')

For a complete example see the source of program TEMPLATE3.

3. "zhbGetVarPtr" parsing procedure (for input string read via ZhbGetInput 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 .

Example:

 * Prototype definitions and standard system API error structure
 /copy mysrclib/qrpglesrc,prototypeb
 /copy mysrclib/qrpglesrc,usec
 * Number of variables
DnbrVars          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. ...
 * Get input
C                   eval      nbrVars =
C                             zhbgetinput(savedquerystring:qusec)
 * Retrieve the pointer to input variable named 'longstring':
C                   eval      occurrence = 1
C                   eval      ReturnVarP = zhbGetVarPtr('longstring':
C                             occurrence:
C                             varLenOut)

Note. Do not use this subprocedure for reading a file being uploaded from the browser. Instead, use Giovanni Perotti's FUPLOAD utility (see http://www-922.ibm.com/easy400h/fupload.htm)

4. Other zhbGet... subprocedures available when using zhbGetInput:

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
 * Get input
C                   eval      nbrVars =
C                             zhbgetinput(savedquerystring:qusec)
 * Example of retrieving
 * the number of occurrences of all variables in the CGI input
C                   eval      nbrInpVars = ZhbCountAllVars
 * Example of retrieving
 * detailed information for all the input variables
C                   if        nbrInpVars > 0
C     1             do        nbrInpVars    ThisOccur
C                   eval      ThisVarVal =
C                             ZhbGetVarDetails(ThisOccur:
C                             ThisVarName:
C                             ThisVarOccur:
C                             FoundInd)
C                   enddo
C                   endif

4. Receiving names of input variables (for input string read via ZhbGetInput procedure)

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:

ZhbGetInput
ZhbCountAllVars
ZhbGetVarDetails