The C$GETCGI routine retrieves CGI (Common Gateway Interface) variables.
CALL "C$GETCGI"
USING VARIABLE-NAME, DEST-ITEM, VALUE-INDEX
GIVING VALUE-SIZE
| 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, then 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. |
This library routine is intended to be called from COBOL CGI scripts to retrieve CGI variables from either the environment or the standard input stream, stdin.
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, such as the case where multiple items have been selected from a choose-many list.
The size of the resulting value is returned in the special RETURN-CODE register. This may be 0 to indicate that the variable has no value or -1 to indicate that the variable does not exist. The value of RETURN-CODE is moved to VALUE-SIZE.
The value is truncated to the size of the destination item.
You may use C$GETCGI instead of or in combination with external forms. Use C$GETCGI if you must know the exact size of a CGI variable or if you are converting an existing COBOL CGI program.