CGI Query Acception and Form Submission

Usually, a CGI program receives two types of the information from the browser:

1. Information about the browser (its type, what it can view, the remote host name, and so on), the server (its name and version, the port it's running on, and so on), and the CGI program itself (the program name and where it's located). The server provides all of this information to the CGI program through environment variables.
2. Information entered by the user. This information, after first being encoded by the browser, is sent either through an environment variable (the GET method) or through the standard input (stdin- the POST method).

Here are the descriptions of some of the important CGI environment variables:

• QUERY_STRING

  QUERY_STRING contains the input to a CGI application that is invoked with the GET method. The input string is URL-encoded (spaces replaced by plus signs, several characters escaped). Each piece of data being sent to the CGI application is sent in "key=value" form. If the POST method is used, QUERY_STRING will be empty.

• CONTENT_TYPE

  CONTENT_TYPE gives the MIME types of data sent to a CGI application that is invoked using the POST method. When the CGI application is invoked using the GET method, the CONTENT_TYPE enviornment variable is blank. A typical value for the CONTENT_TYPE environment variable is application/x-www-form-urlencoded.

• CONTENT_LENGTH

  CONTENT_LENGTH gives the length in bytes of data sent to a CGI application that is invoked using the POST method. When the CGI application is invoked using the GET method, the COPNTENT_LENGTH enviornment variable is blank.

• PATH_INFO

  PATH_INFO gives extra path information as it was passed to the server in the query URL.

• REMOTE_ADDR

  REMOTE_ADDR gives the IP address of the client that made the request.

• REMOTE_HOST

  REMOTE_HOST gives the name of the remote computer that made the request.

• REQUEST_METHOD

  REQUEST_METHOD gives the name of the method used to invoke the CGI application. Valid values are GET and POST.

• SCRIPT_NAME

  SCRIPT_NAME gives the name of the script that was invoked, for instance, /cgi-bin/hello.cgi.

• SERVER_PORT

  SERVER_PORT gives the TCP port number on which the server that invoked the CGI application is operating, for instance, 80 (the default HTTP port number).

• SERVER_PROTOCOL

  SERVER_PROTOCOL gives the name of the protocol that server is using and the version of the protocol. For instance, HTTP/1.0.

• SERVER_NAME

  SERVER_NAME is the domain name of the computer that is running the server software, for instance, www.cba.uh.edu

Encoding Scheme

Form data consists of a list of name/value pairs. Before transmitting this data to the server and the CGI program, the browser encodes the information using a scheme called URL encoding (specified by the MIME type application/x-www-form-urlencode). The encoding scheme consists of the following:

• URL encoding certain non-alphanumeric characters. This process consists of replacing these characters with a percent sign followed by the hexadecimal value of the character. Some of these characters and their corresponding hexadecimal values are here:

  Chracter	Hexadecimal Value
  Tab	09
  Space	20
  "	22
  (	28
  )	29
  ,	2C
  ;	3B
  @	40

• Replacing spaces with the plus sign (+).
• Separating each name and value with an equal sign (=).
• Separating each name/value pair with an ampersand (&).

For example, suppose you have the following name/value pairs:

     name    Zhanshou Yu
     major   Computer Science  
     e-mail  zyu@bayou.uh.edu

In order to encode these pairs, first replace the non-alphanumeric characters. In this example, only one charater exists,@, which is replaced with %40. So we have:

     name    Zhanshou Yu
     major   Computer Science  
     e-mail  zyu%40bayou.uh.edu

     name    Zhanshou+Yu
     major   Computer+Science  
     e-mail  zyu%40bayou.uh.edu

Seperate each name and value with an equal sign:

     name=Zhanshou+Yu
     major=Computer+Science  
     e-mail=zyu%40bayou.uh.edu

Finally, separate each pair with an ampersand (&):

name=Zhanshou+Yu&major=Computer+Science&email=zyu%40bayou.uh.edu

The CONTENT_LENGTH is equal to the number of character in the coding string. This example has 64 characters, so the CONTENT_LENGTH is 64.

Submission Method

• Method = POST

  For POST method, user input information is retrieved from standard input (STDIN) using the CONTENT_LENGTH environment variable. Here is one example:

   
     Enter string:         
  

  Here is the HTML FORM code:

  <form method=post action="cgi-bin/post.pl"> 
     Enter string:   <INPUT NAME="name" TYPE="TEXT" SIZE="20" MAXLENGTH="30">  
  <INPUT TYPE="SUBMIT" VALUE="Send">     <INPUT TYPE="RESET"></form>
  

  Here is the CGI script in PERL (Pay attention to the bold line, which gets the input from the user):

  #!/usr/local/bin/perl
  #-------------------------------------------
  # post.pl by Zhanshou Yu
  #-------------------------------------------
  
  # Get the input for POST method
   read(STDIN,$buffer,$ENV{'CONTENT_LENGTH'});
  
  #Split the name-value pairs
   ($name,$value)=split(/=/,$buffer);
  
  # Substitute special character to its original character
   $value=~ tr/+/ /;
   $value=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
  
  #------print the return HTML------------------
  
   #print the MIME type
   print"Content-type: text/html\n\n";
  
   #print the HTML body
   print"<html>\n";
   print "<head><title>Input For POST method </title></head>\n";
   print "<body><center><h1>Input for POST Method </h1>\n";
   print "<h2>Here is the string you just input:    $value</h2>\n";
   print "</body></html>\n";
   exit;
  

• Method = GET

  In the GET method, user input information is retrieved using QUERY_STRING environment variable.

  Here is the example:

  Enter string:

  Here is the HTML FORM code:

  <form method=get action="cgi-bin/get.pl"> 
     Enter string:   <INPUT NAME="name" TYPE="TEXT" SIZE="20" MAXLENGTH="30">  
  <INPUT TYPE="SUBMIT" VALUE="Send">     <INPUT TYPE="RESET"></form>
  

  Here is the CGI script in PERL :

  #!/usr/local/bin/perl
  #-------------------------------------------
  # get.pl by Zhanshou Yu
  #-------------------------------------------
  
  # Get the input for the GET method
   $buffer=$ENV{'QUERY_STRING'};  
  
  #Split the name-value pairs
   ($name,$value)=split(/=/,$buffer);
  
  # Substitute any special character with its original character
   $value=~ tr/+/ /;
   $value=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
  
  #------print the return HTML------------------
  
   #print the MIME type
   print"Content-type: text/html\n\n";
  
   #print the HTML body
   print"<html>\n";
   print "<head><title>Input For GET method </title></head>\n";
   print "<body><center><h1>Input for GET Method </h1>\n";
   print "<h2>Here is the string you just input:    $value</h2>\n";
   print "</body></html>\n";
   exit;
  

Just look at the above two bold input lines (it doesn't matter if you do not understand other statements right now). The POST method using:

 read(STDIN,$buffer,$ENV{'CONTENT_LENGTH'});

to read the input data from standard input to a buffer. The length is specified by the enviroment variable CONTENT_LENGTH. If you are a C language programmer, the following C code can do the same work :

 char *buffer;
 char *contentLength=getenv("CONTENT_LENGTH");
 int length=atoi(contentLength);
 buffer=(char *)malloc(length+1);
 fread(buffer,1,length,stdin);

 $buffer=$ENV{'QUERY_STRING'};  

or you can write in C code:

 char *buffer=getenv("QUERY_STRING");