A CGI program to be invoked by the generic-CGI server class uses standard functions, such as C library functions, for access to the standard file environment.
A Pathway CGI application uses the CGI library for access to standard files.“CGI Procedures” (page 159)lists and describes the procedures in the CGI library.
Table 21 CGI Procedures
Description Procedure
This procedure decodes the name/value pairs encoded in form data returned by the POST request method or in the CGI_Capture()
QUERY_STRING returned by the GET request method, creates an environment variable for each name/value pair
Table 21 CGI Procedures(continued)
Description Procedure
and sets the value of the variable. CGI_Capture() might be called in lieu of placing the Region directive AddCGI AUTOMATIC_FORM_DECODING ON command in the server's configuration file.
This procedure is analogous to the feof() procedure in the C library: It tests for the end-of-file condition on a specified CGI_feof()
stream and returns a nonzero value if it encounters the end-of-file.
This procedure is analogous to the fgets() procedure in the C library. The CGI_fgets() function reads data from the CGI_fgets()
stream pointed to by the stream parameter into the array pointed to by the string parameter. Data is read until n-1 bytes have been read, a newline character is read, or an end-of-file condition is encountered. The string represented by the data is then terminated with a NULL character. This procedure is used as an entry point into a user-written CGI server class. The CGI environment changes on each CGI_main()
invocation of CGI_main. (See“Design Guidelines” (page 162).)
This procedure is analogous to the printf() procedure in the C library, with one exception: output is passed back to the CGI_printf()
CGI client program through the Pathway CGI interface rather than to the stdout file descriptor.
The maximum size of the write buffer (including expansion of elements such as integers) is 32000 bytes. If the printf string exceeds this size, the application terminates with an error message.
This procedure is analogous to the fread() procedure in the C library with the following exceptions:
CGI_fread()
Data is read from the Pathway CGI interface rather than from stdin, and stdin is the only file descriptor that this procedure might be called with.
This procedure is analogous to the write() procedure with the following exceptions: stdout is the only file descriptor CGI_fwrite()
that works with this procedure, and data is written to the Pathway CGI interface rather than to stdout.
This procedure immediately writes buffered data from a CGI program to a specified stream. If the stream specified CGI_fflush()
is stdout or stderr, this procedure immediately writes any buffered data to the httpd process and restarts the fflush timer.
This procedure specifies the interval at which stdout (really $RECEIVE simulating stdout) is flushed. To change a flush CGI_set_fflush_timer()
interval set by a call to CGI_set_fflush_timer(), the program must call CGI_set_fflush_timer() with seconds set to 0 (zero), and then call CGI_set_fflush_timer() with a nonzero value to set the new flush interval.
A call to this procedure supersedes the value of the TANDEM_CGI_SET_FFLUSH_TIMER in the server configuration.
The flush timer uses an signal handling routine that catches a SIGALARM signal. When the alarm signal is delivered to a process, it can interrupt long I/O operations, and cause an error. In this case, the errno variable is set to 4004 (interrupted system call). If you want your server to perform its own SIGALARM processing, set this value to 0.
Table 21 CGI Procedures(continued)
Description Procedure
Only a single alarm signal can be in effect for a process. If you need to implement a customized alarm function and still use the fflush timer, write an alarm signal handler that calls CGI_fflush() when appropriate.
This procedure gets a character from the CGI input stream. It is the same as the Posix function getc(), but returns the CGI_getc()
next byte from the CGI input stream specified and moves the file pointer, if defined, ahead 1 byte in the stream. This procedure writes a string to the CGI output stream. It operates in the same way as its Posix equivalent. CGI_puts()
This stub procedure is called whenever the connection between the CGI server and the httpd program is broken; CGI_connection_abort
usually, when the end user at the Web client stops an active data transfer prior to receiving all the data being sent, or when there is an internal timeout within the httpd server itself, in the case where a single connection has existed longer than its configured lifetime. An internal timeout might occur if the ScriptTimeout / InputTimeout /OutputTimeout values are configured. When an internal timeout occurs, httpd cancels the request, closes the connection, and sends a termination signal to the CGI process. The CGI library invokes the CGI_connection_abort procedure to handle the termination signal.
The intent of a user-coded connection abort routine is to allow for graceful cleanup of transactions in progress. This stub procedure is called each time the server comes up to allow user-written initialization code (such as opening CGI_initialize()
database files) to be executed at startup time. You must use this function in order to read environment variables. (See“Design Guidelines” (page 162).)
This stub procedure is called before the server stops to allow user-written cleanup code to be executed prior to process termination.
CGI_terminate