Module mod_cgi

Module mod_cgi supports directives for the IBM® HTTP Server for i Web server.

Summary

The module mod_cgi provides for execution of CGI scripts. Any file that has the handler cgi-script will be treated as a CGI script, and run by the server, with its output being returned to the client. Files acquire this handler either by having a name containing an extension defined by the AddHandler directive, or by being in a ScriptAlias directory.

When the server invokes a CGI script, it will add a variable called DOCUMENT_ROOT to the environment. This variable will contain the value of the DocumentRoot configuration variable.

For backward-compatibility, the cgi-script handler will also be activated for any file with the mime-type application/x-httpd-cgi. The use of the magic mime-type is deprecated.

CGI Environment variables

The server will set the CGI environment variables as described in the CGI specification Link outside Information Center with the following provisions. See Environment variables set by HTTP Server for a list of environment variables.

REMOTE_HOST: This will only be set if HostNameLookups is set to double (it is off by default), and if a reverse DNS lookup of the accessing hosts address indeed finds a host name.

REMOTE_IDENT: This will only be set if IdentityCheck is set to on and the accessing host supports the ident protocol.
Note: The contents of this variable cannot be relied upon because it can easily be faked. If there is a proxy between the client and the server, the variable is not useful.

REMOTE_USER: This will only be set if the CGI script is subject to authentication.

This module also leverages the core functions ap_add_common_vars and ap_add_cgi_vars to add environment variables like:

DOCUMENT_ROOT: Set with the content of the related DocumentRoot directive.

SERVER_NAME: The fully qualified domain name related to the request.

SERVER_ADDR: The IP address of the Virtual Host serving the request.

SERVER_ADMIN: Set with the content of the related ServerAdmin directive.

For an exhaustive list it is suggested to write a basic CGI script that dumps all the environment variables passed by HTTP Server in a convenient format.

CGI Debug

Debugging CGI scripts has traditionally been difficult, mainly because it has not been possible to study the output (standard output and error) for scripts which are failing to run properly. However, the HTTP Server runs CGI programs in previously started jobs (not prestart jobs) and it also reuses these jobs to run many CGI program invocations. Therefore, debugging your CGI program is simple. You simply need to find the job that runs CGI programs. It will have a jobname the same as the server instance name. The joblog will contain either HTP2001 or HTP2002 indicating whether it is a CGI single threaded only job, or a CGI multi-thread capable job. If you use a dedicated server instance, when you invoke your CGI from a browser, the first job in the WRKACTJOB list for CGI, will be the job chosen to run the CGI request. Therefore, you can use STRSRVJOB against this job and STRDBG against your CGI program. From here, you have full debug capabilities provided with the IBM i debugger. You can also use standard error (stderr) for debug information. The debug information written to STDERR is written to the ScriptLog if one is configured or to the ErrorLog if a ScriptLog is not configured. The ScriptLog and ErrorLog are both created with CCSID 1208 UTF-8. For CGI conversion mode EBCDIC, debug information is assumed to be in the CCSID of the CGI job. The logging process handles the conversion from CGI job CCSID to UTF-8. For CGI converison mode BINARY, debug information is written as is.

ScriptLog Format

When configured, the ScriptLog logs any CGI that does not execute properly. Each CGI script that fails to operate causes several lines of information to be logged. The first two lines are always of the format:

%% [time] request-line 
%% HTTP-status CGI-script-filename

If the error is that CGI script cannot be run, the log file will contain an extra two lines:

%%error 
error-message

Alternatively, if the error is the result of the script returning incorrect header information (often due to a bug in the script), the following information is logged:

%request 
All HTTP request headers received 
POST or PUT entity (if any) 
%response 
All headers output by the CGI script 
%stdout 
CGI standard output 
%stderr 
CGI standard error

Note: The %stdout and %stderr parts may be missing if the script did not output anything on standard output or standard error

Directives

