Support : Guides

CGI Input

Accessing the input parameters passed to a web CGI module is the beginning process of all typical CGI modules. To understand how parameters are passed in it is important to recognize how web CGI modules are invoked in the first place. How a web CGI modules is invoked determines how the input parameters are passed as well as how to access them.

Methods of Web CGI Invocation

There are two "methods" of web CGI invocation. There is the "GET" method and the "POST" method.

Typically the "GET" method is used for all web page hyperlinks coded with the HTML anchor tag "<a href="...">...</a>". The "href" points to the web server that receives the request and also points to the resources being requested. For invocation of a web CGI the "href" value would point to the web CGI module with its output being the resource being requested; i.e., "href="/cgi-bin/test.cgi". To pass a parameter to "test.cgi" a question mark (?) is used to delimit (or differentiate) it from the web CGI module name. Then, following the "?" is one of more parameter name and value pair; i.e., "?item=ABC+qty=2". Notice the plus sign "+" is used to delimit the first and second parameter name value pair.

Typically the "POST" method is used for HTML Forms, but it is not restricted to just forms. The same parameter name value pair relationship exists with the POST method, as with the GET method, with each parameter being specified within the context of the HTML Form Elements.

The most significant difference between the GET and POST methods is how the web server makes the input parameter data available. With the GET method the data is placed in an Environment Variable called "QUERY_STRING". As opposed to the POST method where the data is loaded into the STDIN (Standard Input) stack and the length of the data element being stored in the Environment Variable called "CONTENT_LENGTH".

For both methods, the parameter data is "packaged" for safe cross-platform transmission. This means that upon receipt of the parameter data the packet must be unpacked to put it back into platform specific format; on most non-Mainframe systems ASCII format.

Determining which method was used to invoke the web CGI can be accomplished by testing the "CONTENT_LENGTH" Environment Variable.

Here is a PERL example of accessing input passed to a web CGI module. The data is retrieved, parsed, then placed in an associative (hash) array named "$input{}":

my %input;
sub parse_input {
	my $buffer;
    if ( $ENV{ CONTENT_LENGTH } ) {
        read( STDIN, $buffer, $ENV{ CONTENT_LENGTH } );
    }
    else {
        $buffer = $ENV{ QUERY_STRING };
    }
    foreach ( split(/&/,$buffer) ) {
        my ( $name, $value ) = split( /=/ );
        $value =~ tr/+/ /;
        $value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
        $input{ $name } = $value;
    }
}

Types of Web CGI Input

There are a variety of data formats that can be passed to a web CGI module. The obvious is "text". The not so obvious are binary data formats. These can include graphic image files, executable programs, database components and other data items that must have their content and format preserved without platform specific conversion. This requires special processing to preserve the content of the input being passed in. This is done by changing the mode of access to STDIN; as shown in the code snippet below

if (index($ENV{CONTENT_TYPE},"application/x-www-form-urlencoded") != -1) {
    read(STDIN, $buffer, $ENV{CONTENT_LENGTH});
    @pairs = split(/&/,$buffer);
} elsif (index($ENV{CONTENT_TYPE},"multipart/form-data") != -1) {
    binmode(STDIN);
    read(STDIN, $buffer, $ENV{CONTENT_LENGTH});
    ...