This page contains some hints for analyzing and debugging your failing CGI program.

Server jobs all run under the QHTTPSVR subsystem. To find your server jobs, use the Work with Active Jobs (WRKACTJOB) command where server_instance is the name of your HTTP Server instance.

WRKACTJOB SBS(QHTTPSVR) JOB(server_instance)

The Work with Active Jobs display will show several server jobs. There may be more, but these are the significant ones for CGI debugging.

To check the job log, enter 5 next to the CGI job, then option 10 to see the job log.

To determine if a CGI job has ended abnormally, check the spooled files that contain the CGI job logs (QPJOBLOG) for the user profile QTMHHTTP.

WRKSPLF SELECT(QTMHHTTP)

The User Data field contains the name of the server.

The ErrorLog directive sets the name of the file to which the server will log errors it may encounter. Error logging is enabled by default. The default error log is named logs/errorlogand is relative to the server root. This log can contain a variety of CGI related errors including errors sent from some of the CGI APIs.

The ScriptLog directive, when configured, logs information about a CGI program that does not execute properly. The ScriptLog is useful to see what data (if any) your failing CGI program produced and any associated errors. Script logs record all CGI parsed data and, therefore, can have a significant impact on CGI performance. They should be used for debug purposes only and not be kept active all the time. In addition, being a mere debug tool, they are not customizable. 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 the 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 sections of information are logged:

%request -- All HTTP request headers received with 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.

You can also use standard error (stderr) for debug information. The information written to stderr within a CGI program is written to your server's error log. Here is a code snippet (written in c) that writes data to stderr:

#include <stdio.h>
...
fprintf(stderr," Entering foo()\n");
...
fprintf(stderr," Leaving foo()\n");

This will produce entries in the error log in the following format:

[] [error] [client <ip_address>] Entering foo() [<time>] [error] [client <ip_address>] Leaving foo()

If you write to stderr it will write to the error log, even if your CGI program does not fail.

The symptoms that are described in this section would be seen when running a CGI request from a browser to the server.

Symptom: Error 500 - Internal server error

Cause: The system has a problem with the data sent by a CGI program to standard output. The data that is written to stdout may have one of the following problems:

Solution: The first data written to stdout should be the "Content-type" line with two new line characters ("\n"), followed by the data to be returned to the client. For example:

Content-type: text/html\n\n

See CGI programming examples for more help.

Add the ScriptLog directive to your server to see the data, if any, being sent from the CGI program.

Cause: CGI program caused an exception message that was not handled by the CGI program.
Solution: Check the status and job log for your CGI job. Change the program to monitor for the message not being handled.

Cause: There is a bug in your user-created CGI program.
Solution: You need to modify your server to debug the CGI application.

Symptom: The system is not converting or handling special characters as expected

Cause: The browser inserts special characters using escape sequences which require special handling by the CGI program.
Solution: Browsers create escape sequences (ISO 8859) for special characters (for example, : . , ! @ # $ % *, and so on.) These characters come into standard input in the form "%xx", where "xx" represents the ASCII hexadecimal value. (For example, a comma comes in as "%2C".)

For CGI input mode EBCDIC, these three characters "%xx" are converted to EBCDIC and the values of "xx" are changed to the corresponding EBCDIC code points. (For example, a comma coming in as "%2C" would be converted to "%6B".)

For CGI input mode %%MIXED%%, these three characters "%xx" are converted to EBCDIC, but the values of "xx" are not changed to the corresponding EBCDIC code points

Symptom: Not Found -- Error 404: The script request is not valid. The script is not executable.

Cause: Configuration, program existence, or authority error.

This message can appear for the following reasons:

Solution: Check the configuration and authorities given to the CGI program.

Symptom: A browser request CGI program runs longer than expected. The browser keeps waiting for a response

Cause: The CGI application that was running has taken a function check.
Solution: Look at the QSYSOPR message queue for a message that requires a reply sent from the CGI program that was running. Note the statement where the program is failing. Use the procedure described under "Symptom: Error 500".

Symptom: CGI program does not run the same on Apache as it did on Original

Cause: There are some differences between the 2 servers that might prevent a CGI application from running as expected.
Solution: Consider the following list of server differences and recommendations for running your CGI application on an Apache server.