CGIConvMode
CgiInitialUrl
CGIJobCCSID
CGIJobLocale
CGIMultiThreaded
CGIRecyclePersist
MaxCGIJobs
MaxPersistentCGI
MaxPersistentCGITimeout
MaxThreadedCGIJobs
PersistentCGITimeout
ScriptLog
ScriptLogBuffer
ScriptLogLength
StartCGI
StartThreadedCGI
ThreadedCgiInitialUrl

CGIConvMode

Module: mod_cgi
Syntax: CGIConvMode `mode`
Default: CGIConvMode EBCDIC
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: FileInfo
Origin: IBM
Example: CGIConvMode BINARY

The CGIConvMode directive is used to specify the conversion mode that your server will use when processing CGI programs.

Parameter: mode

Valid modes include the following:
Table 1. Valid conversion modes

Mode Description

EBCDIC The server converts everything into the EBCDIC CCSID of the CGI job. If the directive CGIJobCCSID exists, it has precedence in its context over the job CCSID of the server. The server assumes the header output and encoded characters "%xx" are in the EBCDIC CCSID of the CGI job. The server assumes that the body output is in the EBCDIC CCSID of the CGI job unless specified otherwise using the Content-type header.

EBCDIC_JCD The server will use the Japanese Codepage Detection utility to determine which Japanese ASCII CCSID to convert from. Otherwise, this option is the same as the EBCDIC option.

BINARY The server performs no conversion on QUERY_STRING or STDIN data. Environment variables are encoded in the CGI job's EBCDIC CCSID.
The server expects the header output and encoded characters "%xx" in ASCII. The server assumes that the body output is in ASCII unless specified otherwise using the Content-type header. This differs from no parse header CGI in that the server will still build the HTTP headers and perform conversion on the body output if necessary.

The following modes are used for compatibility with IBM HTTP Server (original).
Table 2. Legacy conversion modes

Mode Description

%%MIXED/MIXED%% The server converts CGI environment variables to EBCDIC CCSID 37, including QUERY_STRING. The server converts STDIN data to the CCSID of the server job. However, the encoded characters "%xx" are still represented by the EBCDIC 37 representation of the ASCII 819 octet. The server expects the header output to be in EBCDIC CCSID 37. However, the encoded characters "%xx" must be represented by the EBCDIC 37 representation of the ASCII 819 octet. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).

%%EBCDIC/MIXED%% The server converts everything into the EBCDIC CCSID of the job. In addition, the server converts escaped octets from ASCII to EBCDIC. The server expects the header output to be in EBCDIC CCSID 37. However, the encoded characters "%xx" must be represented by the EBCDIC 37 representation of the ASCII 819 octet. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).

%%BINARY/MIXED%% The server converts environment variables into the EBCDIC CCSID of the job, but performs no conversions on either QUERY_STRING or STDIN data. The server expects the header output to be in EBCDIC CCSID 37. However, the encoded characters "%xx" must be represented by the EBCDIC 37 representation of the ASCII 819 octet. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).

%%EBCDIC_JCD/MIXED%% The server uses the Japanese Codepage Detection utility to determine which Japanese CCSID to convert from. Otherwise, this option is the same as the %%EBCDIC/MIXED%% option.

%%EBCDIC/EBCDIC%% The server converts everything into the EBCDIC CCSID of the job. In addition, the server converts escaped octets from ASCII to EBCDIC. The server expects the header output and encoded characters "%xx" to be in EBCDIC CCSID 37. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).

%%BINARY/BINARY%% The server converts environment variables into the EBCDIC CCSID of the job, but performs no conversions on either QUERY_STRING or STDIN data. The server expects the header output and encoded characters "%xx" to be in ASCII 819. The server assumes that the body output is in ASCII 819 unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).

%%BINARY/EBCDIC%% The server converts environment variables into the EBCDIC CCSID of the job, but performs no conversions on either QUERY_STRING or STDIN data. The server expects the header output and the encoded characters "%xx" to be in EBCDIC CCSID 37. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header.

