Troubleshooting CGI programs

This topic lists common CGI program problems and solutions.

You can use the Work with Active Jobs (WRKACTJOB) command to check on the status of server jobs. To start Work with Active Jobs command, type the following in during a 5250 session on a command line:

WRKACTJOB SBS(QHTTPSVR) JOB(server_instance)

Where server_instance is the name of your HTTP Server instance.

When the server is not processing a request, the Work with Active Jobs display will show several server jobs. The first job is the manager job for the server instance. (Function PGM-QZHBMAIN). Server jobs showing PGM - QZSRLOG are logging jobs. Server jobs showing PGM - QZSRHTTP are primary jobs. (There will be 2 of these unless you specify HotBackup Off in your configuration.) Only one of these jobs will be actively handling requests. Jobs showing PGM -QZSRCGI are CGI jobs.

To find out if server jobs have ended abnormally, check the spooled files that contain the job logs (QPJOBLOG) for the user profile QTMHHTTP.

More CGI troubleshooting tips and hints can be found at the Troubleshooting your CGI program Link outside Information Center Web page on the HTTP Server Web site.

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

List of symptoms:

Symptom: Connection abandoned, dropped, or no data sent

Note: Different browser issues different messages when no data is returned to the browser. Abandoned, dropped or no data will be displayed at the browser.
Cause: The system has incorrectly formatted a CGI program that writes data 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”, “Location”, or “Status” line
  • No new line character after HTTP response header
  • No data after HTTP response header.
Solution: Write the data to stdout with “Content-type: ” line with two new line characters (“\n”) and the data to be returned to the client. For example:
Content-type: text/plain\n
   \n
   This data is returned to the client
Cause: CGI program caused an exception message that was not handled by the CGI program.
Solution: If the system does not indicate a message in the joblog for the active server jobs, do a WRKSPLF QTMHHTTP. Check for server jobs that ended when the system ran the CGI program. Change the program to monitor for the message not being handled.
Cause: The program being called does not exist in the library.
Solution: Check the library for the correct name.
Cause: There is a bug in your user-created CGI program.
Solution: You need to set up a scaffolding environment to debug the CGI application prior to integration with server:
  1. Issue the command ENDTCPSVR *HTTP HTTPSVR(server_instance)
  2. Issue the command STRTCPSVR *HTTP HTTPSVR(server_instance '-minat 1 -maxat 1')
    Note: You also may need to change script_timeout and output_timeout to be larger. If you are stepping through your code, it may take too long and script_timeout or output_timeout may expire. This causes the server to terminate the job you are debugging.

    Ending and starting the server ensures that only one worker job is running.

    1. Issue the command WRKACTJOB JOB(server_instance)

      Look for the CGI jobs as described above.

      Select option 10 to display the job log.

      If your CGI program is single thread capable, message HTP2001 will be in the job log. If your CGI program is multithread capable, message HTP2002 will be in the job log.

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

      Press F12.

      Issue the command STRSRVJOB <Number/User/Job>.

    2. For the user CGI program, issue the command STRDBG <usercgilib/cgipgm>

      If the program accesses a database file on the server, you must specify UPDPROD(*YES). See the help for the STRDBG command.

      Note: You will need additional authority to troubleshoot the CGI program. For example, you will need authority to the QTMHHTTP user profile.
    3. Set breakpoints in the program.
    4. On the browser, issue a URL that would run the CGI program.
    5. 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.

      Ending and starting the server ensures that only one worker thread is running.

  3. When finished with debug, reset the server values:
    1. Issue the command ENDDBG
    2. Issue the command ENDSRVJOB
    3. Issue the command WRKACTJOB SBS(QHTTPSVR) JOB(server_instance)
    4. Issue the command STRTCPSVR *HTTP HTTPSVR(server_instance)

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

Cause: The browser inserts special characters using escape sequences which requires 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 or into the QUERY_STRING environment variable in the form “%xx”, where “xx” is the two characters representing the ASCII hexadecimal value. (For example, a comma comes in as “%2C”. 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.

There are two approaches to handling escape sequences:

  1. Convert the EBCDIC representation of the ASCII escape sequence to an EBCDIC escape sequence or use CGI input mode %%EBCDIC%%. This is necessary because the QtmhCvtDB API assumes that escape sequences represent EBCDIC code points, and the API converts them to the corresponding EBCDIC character. For example, %2C, which represents an ASCII comma, is converted to EBCDIC X'2C', which is not an EBCDIC comma.
  2. Convert the EBCDIC representation of the ASCII escape sequence to the EBCDIC equivalent character.

The following approach outlined in the first conversion technique listed above:

Note: The hex representation of the %2C from the browser was 0x253243. When this escape sequence is converted to EBCDIC, it ends up as 0x6CF2C3.
  1. Convert the “xx” in “%xx” to the corresponding EBCDIC character. In this case 0xF2C3 is converted to 0x2C.
  2. For the first approach, convert the EBCDIC character to the two-byte form. Then you can reinsert the two bytes back into the input stream in the same place they originally appeared. The 0x6B would be converted to 0xF6C2, and the resultant escape sequence would be 0x6CF6C2. For the second approach, leave the data in its EBCDIC form and replace the original escape sequence (three characters) with the single character. In this case, replace 0x6CF2C3 with 0x6B.
    Note: The CGI program should preserve an escape sequence that represents the character “%”.
  3. Call QtmhCvtDB to convert the input stream.
    Note: 7-bit ASCII CCSID 367 is standard on browsers.

Symptom: Error 500: Bad script request -- script '/qsys.lib/qsyscgi.lib/progname.pgm' not found or not executable

Cause: Configuration 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 that runs a 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: A CGI written form is not cached in the browser

Using the back button on the browser results in a request to the server. The form contains no headers or meta tags telling the browser to request (not cache) the page.

Cause: The server is sending a last-modified header.
Solution: Use the —nolastmod HTTP Server startup value to specify that the server should not send a last-modified header.

Symptom: The configuration uses the CGIConvMode value of %%MIXED/MIXED%% and the input characters your CGI program receives are incorrect

Cause: The file CCSID language for your server has characters that do not match the EBCDIC code page 37. Use the EBCDIC mode rather than the MIXED mode.
Solution: Configure CGIConvMode for %%EBCDIC/MIXED%%.