IBM Support

CGI troubleshooting



CGI troubleshooting


You are in: IBM i Technology Updates  > Web Integration on i IBM HTTP Server for i > Introduction > CGI troubleshooting

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

Check the status and job log for your CGI job

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.


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

Job type Program Number of jobs Purpose
Manager job QZHBMAIN 1 (server startup) server startup
Logging job QZSRLOG 0 - number of logs logging
Primary job QZSRHTTP 1 or 2 (Hotbackup job) handles requests
CGI job QZSRCGI 0 - many runs CGI program

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.


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.

CGI ScriptLog

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.

Send debug information from your CGI program

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.

CGI symptoms and solutions

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:

  • No data written to stdout
  • No "Content-type" line
  • No new line character after HTTP response header
  • No data after HTTP response header.

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.

  1. Issue the command ENDTCPSVR *HTTP HTTPSVR(server_instance)
  2. Change your configuration to start only 1 CGI job by adding the following directive. MaxCGIJobs 1
  3. Issue the command STRTCPSVR *HTTP HTTPSVR(server_instance)
  4. Run the CGI request.
  5. Issue the command WRKACTJOB JOB(server_instance)

    Look for the CGI job as described above.

    Select option 10 to display the job log.

    Record the Number:, User:, and Job: values for your CGI program job.

    Press F12.
  6. Issue the command STRSRVJOB <Number/User/Job>.
  7. For the CGI program, issue the command:

    STRDBG PGM(mylib/mypgm)

    If the program accesses a database file on the server, you must specify UPDPROD(*YES). See the help for the STRDBG command.
  8. Set breakpoints in the program.
  9. On the browser, issue the URL to run the CGI program.
  10. After the system issues an HTTP request on the browser, return to the session that ran STRSRVJOB. It should have stopped at a program breakpoint. Step through the code to determine the error.
  11. When finished with debug, change the configuration back to what it was and cleanup the debug environment: 
    • Issue the command ENDDBG to end debug.
    • Issue the command ENDSRVJOB to end servicing your CGI job.

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:

  • The script does not exist.
  • There is a problem with the script, for example, a send error or function check.
  • The user QTMHHTP1 does not have authority to run this program.

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.

  • Apache server enforces security more than Original server
  • If your configuration specifically excludes a user from reading a file, you cannot start the Apache server (V5R3 and after).
  • Make sure the CGI application is bound to service program QZHBCGI rather than QTMHCGI.
  • SSL is not migrated from an Original configuration to an Apache configuration.
  • Original put in the CONTENT-TYPE: text.html header followed by 2 carriage return line feeds before the tag if it didn't exist. Apache does not, causing an Error 500 - "Premature end of script header" error.
  • Apache does not free up memory used by the CGI application.
  • Apache does not close files opened by the CGI application.
  • If the CGI application swaps the user profile, Apache does not swap back to the previous profile.
  • CGI applications should run in either a "named" or "*CALLER" activation group for best performance. See CGI Programs and Activation Groups.

[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"Component":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB08","label":"Cognitive Systems"}}]

Document Information

Modified date:
30 January 2020