The C$GETCGI library routine (available in ACUCOBOL-GT Version 4.0 or later) retrieves CGI variables from the environment or the standard input stream, "stdin" like other types of COBOL CGI programs. The C$GETCGI routine should be used by those with existing COBOL CGI programs to retrieve CGI variables as normal while incrementally converting to ACUCOBOL-GT Version 4.0's external form method of CGI data retrieval. Although "ACCEPT from stdin" and "ACCEPT external-form-item" cannot be used together, you may use C$GETCGI instead of or in combination with external forms. The C$GETCGI routine retrieves the exact size of a CGI variable.
To use C$GETCGI, you would include a CALL in your CGI program using the following syntax:
CALL "C$GETCGI" USING VARIABLE-NAME, DEST-ITEM, VALUE-INDEX GIVING VALUE-SIZE
Where the following are defined in the working storage or data division section of your program.
| VARIABLE-NAME
| PIC X(n)
| Contains the name of the CGI variable. |
| DEST-ITEM
| PIC X(n)
| Receives the value of the given CGI variable. |
| VALUE-INDEX
| Numeric value
| Contains the CGI value index. This optional parameter contains an index that
is used when a CGI variable has multiple values in the CGI input data. This
typically happens when multiple items have been selected from a "choose-many"
list box. For example, to receive the third selected value, pass 3 for
VALUE-INDEX. If VALUE-INDEX is greater than the total number of values in the input
stream for the given CGI variable, spaces are moved to DEST-ITEM. |
| VALUE-SIZE
| Signed numeric value
| Receives the size of the resulting value. This may be "0" to indicate that
the variable exists but has no value or "-1" to indicate that the variable does
not exist. |
C$GETCGI automatically determines whether to read the CGI variable from the environment or "stdin" depending on the value of the "REQUEST_METHOD" environment variable which is set by the Web Server. The first time C$GETCGI is called, it reads all of the CGI variables and values into a variable length buffer. If REQUEST_METHOD is "GET" then the data is read from the "QUERY_STRING" environment variable. If the REQUEST_METHOD is "POST" then it is read from "stdin".
Each time C$GETCGI is called, it searches for the variable name passed in the first parameter, translates the value from CGI format into standard format, and moves the result to the destination item passed in the second parameter. An optional third parameter specifies a CGI value index. This index is used when a CGI variable has multiple values in the CGI input data as in the case where multiple items have been selected from a "choose-many" list.