8.3.2.3 Using the C$GETCGI routine

The C$GETCGI library routine 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'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, 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 sections of your program.

Parameter Type Description
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", the data is read from the "QUERY_STRING" environment variable. If the REQUEST_METHOD is "POST", 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.

Please note that when some browsers encounter multiple-line entry fields (also known as HTML TEXTAREAS), they send a carriage return line feed sequence to the CGI program. If a carriage return is not desired, as in operating systems that automatically terminate text lines with line feed characters, you can have them removed by using the CGI_STRIP_CR runtime configuration variable.

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.

Parameter	Type	Description
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.