%%EBCDIC_JCD/EBCDIC%% The server uses the Japanese Codepage Detection utility to determine which Japanese CCSID to convert from. Otherwise, this option is the same as the %%EBCDIC/EBCDIC%% option.

Table 1. Valid conversion modes
Mode	Description
EBCDIC	The server converts everything into the EBCDIC CCSID of the CGI job. If the directive CGIJobCCSID exists, it has precedence in its context over the job CCSID of the server. The server assumes the header output and encoded characters "%xx" are in the EBCDIC CCSID of the CGI job. The server assumes that the body output is in the EBCDIC CCSID of the CGI job unless specified otherwise using the Content-type header.
EBCDIC_JCD	The server will use the Japanese Codepage Detection utility to determine which Japanese ASCII CCSID to convert from. Otherwise, this option is the same as the EBCDIC option.
BINARY	The server performs no conversion on QUERY_STRING or STDIN data. Environment variables are encoded in the CGI job's EBCDIC CCSID. The server expects the header output and encoded characters "%xx" in ASCII. The server assumes that the body output is in ASCII unless specified otherwise using the Content-type header. This differs from no parse header CGI in that the server will still build the HTTP headers and perform conversion on the body output if necessary.

Table 2. Legacy conversion modes
Mode	Description
%%MIXED/MIXED%%	The server converts CGI environment variables to EBCDIC CCSID 37, including QUERY_STRING. The server converts STDIN data to the CCSID of the server job. However, the encoded characters "%xx" are still represented by the EBCDIC 37 representation of the ASCII 819 octet. The server expects the header output to be in EBCDIC CCSID 37. However, the encoded characters "%xx" must be represented by the EBCDIC 37 representation of the ASCII 819 octet. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).
%%EBCDIC/MIXED%%	The server converts everything into the EBCDIC CCSID of the job. In addition, the server converts escaped octets from ASCII to EBCDIC. The server expects the header output to be in EBCDIC CCSID 37. However, the encoded characters "%xx" must be represented by the EBCDIC 37 representation of the ASCII 819 octet. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).
%%BINARY/MIXED%%	The server converts environment variables into the EBCDIC CCSID of the job, but performs no conversions on either QUERY_STRING or STDIN data. The server expects the header output to be in EBCDIC CCSID 37. However, the encoded characters "%xx" must be represented by the EBCDIC 37 representation of the ASCII 819 octet. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).
%%EBCDIC_JCD/MIXED%%	The server uses the Japanese Codepage Detection utility to determine which Japanese CCSID to convert from. Otherwise, this option is the same as the %%EBCDIC/MIXED%% option.
%%EBCDIC/EBCDIC%%	The server converts everything into the EBCDIC CCSID of the job. In addition, the server converts escaped octets from ASCII to EBCDIC. The server expects the header output and encoded characters "%xx" to be in EBCDIC CCSID 37. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).
%%BINARY/BINARY%%	The server converts environment variables into the EBCDIC CCSID of the job, but performs no conversions on either QUERY_STRING or STDIN data. The server expects the header output and encoded characters "%xx" to be in ASCII 819. The server assumes that the body output is in ASCII 819 unless specified otherwise using the Content-type header. The header most affected by this value is the location header (for example, to send a plus sign '+' in the location header you would send %).
%%BINARY/EBCDIC%%	The server converts environment variables into the EBCDIC CCSID of the job, but performs no conversions on either QUERY_STRING or STDIN data. The server expects the header output and the encoded characters "%xx" to be in EBCDIC CCSID 37. The server assumes that the body output is in the default CCSID of the server job unless specified otherwise using the Content-type header.
%%EBCDIC_JCD/EBCDIC%%	The server uses the Japanese Codepage Detection utility to determine which Japanese CCSID to convert from. Otherwise, this option is the same as the %%EBCDIC/EBCDIC%% option.

