Writing a CGI Program

Each element of your HTML, XML, or WML interface has a corresponding CGI variable. Your application must be able to interpret the CGI input data and return an appropriate response to the user. This is where your CGI program comes in.

Your CGI program must perform three basic functions:

Function	Description
Read CGI input data from the client	When a user enters information onto the form, that information is sent to the CGI program in the form of CGI data. Your program must be able to read CGI input data. In ACUCOBOL-GT, this is accomplished with the ACCEPT verb.
Process the input data and arrive at results	Typically, this involves either a calculation, database lookup, or file read, but it could involve a CALL to an existing COBOL program on a local or remote machine.
Generate output that can be read by the client browser	Minimally, this includes an HTTP response header with a URL pointer to the response data. Otherwise, the header may be followed by response data formatted in HTML, WML, or XML. In ACUCOBOL-GT, HTTP output is accomplished using the DISPLAY verb.

In the simplest case, your ACUCOBOL-GT CGI program can contain one ACCEPT statement and one DISPLAY statement. Even if your program is more complicated, it will always start with an ACCEPT and end with a DISPLAY. Few languages make CGI programming so simple.

When writing your CGI program, consider the following:

CGI programs must be written to be non-interactive. They take a set of input data, process it, and produce output.
While the CGI program is running, the user is waiting for a response in the Web browser. CGI programs should be kept small and do their job quickly to reduce the user wait time.
If users get tired of waiting and press the Stop button on their browsers, the Web server generally kills the CGI program. The output from the CGI program is discarded.
One of the limitations of CGI is that it does not automatically maintain any state information. It is the CGI programmer's responsibility to record state information in a file or database and then encode a "key" to that state information in the HTML, XML, or WML output.
For example, if a client invokes a CGI program to "log in" to your application or to add an item to his/her "shopping cart," the CGI program must record that fact along with any user identification information in a file or database. When the CGI program generates the output, it should encode a user ID or key in a CGI variable that will get passed to the next CGI program that the client invokes. The next CGI program can then look up the user state information (for example, shopping cart contents) from the database. The user state information should also include a date/time "stamp" so that a maintenance program can delete records for users who haven't logged on in a specified amount of time or who left the application without logging out.
If you choose to use ANSI style ACCEPT and DISPLAY statements instead of–or in addition to–the ACCEPT and DISPLAY external-form-item syntax described in this section, you must include the UPON SYSOUT phrase or else compile with the -Ca option. -Ca implies UPON SYSOUT for all ANSI DISPLAY statements.

With these considerations in mind, you are ready to write your CGI program. The following sections describe how to accomplish the necessary I/O and processing tasks. The topic Sample CGI Programs provides some sample code for your reference.