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:
Where handle is
an exact match of the handle provided in the ″
CGI header for the program
cgi-namethat 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
is used. If specified, it takes precedence over the
but the server will not wait longer than the time specified on the
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 ″
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 examples displays a counter that is increased each time the Persistent CGI program is called.