This CGI primer will help you to understand the basic concepts of CGI programming. We will examine how the different CGI methods makes use of the data stream communication which occurs between the web client, and the CGI session.
Brief Overview:
The GET METHOD is the simplest method of accepting data from the hypertext transport protocol(HTTP). A GET METHOD program will query the environment variable called QUERY_STRING. Query_string contains the complete data stream.
A POST METHOD CGI reads Xbytes directly from STDIN. The value of Xbytes is determined by the value stored in the environment variable called CONTENT_LENGTH.
Both methods are available through PlanetWide OS/2 Web Server, and each has its own advantages. Let us explore each method separately.
POST METHOD:
Programming for the POST METHOD is similar to coding for local operation on a PC, in that the CGI session has open access to all of the OS environment.
You are granted the ability to query all environment variables including CONTENT_LENGTH. This variable contains the number of bytes of data that you should read from STDIN.
Let's say that an HTML < FORM > is activating your POST Method CGI. The form contains certain fields that the web client may fill-in; FIRST_NAME, LAST_NAME and EMAIL_ADDRESS.
The user would key in the information like this:
FIRST_NAME: John
LAST_NAME: Smith
EMAIL_ADDRESS: jsmith@company.com
Of course, your CGI program would read this data, and it appears nothing like what you woud think. The STDIN data stream is just that, a continuous stream of data.
NOTE: No matter how the web client terminates the stream, you only need to read the first Xbytes and do not touch the termination character(s). Done! almost...
POST Query example:
int len;
len=atoi(getenv("Content_Length"));
Integer (len) will now contain the exact number of bytes that you
must read into your buffer array.
CONTENT_LENGTH representing the previous field entries will be equal to
64.
See how we get this number from the next step.
POST read example:
The data stream is easily captured by using the getchar() function. Since the STDIN data stream is already open to you, read it as if it were a series of keyboard strokes; (but you already know how many bytes to read).
for(i=0;i < len;i++) buffer[i]=getchar();
buffer[i]=0;
Array buffer[ ]; will now contain the data from the STDIN stream.
FIRST_NAME=John&LAST_NAME=Smith&EMAIL_ADDRESS=jsmith@company.com
If you count the characters in the buffer stream, it totals 64 bytes. The '&' character is the field separator. Further on, in your CGI program, replace the '&' character with a blank-space character(dec 32) to help you parse buffer[ ] into individual data fields.
This is a basic outline of the POST METHOD accessing the CGI interface. A sample program demonstrating how to write complete POST code in C is provided with more explanation. (see the post tutorial to learn more).
GET METHOD:
Programming for the GET METHOD is so close to the coding for POST, you would have a tough time deciding why you would prefer one method over the other. Follow along and decide for yourself.
As in the POST method, GET has full access to the environment variables in your CGI session; but this is where we draw the line between the two. The environment variable called QUERY_STRING contains the entire data stream from the web client.
For comparison, we will use the same example as we used above in the POST METHOD. Your GET CGI is initiated by an HTML < FORM >. The form contains certain fields that the web client may fill-in; FIRST_NAME, LAST_NAME and EMAIL_ADDRESS.
The user would key in the information like this:
FIRST_NAME: John
LAST_NAME: Smith
EMAIL_ADDRESS: jsmith@company.com
GET read example:
The data stream is simple to capture, but with less stress. The first thing we do is allocate a char*(pointer) and aim it at the Query_String environment variable. You must then query the length of the string... Like this:
int len;
char *cp;
cp=getenv("QUERY_STRING");
len=strlen(cp);
Now that the pointer is established, and you know how big it really is, it's time to fill your input buffer[]. The GET code is quite similar to POST at this point.
for(i=0;i < len;i++) buffer[i]=cp[i];
buffer[i]=0;
Keep in mind that the data is still a single stream. Again you should note that the stream is terminated by the web client, but we don't actually read the termination character. So far, the only difference between the two CGI methods is the way in which a data stream is presented to your program. A matter of only a few lines of code; WOW!. The rest of your code to parse your stream is completely portable between the methods.
Array buffer[ ]; now contains the data from the STDIN stream. Identical to the POST Method data stream!
FIRST_NAME=John&LAST_NAME=Smith&EMAIL_ADDRESS=jsmith@company.com
If you count the characters in the buffer stream, it totals 64 bytes. The '&' character is the field separator. Further on, in your CGI program, replace the '&' character with a blank-space character(dec 32) to help you parse buffer[ ] into individual data fields.
Now you should have a pretty good idea of how to code your GET CGI programs. A sample program demonstrating how to write complete GET code in C is provided with more explanation. (see the get tutorial to learn more).
CGI Terms, Definitions & Considerations:
This is due to the method in
which OS/2 delivers a stream of data.
The http client will not accept data that is incorrectly terminated or
missing proper termination.