Writing persistent CGI programs

Persistent CGI is an extension to the CGI interface that allows a CGI program to remain active across multiple browser requests and maintain a session with that browser client. This allows files to be left open, the state to be maintained, and long running database transactions to be committed or rolled-back based on end-user input.

The CGI program must be written using named activation groups which allows the program to remain active after returning to the server. The CGI program notifies the server it wants to remain persistent using the ″Accept-HTSession″ CGI header as the first header it returns. This header defines the session ID associated with this instance of the CGI program and is not returned to the browser. Subsequent URL requests to this program must contain the session ID as the first parameter after the program name. The server uses this ID to route the request to that specific instance of the CGI program. The CGI program should regenerate this session ID for each request. It is strongly recommended that you use Secure Sockets Layer (SSL) for persistent and secure business transaction processing.

Accept-HTSession CGI Header

This header specifies the session handle associated with this instance of the Persistent CGI program. This session handle is used to route back subsequent requests to that program and must be unique, or the server will not honor the persistence request. A message is logged in the error log of the server.

Accept-HTSession = "Accept-HTSession" ":" handle

When the server receives this header, the CGI job servicing the request will be reserved in a persistent state. Only requests coming in with that session handle in the URL are routed back to that instance of the CGI program. The URL must be in the following format:

/path/cgi-name/handle/rest/of/path

Where handle is an exact match of the handle provided in the ″Accept-HTSession″ CGI header for the program cgi-name.

Note: The cgi-name that is being resolved is the name as it appears in the URL. It is not necessarily the actual name of the program being started on the system. This is to remain consistent with the name resolution performed by the server.

HTTimeout CGI Header

The HTTimeout header is for the CGI program to define the amount of time, in minutes, that this CGI program wants to wait for a subsequent request. If not specified, the value specified on the PersistentCGITimeout directive is used. If specified, it takes precedence over the PersistentCGITimeout directive, but the server will not wait longer than the time specified on the MaxPersistentCGITimeout directive. This allows individual CGI programs to give users more time to respond to lengthy forms or explanations. However, it still gives the server ultimate control over the maximum time to wait.

HTTimeout = "HTTimeout" ":" minutes

The time-out value is a non-negative decimal integer, representing the time in minutes. This header must be preceded by an ″Accept-HTSession″ header, if not, it is ignored. If you omit the header, the default time-out value for the server is used. When a CGI program is ended because of a timeout, a message is logged in the error log of the server.

Considerations for using Persistent CGI Programs

You should be aware of the following considerations when using persistent CGI programs:

  • The web administrator can limit the number of persistent CGI programs that the server supports by using the MaxPersistentCGI configuration directive.
  • There are some job or thread-level resources that the server code running in the CGI job usually manipulates (directly or indirectly) on behalf of CGI programs. The following attributes will (potentially) change across calls:
    • Environment variables the server sets
    • Stdin/Stdout/Stderr file descriptors
    • User profile
    • Library list
  • The server will not set the rest of the job attributes set by the server, and therefore, will maintain state across calls if changed by the CGI program. Note, however, that the CGI program must restore the initial state of these values before ending its persistence in order to guarantee compatibility across subsequent server requests:
    • Job Language, Region, CCSID
    • Job Priority
    • Printer/Output Queue
    • Message Logging
    • Environment variables set by the CGI program
  • For added security, web server administrators can protect their persistent CGI programs using registered Internet users, thereby forcing authentication by the user before processing each request.

Persistent CGI Program Example

The Persistent CGI programming example located at CGI Programming examplesLink outside Information Center displays a counter that is increased each time the Persistent CGI program is called.