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.
CGI programs can be built using named activation groups by specifying a name on the ACTGRP parameter of the CRTPGM or CRTSRVPGM commands. In doing this, the initial call to the program within the job will still have the startup cost of activating the program. However, an activation group is left active after the program has exited normally. All storage associated with that program is still allocated and in ″last-used″ state. The program is not initialized when it is called again. In addition, for the ILE C runtime, all settings are in ″last-used″ state, such as signal(), strtok(). The RCLACTGRP command is used to end a named activation group. Use the DSPJOB OPTION(*ACTGRP) command to display all the activation groups for the job. All ILE languages running on the server can use this mechanism to enable persistence for their CGI programs.
For additional information about activation groups see the ILE Concepts, SC41-5606 book.
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.
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 time-out, a message is logged in the error log of the server.
You should be aware of the following considerations when using persistent CGI programs:
The program example located under Developer Resources, http://www.ibm.com/eserver/iseries/http , displays a counter that is increased each time the Persistent CGI program is called.