ibm-information-center/dist/eclipse/plugins/i5OS.ic.rzaie_5.4.0.1/rzag3ch6troubleshooting.htm

212 lines
13 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="security" content="public" />
<meta name="Robots" content="index,follow" />
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
<meta name="DC.Type" content="topic" />
<meta name="DC.Title" content="Troubleshooting your CGI programs" />
<meta name="abstract" content="You can use the Work with Active Jobs (WRKACTJOB) command to check on the status of server jobs." />
<meta name="description" content="You can use the Work with Active Jobs (WRKACTJOB) command to check on the status of server jobs." />
<meta name="DC.Relation" scheme="URI" content="rzaieparcgi.htm" />
<meta name="copyright" content="(C) Copyright IBM Corporation 2002,2006" />
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2002,2006" />
<meta name="DC.Format" content="XHTML" />
<meta name="DC.Identifier" content="rzag3ch6troubleshooting" />
<meta name="DC.Language" content="en-us" />
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
<link rel="stylesheet" type="text/css" href="./ic.css" />
<title>Troubleshooting your CGI programs</title>
</head>
<body id="rzag3ch6troubleshooting"><a name="rzag3ch6troubleshooting"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<h1 class="topictitle1">Troubleshooting your CGI programs</h1>
<div><p>You can use the Work with Active Jobs (WRKACTJOB) command to check
on the status of server jobs.</p>
<p>To start Work with Active Jobs command, type the following in during a
5250 session on a command line:</p>
<pre>WRKACTJOB SBS(QHTTPSVR) JOB(<var class="varname">server_instance</var>)</pre>
<p>Where <var class="varname">server_instance</var> is the name of your HTTP Server
instance.</p>
<p>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. </p>
<p>To find out if server jobs have ended abnormally, check the spooled files
that contain the job logs (QPJOBLOG) for the user profile QTMHHTTP. </p>
<p>The symptoms that are described in this section would be seen running a
request to the server at a browser.</p>
<div class="section"><h4 class="sectiontitle">Symptom: Connection abandoned, dropped, or no data sent</h4><div class="note"><span class="notetitle">Note:</span> Different
browser issues different messages when no data is returned to the browser.
Abandoned, dropped or no data will be displayed at the browser.</div>
<div class="note"><span class="notetitle">Cause:</span> 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:<ul><li></li>
<li>No data written to stdout</li>
<li>No “Content-type”, “Location”, or “Status” line</li>
<li>No new line character after HTTP response header</li>
<li>No data after HTTP response header.</li>
</ul>
</div>
<div class="note"><span class="notetitle">Solution:</span> 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:<blockquote><pre>Content-type: text/plain\n
\n
This data is returned to the client</pre>
</blockquote>
</div>
<div class="note"><span class="notetitle">Cause:</span> CGI program caused an exception message that was not handled
by the CGI program.</div>
<div class="note"><span class="notetitle">Solution:</span> Look at
the active server job logs in <a href="#rzag3ch6troubleshooting__wrkactjobexample">#rzag3ch6troubleshooting/wrkactjobexample</a>. If the system does not indicate a message in the joblog
for the active server jobs, do a <kbd class="userinput">WRKSPLF QTMHHTTP</kbd>.
Check for server jobs that ended when the system ran the CGI program. Change
the program to monitor for the message not being handled.</div>
<div class="note"><span class="notetitle">Cause:</span> The program being called does not exist in the library.</div>
<div class="note"><span class="notetitle">Solution:</span> Check the library for the correct name.</div>
<div class="note"><span class="notetitle">Cause:</span> There is a bug in your user-created CGI program.</div>
<div class="note"><span class="notetitle">Solution:</span> You need to set up a scaffolding environment
to debug the CGI application prior to integration with server:<ol><li>Issue the command <kbd class="userinput">ENDTCPSVR *HTTP HTTPSVR(server_instance)</kbd></li>
<li>Issue the command <kbd class="userinput">STRTCPSVR *HTTP HTTPSVR(server_instance '-minat
1 -maxat 1')</kbd><div class="note"><span class="notetitle">Note:</span> 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.</div>
<p>Ending and starting
the server ensures that only one worker job is running.</p>
<ol type="a"><li>Issue the command <kbd class="userinput">WRKACTJOB JOB(<var class="varname">server_instance</var>)</kbd><p>Look
for the CGI jobs as described above.</p>
<p>Select <span class="uicontrol">option 10</span> to
display the job log.</p>
<p>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.</p>
<p>Record the <var class="varname">Number:</var>, <var class="varname">User:</var>,
and <var class="varname">Job:</var> values for your CGI program job.</p>
<p>Press <span class="uicontrol">F12</span>.</p>
<p>Issue
the command <kbd class="userinput">STRSRVJOB &lt;<var class="varname">Number/User/Job</var>&gt;</kbd>.</p>
</li>
<li>For the user CGI program, issue the command STRDBG &lt;usercgilib/cgipgm&gt;<p>If
the program accesses a database file on the server, you must specify <kbd class="userinput">UPDPROD(*YES)</kbd>.
See the help for the STRDBG command.</p>
<div class="note"><span class="notetitle">Note:</span> You will need additional authority
to troubleshoot the CGI program. For example, you will need authority to the
QTMHHTTP user profile.</div>
</li>
<li>Set breakpoints in the program.</li>
<li>On the browser, issue a URL that would run the CGI program.</li>
<li>After the system issues an HTTP request on the browser, return to the
session that ran <kbd class="userinput">STRSRVJOB</kbd>. It should have stopped
at a program breakpoint.<p>Ending and starting the server ensures that only
one worker thread is running.</p>
</li>
</ol>
</li>
<li>When finished with debug, reset the server values:<ol type="a"><li>Issue the command <kbd class="userinput">ENDDBG</kbd></li>
<li>Issue the command <kbd class="userinput">ENDSRVJOB</kbd></li>
<li>Issue the command <kbd class="userinput">WRKACTJOB SBS(QHTTPSVR) JOB(server_instance)</kbd></li>
<li>Issue the command <kbd class="userinput">STRTCPSVR *HTTP HTTPSVR(server_instance)</kbd></li>
</ol>
</li>
</ol>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Symptom: The system is not converting or handling special
characters as expected</h4><div class="note"><span class="notetitle">Cause:</span> The browser
inserts special characters using escape sequences which requires special handling
by the CGI program.</div>
<div class="note"><span class="notetitle">Solution:</span> 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.</div>
<p>There are two approaches to handling
escape sequences:</p>
<ol><li>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.</li>
<li>Convert the EBCDIC representation of the ASCII escape sequence to the
EBCDIC equivalent character.</li>
</ol>
<p>The following approach outlined in the first conversion technique
listed above:</p>
<div class="note"><span class="notetitle">Note:</span> The hex representation of the %2C from the browser
was 0x253243. When this escape sequence is converted to EBCDIC, it ends up
as 0x6CF2C3.</div>
<ol><li>Convert the “xx” in “%xx” to the corresponding EBCDIC character. In this
case 0xF2C3 is converted to 0x2C.</li>
<li>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.<div class="note"><span class="notetitle">Note:</span> The CGI program should preserve an escape sequence that represents
the character “%”.</div>
</li>
<li>Call QtmhCvtDB to convert the input stream.<div class="note"><span class="notetitle">Note:</span> 7-bit ASCII CCSID 367
is standard on browsers.</div>
</li>
</ol>
</div>
<div class="section"><h4 class="sectiontitle">Symptom: Error 500: Bad script request -- script /qsys.lib/qsyscgi.lib/progname.pgm
not found or not executable</h4><div class="note"><span class="notetitle">Cause:</span> Configuration
or authority error.</div>
<p>This message can appear for the following reasons:</p>
<ul><li>The script does not exist.</li>
<li>There is a problem with the script, for example, a send error or function
check.</li>
<li>The user QTMHHTP1 does not have authority to run this program.</li>
</ul>
<div class="note"><span class="notetitle">Solution:</span> Check the configuration and authorities
given to the CGI program.</div>
</div>
<div class="section"><h4 class="sectiontitle">Symptom: A browser request that runs a CGI program runs longer
than expected. The browser keeps waiting for a response</h4><div class="note"><span class="notetitle">Cause:</span> The CGI application that was running has taken a function check.</div>
<div class="note"><span class="notetitle">Solution:</span> 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”.</div>
</div>
<div class="section"><h4 class="sectiontitle">Symptom: A CGI written form is not cached in the browser</h4><p>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.</p>
<div class="note"><span class="notetitle">Cause:</span> The server is sending a
last-modified header.</div>
<div class="note"><span class="notetitle">Solution:</span> Use the <var class="varname">—nolastmod</var> HTTP
Server startup value to specify that the server should not send a last-modified
header.</div>
</div>
<div class="section"><h4 class="sectiontitle">Symptom: The configuration uses the CGIConvMode value of %%MIXED/MIXED%%
and the input characters your CGI program receives are incorrect</h4><div class="note"><span class="notetitle">Cause:</span> 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.</div>
<div class="note"><span class="notetitle">Solution:</span> Configure
CGIConvMode for %%EBCDIC/MIXED%%.</div>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzaieparcgi.htm" title="This topic provides information about Common Gateway Interfaces (CGI).">Common Gateway Interface</a></div>
</div>
</div>
</body>
</html>