Guidelines for writing high availability CGIs

By understanding the guidelines for writing cluster-enabled CGIs, you can avoid potential problems with your CGI code.

All CGI programs existing today are cluster-disabled. A CGI program developer should follow the following rules when writing cluster-enabled CGI programs:

Write the CGI in such a way that running them with the same state more than once does not cause any problem.
Store the CGI program’s state between client’s requests only in the Web server.
Use only cluster-safe mechanisms. For example, if a CGI program uses shared memory (which is currently not a cluster-safe mechanism), the macro is almost certainly cluster-disabled.

Table 1. CGI problems and solutions. This table identifies potential problem areas and suggests a solution:
Potential problems	Solutions
When the stateful CGI is run with the same state more than once, its correctness is not ensured.	Rewrite the CGI so that it can run with the same state more than once.
The stateful CGI accesses shared memory.	Eliminate the use of shared memory.
The stateful CGI generates session handles ignoring session handles passed by the Web server.	Rewrite the CGI to use session handles passed by the Web server.

There are two categories of high availability Web server programming models to consider when writing high availability CGI programs or enabling an existing CGI program for use as a high availability CGI program. The two categories are:

Primary/backup
Peer model

For the primary/backup, follow these additional guidelines:

The stateful data is saved by the high availability CGI program by calling the QzhbCgiSendState API. To retrieve any stateful data that has been stored use the QzhbCgiRecvState API. The QzhbCgiRecvState API returns stateful information when the environment variable QZHBRECOVERY is set and QZHBHA_MODEL is equal to PRIMARYBACKUP. If the QZHBRECOVERY is not set, then the CGI program should not use the QzhbCgiRecvState API. You must write a persistent CGI that maintains the data in static variables. If the environment variable QZHBRECOVERY is set, retrieve the data using the QzhbCgiRecvState API and restore the static variables.

The Web server still limits the total number of persistent CGIs (both cluster-enabled and cluster-disabled ) using the MaxPersistentCGI directive.

For the Peer model, follow these additional guidelines:

The stateful data is saved by the high availability CGI program by calling the QzhbCgiSendState API. To retrieve any stateful data that has been stored use the QzhbCgiRecvState API. The QzhbCgiRecvState API must be used with each new request to retrieve any stateful data that has been stored for a previous high availability CGI program invocation. In this model your CGI program must not save stateful data in static variables.

If QZHBHA_MODEL is PUREPEER the CGI is expected to restore its state, to serve the request, and to return its new state to the Web server. When the Web server receives the new CGI’s state, it stores the state (which will be passed to the CGI with the subsequent request), returns the response to the client, and terminates the CGI job. Consider a cluster-enabled persistent CGI program. The concept of persistency is kept, but its implementation is absolutely changed. A cluster-enabled persistent CGI program does not stay in the CGI job during a session; it is invoked each time a request comes in. However, the concept of persistency is kept due to CGI’s state (and the state of the Web server regarding the CGI) stored in the CHT and always passed to the CGI program with subsequent requests.