CgiInitialUrl

Module: mod_cgi
Syntax: CgiInitialUrl `url userid`
Default: none
Context: server config
Override: none
Origin: IBM
Example: CgiInitialUrl /qsys.lib/qsyscgi.lib/db2www.pgm/mymacros/macro.ndm/initial *
Example: CgiInitialUrl /qsys.lib/cgi.lib/mycgi.pgm QTMHHTP1
Example: CgiInitialUrl /QOpenSys/mypacedir/pacecgi USER1
Example: CgiInitialUrl /qsys.lib/cgi.lib/mycgi.pgm?init=yes
Example: /IASP1/qsys.lib/cgi.lib/mycgi.pgm USER2

This directive is used to load and initialize CGI programs when the server starts. At server startup, when we are processing the StartCgi directive, we are starting jobs to run CGI programs in. This new directive will enable the server to run a CGI request to the CGI job enabling the CGI program to be loaded and initialized. This is beneficial for Net.Data® users and other CGI programs built to use "named" activation groups. The initialization of the "named" activation group is a performance issue that the first user of the CGI job has to endure. This function will enable the performance issue to be moved to when the server starts, so the first user does not have to pay the performance penalty.

If there are no StartCgi directives, an error will be posted and the server will not start.

Parameter One: url

The url parameter value is actually the physical path URL, not the logical path URL. It should not be fully qualified (do not use http://system:port/). It must start with a / and contains the physical path to the CGI program and any path info needed by the CGI program, including query-string. If a URL is specified that is not valid, the server will not start.

Parameter Two: userid

The userid parameter value is either a valid IBM i userid or * where * means all of the userids specified on the StartCgi directive. To check for valid values, follow the rules for IBM i user profiles. The userid is optional.

CGIJobCCSID

Module: mod_cgi
Syntax: CGIJobCCSID `cgi-job-character-set-identification-number`
Default: CGIJobCCSID `Dependent upon server-character-set-identification-number`
Context: server config, virtual host, directory, not in limit, .htaccess
Override: none
Origin: IBM
Example: CGIJobCCSID 37
Example: To run one CGI program in CCSID 37 (English): ScriptAlias /cgi-english/ /QSYS.LIB/ENGLISH.LIB/ <Directory /QSYS.LIB/ENGLISH.LIB/> Allow From all Options +ExecCGI DefaultNetCCSID 819 CGIJobCCSID 37 CGIConvMode EBCDIC </Directory>
Example: To run a different CGI program in CCSID 284 (Spanish): ScriptAlias /cgi-spanish/ /QSYS.LIB/SPANISH.LIB/ <Directory /QSYS.LIB/SPANISH.LIB/> Allow From all Options +ExecCGI DefaultNetCCSID 819 CGIJobCCSID 284 CGIConvMode EBCDIC </Directory>
Example: For GET and POST – Use the URI to determine the language of the user: Enter: http://www.mydomain.com/cgi-bin/ENG/819/... The configuration file would have this container configuration: <Location /cgi-bin/ENG/819/> DefaultNetCCSID 819 CGIJobCCSID 37 </Location> ScriptAlias /cgi-bin/ /QSYS.LIB/CGI.LIB/ <Directory /QSYS.LIB/CGI.LIB/> Allow From all Options +ExecCGI CGIConvMode EBCDIC </Directory> The same configuration can handle this URI for a Japanese speaking user. Enter: http://www.mydomain.com/cgi-bin/JAP/942/ The configuration file would also have this container configuration: <Location /cgi-bin/JAP/942/> DefaultNetCCSID 942 CGIJobCCSID 5035 CGIConvMode EBCDIC_JCD </Location> ScriptAlias /cgi-bin/ /QSYS.LIB/CGI.LIB/ <Directory /QSYS.LIB/CGI.LIB/> Allow From all Options +ExecCGI CGIConvMode EBCDIC </Directory>

The CGIJobCCSID directive specifies the CCSID under which CGI jobs run, the CGI job character set environment, and the EBCDIC CCSID that is used when the server converts:

Input request data for user CGI programs
Output response data from user CGI programs to be sent back to the requester (client browser)

If this directive is not specified, the default behavior is to have the CGI job run under the same CCSID as the main server jobs. See the DefaultFsCCSID directive for detailed information on how this is determined.

CGIJobLocale

Module: mod_cgi
Syntax: CGILocale `locale_path_name`
Default: none
Context: server config, virtual host, directory, not in limit, .htaccess
Override: none
Origin: IBM
Example: CGIJobLocale /QSYS.LIB/LOCALELIB.LIB/EN_US.LOCALE
Example: To run one CGI program in CCSID 37 with an English based locale (English): ScriptAlias /cgi-english/ /QSYS.LIB/ENGLISH.LIB/ <Directory /QSYS.LIB/ENGLISH.LIB/> Allow From all Options +ExecCGI DefaultNetCCSID 819 CGIJobCCSID 37 CGIJobLocale /QSYS.LIB/LOCALELIB.LIB/EN_US.LOCALE CGIConvMode EBCDIC </Directory>
Example: To run a different CGI program in CCSID 273 and with a German based locale (German): ScriptAlias /cgi-german/ /QSYS.LIB/GERMAN.LIB/ <Directory /QSYS.LIB/GERMAN.LIB/> Allow From all Options +ExecCGI DefaultNetCCSID 819 CGIJobCCSID 273 CGIJobLocale /QSYS.LIB/LOCALELIB.LIB/DE_DE.LOCALE CGIConvMode EBCDIC </Directory>

Applications can be created independent of language, cultural data, or specific characters. Locales can be accessed to provide this type of support to any integrated language environment-based application. The CGIJobLocale directive allows a locale to be set globally or for a specific CGI job. After the locale is set, region specific information such as date or time format can be accessed. Some ILE C/C++ run time functions such as ctime() and localtime() are locale sensitive. The environment variable CGI_JOB_LOCALE is set from the CGIJobLocale directive.

CGIMultiThreaded

Module: mod_cgi
Syntax: CGIMultiThreaded `on \| off`
Default: CGIMultiThreaded off
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: FileInfo
Origin: IBM
Example: CGIMultiThreaded on

Parameter: on | off

The on value indicates that your CGI programs will be run in a job that is multiple thread capable.
The off value indicates that your CGI programs will not be run in a job that is multiple thread capable.

The CGIMultiThreaded directive is used to specify whether your CGI programs should be run in a job that is multiple thread capable. HTTP Server uses a pool of pre-started jobs for handling CGI requests. Multiple threaded programs must run in a multiple thread-capable job. The job pool that the job runs in is specified at job startup time. Once the job has started, it cannot be changed to another job pool. Not all IBM i APIs are thread safe, some will issue an error if used in a multiple thread-capable job. This happens even if the program does not actually have multiple threads running. Because of this, HTTP Server must default to non-multiple thread capable jobs for CGI programs for compatibility reasons. If your CGI program uses multiple threads, it must run in a multiple thread capable job. If your CGI does not need multiple threads, you should run it in the single threaded CGI job for performance reasons.

CGIRecyclePersist

Module: mod_cgi
Syntax: CGIRecyclePersist `on \| off`
Default: CGIRecyclePersist off
Context: server config, virtual host, directory, .htaccess, Not in Limit
Override: FileInfo
Origin: IBM
Example: CGIRecyclePersist on

The CGIRecyclePersist directive instructs the server what should be done with the job that was being used by a persistent CGI when the persistent CGI exits persistence normally.

Parameter: on | off

The on value indicates that the server can reuse this job for other CGI requests. When this is used, the persistent CGI program is responsible for cleaning up any static data from the persistent CGI transaction. The server will not perform any action other than to remove all environment variables, to clean up any static data. Before using this setting, the CGI programmer need to verify that it does indeed clean up its static data.

The off value indicates that the server will not reuse this job for other CGI requests. This is the default behavior.

MaxCGIJobs

Module: mod_cgi
Syntax: MaxCGIJobs `number`
Default: Value used for the ThreadsPerChild directive
Context: server config
Override: none
Origin: IBM
Example: MaxCGIJobs 50

The MaxCGIJobs directive is used to set the maximum number of CGI jobs that the server will concurrently use. The server will only run CGI programs in jobs where the user profile for the CGI job matches the user profile that the request is to run under. If you protect your CGI programs with many different dummy IBM i profiles ( profiles with no password) or use %%CLIENT%% (each user has their own IBM i profile and it is used to run the CGI program), then you may want to use this directive to allow the server to start more CGI jobs to handle the CGI programs. The server does reuse the CGI jobs, but only when the profile for the CGI program matches the profile for the CGI job. If you see the server ending and starting CGI jobs regularly, then you may want to use this directive to allow the server to use more CGI jobs. This would improve the capacity and performance of your system and server.

Parameter: number

The number parameter accepts any positive number. If an invalid value is used, or the number is smaller than the value used for the ThreadsPerChild directive, then the server will use the value used for the ThreadsPerChild directive.

MaxPersistentCGI

Module: mod_cgi
Syntax: MaxPersistentCGI `number`
Default: Value used for the ThreadsPerChild directive
Context: server config
Override: none
Origin: IBM
Example: MaxPersistentCGI 50

The MaxPersistentCGI directive is used to set the maximum number of active persistent CGI jobs that you want to have active at one time.

Parameter: number

The number parameter sets the maximum number of active persistent CGI jobs that are active at any one time.

MaxPersistentCGITimeout

Module: mod_cgi
Syntax: MaxPersistentCGITimeout `number`
Default: MaxPersistentCGITimeout 1200
Context: server config
Override: none
Origin: IBM
Example: MaxPersistentCGITimeout 1800

The MaxPersistentCGITimeout directive specifies the maximum number of seconds that a CGI program can use when overriding the PersistentCGITimeout directive.

Parameter: number

The number parameter value must be greater than 1 second.

MaxThreadedCGIJobs

Module: mod_cgi
Syntax: MaxThreadedCGIJobs `number`
Default: Value used for the ThreadsPerChild directive
Context: server config
Override: none
Origin: IBM
Example: MaxThreadedCGIJobs 50

The MaxThreadedCGIJobs directive is used to set the maximum number of multiple thread capable CGI jobs that the server will concurrently use. The server will only run multiple thread capable CGI programs in jobs where the user profile for the multiple thread capable CGI job matches the user profile that the request is to run under. If you protect your multiple thread capable CGI programs with many different dummy IBM i profiles (profiles with no password) or use %%CLIENT%% (each user has their own IBM i profile and it is used to run the multiple thread capable CGI program), then you may want to use this directive to allow the server to start more multiple thread capable CGI jobs to handle the multiple thread capable CGI programs. The server does reuse the CGI jobs, but only when the profile for the multiple thread capable CGI program matches the profile for the multiple thread capable CGI job. If you see the server ending and starting multiple thread capable CGI jobs regularly, then you may want to use this directive to allow the server to use more multiple thread capable CGI jobs. This would improve the capacity and performance of your system and server.

Parameter: number

The number parameter value can be any positive number. If an invalid value is used, or the number is smaller than the value used for the ThreadsPerChild directive, then the server will use the value used for the ThreadsPerChild directive.

PersistentCGITimeout

Module: mod_cgi
Syntax: PersistentCGITimeout `number`
Default: PersistentCGITimeout 300
Context: server config
Override: none
Origin: IBM
Example: PersistentCGITimeout 120

This directive specifies the number of seconds that your server waits for a client response before ending a persistent CGI session. The CGI program can override the value that you specify on a request-by-request basis.

Parameter: number

The number parameter can be any amount of time greater than 1 second.

ScriptLog

Module: mod_cgi
Syntax: ScriptLog `filename`
Default: none
Context: server config
Override: none
Origin: Modified
Example: ScriptLog /QIBM/userdata/httpa/(instance name)

The ScriptLog directive sets the Common Gateway Interface (CGI) script error logfile. If no ScriptLog is given, no CGI error log is created. If a ScriptLog is given, any CGI errors are logged into the filename given as the argument. If this is a relative file or path, it is taken relative to the server root.

This log will be opened as the user the child processes run as, for example the user specified in the main User directive. This means that either the directory the script log is in needs to be writable by that user or the file needs to be manually created and set to be writable by that user. If you place the script log in your main logs directory, do not change the directory permissions to make it writable by the user the child processes run as.

Note: The script logging is meant to be a debugging feature when writing CGI scripts, and is not meant to be activated continuously on running servers. It is not optimized for speed or efficiency, and may have security problems if used in a manner other than that for which it was designed.

Behavior

If the filename does not begin with a slash ('/') then it is assumed to be relative to the ServerRoot.

If the path ends with a '/' character, then the path is considered to be the directory that will contain the log file.

The ScriptLog file will be created with CCSID 1208 (UTF8). Customer data written to the script log is assumed to be in the CGI job CCSID and will automatically be converted to CCSID 1208. The data will be written to the log file in binary. Therefore, the customer's data will be written to the ScriptLog without conversion. Information from the CGI request will not need to be translated, as the data will already be in the defaultFSCCSID.

ScriptLogBuffer

Module: mod_cgi
Syntax: ScriptLogBuffer `size`
Default: ScriptLogBuffer 1024
Context: server config
Override: none
Origin: Apache
Example: ScriptLogBuffer 512

The ScriptLogBuffer directive limits the size of any PUT or POST entity body that is logged to the file. This prevents the log file from growing too big too quickly (the case if large bodies are being received).

Parameter: size

The size parameter is measured in bytes and consists of any positive integer. By default, up to 1024 bytes are logged, but the value can be changed with this directive.

ScriptLogLength

Module: mod_cgi
Syntax: ScriptLogLength `size`
Default: ScriptLogLength 10385760
Context: server config
Override: none
Origin: IBM
Example: ScriptLogLength 1024000

The ScriptLogLength directive can be used to limit the size in bytes of the Common Gateway Interface (CGI) script log file. Since the log file logs a significant amount of information per CGI error (all request headers, all script output) it can grow to be quite large. To prevent problems due to unbounded growth, this directive can be used to set a maximum file-size for the CGI logfile. If the file exceeds this size, no more information will be written to it.

Parameter: size

The size parameter is measured in bytes. This is any positive number.

StartCGI

Module: mod_cgi
Syntax: StartCGI `number userid IASP`
Default: none
Context: server config
Override: none
Origin: IBM
Example: StartCGI 5 USER1 StartCGI 8 QTMHHTP1 IASP1

The StartCGI directive specifies the number of CGI jobs that are spawned by the server when it starts up, the IBM i user profile to use in these jobs. This allows you to have the server prestart CGI jobs when the server starts so the users do not incur the performance hit of starting a new job. It also allows you to start up jobs for different user profiles. The userid is optional and should only be used to protect your CGI programs so that they run under the %%CLIENT%% profile or under a dummy IBM i profile (a profile with no password). The IASP is optional and should only be used when your CGI programs are in IASP rather than in the system ASP.

The cumulative number from all occurrences of this directive cannot exceed MaxCGIJobs, if it does, the server will not start. If the user profile parameter is not specified, the default server profile (QTMHHTP1) or the value from the global ServerUserID directive is used. If the third IASP parameter is specified, the second userid parameter must be also explicitly specified even using the default QTMHHTP1.

If you are using %%CLIENT%% as the profile in the protection of the CGI programs (meaning that each user authenticates with an IBM i user profile), then it should be noted that %%CLIENT%% is not a valid value on this directive. Using IBM i profiles like this should only be done in an intranet or highly secure server because you would not want to give just anyone an IBM i user profile. Therefore, you would know how many users and also their user profile name, thus you would need to decide how many users will be doing CGI requests and how many concurrent CGI requests you want each user to be able to do. Then you could specify multiple StartCGI directives, one for each user, specifying the number of concurrent CGI requests you expect that user to do.

Note: This will NOT limit the number of concurrent CGI requests. This will simply allow CGI jobs to be started at server startup time so the user does not have to incur the performance hit of starting up a new job when they run their first CGI program.

StartThreadedCGI

Module: mod_cgi
Syntax: StartThreadedCGI `number userid IASP`
Default: none
Context: server config
Override: none
Origin: IBM
Example: StartThreadedCGI 3
Example: StartThreadedCGI 5 USER1
Example: StartThreadedCGI 8 QTMHHTP1 IASP1

The Start ThreadedCGI directive specifies the number of multiple thread capable CGI jobs that are spawned by the server when it starts up, the IBM i user profile and the IASP name to use in these jobs. This allows you to have the server prestart CGI jobs when the server starts so the users do not incur the performance hit of starting a new job. It also allows you to start up jobs for different user profiles and IASPs. The userid is optional and should only be used to protect your multiple thread capable CGI programs so that they run under the %%CLIENT%% profile or under a dummy iSeries profile (a profile with no password). The IASP is optional and should only be used when your CGI programs are in IASP rather than in the system ASP.

The cumulative number from all occurrences of this directive cannot exceed MaxThreadedCGIJobs, if it does, the server will not start. If the user profile parameter is not specified, the default server profile (QTMHHTP1) or the value from the global ServerUserID directive is used. If the third IASP parameter is specified, the second userid parameter must be also explicitly specified even using the default QTMHHTP1.

If you are using %%CLIENT%% as the profile in the protection of the multiple thread capable CGI programs (meaning that each user authenticates with an IBM i user profile), then it should be noted that %%CLIENT%% is not a valid value on this directive. Using IBM i profiles like this should only be done in an intranet or highly secure server because you would not want to give just anyone an IBM i user profile. Therefore, you would know how many users and also their user profile name, thus you would need to decide how many users will be doing CGI requests and how many concurrent multiple thread capable CGI requests you want each user to be able to do. Then you could specify multiple StartThreadedCGI directives, one for each user, specifying the number of concurrent multiple thread capable CGI requests you expect that user to do.

Note: This will NOT limit the number of concurrent multiple thread capable CGI requests. This will simply allow multiple thread capable CGI jobs to be started at server startup time so the user does not have to incur the performance hit of starting up a new job when they run their first multiple thread capable CGI program.

ThreadedCgiInitialUrl

Module: mod_cgi

Syntax: ThreadedCgiInitialUrl url userid

Default: none

Context: server

Override: none

Origin: IBM

Example: ThreadedCgiInitialUrl /qsys.lib/cgi.lib/mycgi.pgm QTMHHTTP

Example: ThreadedCgiInitialUrl /QOpenSys/mypacedir/pacecgi

Example: ThreadedCgiInitialUrl /qsys.lib/cgi.lib/mycgi.pgm?init=yes USER1

Example: ThreadedCgiInitialUrl /IASP1/qsys.lib/cgi.lib/mycgi.pgm USER2

This directive is used to load and initialize threaded CGI programs when the server starts. At server startup, when processing the StartThreadedCgi directive, jobs are started to run CGI programs in. This directive enables the server to run a CGI request to the CGI job enabling the CGI program to be loaded and initialized. This function enables performance issues to be moved to when the server starts, so the first user does not have diminished performance.

If there are no StartThreadedCgi directives, an error is posted and the server does not start.