Troubleshooting

<p>Here are some tools, facilities and techniques useful for troubleshooting problems

with the middleware after installation.</p>

==Assertion failures==

<p>If the CGI program runs but encounters a condition that makes it impossible

to perform a specific function it will exit and generate an [[assertion

failure page]]. An example might be a missing Terminology Mapper map file

for one of your collections.</p>

<p>The <tt>DLPS_DEV</tt> environment variable must be set to get this output.</p>

<p>Note that this page displays an optional message about the nature of the failure,

the URL that led to the assertion failure and a traceback of the stack up to

the point the assertion failed and . </p>

<p>By examining each part you may be able to determine the reason for the failure.

Sometimes it is useful to look at the line number in the code mentioned in the

traceback to determine why the error occurred especially if no message appears.

</p>

==Server errors==

<p>If you see a page similar to <a href="servererror.html">this page</a> it may

due to a syntax error in your code. You can check the code for correct

syntax or reveal other errors you encounter when running under the web server

by <a href="#commandline">running at the command line</a>.</p>

<p>Another possibility is that the location of Perl in your system has changed

since the middleware was installed. This means the symlink to Perl in $DLXSROOT/bin/symlinks

is now bad. You can change the symlink manually or restore Perl to its original

location. </p>

==Debug flags==

<p>There are several useful debug flags which aid in determining the source of

errors. Add <b><tt>;debug=<i>switch</i></tt></b> to the URL that caused the

error and re-submit the URL in you browser. The <a href="http://www.dlxs.org/docs/13/program/debug.html">complete

documentation</a> describes all the debug flags. The most useful values for

<b><tt><i>switch</i></tt></b> are: </p>

<dl>

<dt><tt><b>all</b></tt></dt>

<dd>Turn on all debugging switches. This generates a lot of data.</dd>

<dt><tt><b>collsinfo</b></tt></dt>

<dd>Dump the contents of the CollsInfo database object. This lets you check

that the database values for each collection, which you think are set, are

actually those being used by the program.</dd>

<dt><tt><b>env</b></tt></dt>

<dd>dump the environment variables and their values. You can check for the correct

values of critical environment variables such as <tt>REMOTE_USER</tt>, <tt>HTTP_HOST</tt>,

<tt>AUTHZD_COLL</tt>, <tt>DLXSROOT</tt> and <tt>DOCUMENT_ROOT</tt>. This is

a quick sanity check on the values of these environment variables set for

CGI program by the web server / virtual host. </dd>

<dt><tt><b>tpl</b></tt></dt>

<dd>show the path where files subject to fallback resolution (<tt>.xml, .xsl, .css, .js</tt>) are found.

<dt><tt><b>xml</b></tt></dt>

<dd>emit the raw xml from the middleware not subjected to XSLT transformation to HTML.

<dt><tt><b>xslt</b></tt></dt>

<dd>emit the virtual stylesheet constructed by the middleware.

<dt><tt><b>search</b></tt></dt>

<dd>dump the raw XPAT queries the middleware generated for a given search</dd>

</dl>

==Tools, checks and techniques==

<p>You can get additional information about what might be going wrong by

using the following. It is useful if you can send us this information in support requests too.</p>

==Running at the command line==

<p><B>NOTE:</B> Whenever you run at the command line, the web server is not in the loop, so set these environment variables in your csh or bash shell:

<ul>

<li>set <tt>AUTHZD_COLL</tt> to include the collections that appear in your command line script parameters:

<blockquote> <b>

(csh) % setenv AUTHZD_COLL :moa:moajrnl:sampletc:workshoptc:

<br>(bash) % export AUTHZD_COLL=:moa:moajrnl:sampletc:workshoptc:

</b></blockquote>

</li>

<li>set <tt>DLXSROOT</tt>:

<blockquote><b>

(csh) % setenv DLXSROOT path_to_the_root_of_your_install_tree

<br>(bash) % export DLXSROOT=path_to_the_root_of_your_install_tree

</b></blockquote>

</li>

<li>set <tt>DLPS_DEV</tt> to get more debugging information:

<blockquote><b>

(csh) % setenv DLPS_DEV 1

<br>(bash) % export DLPS_DEV=1

</b></blockquote>

</li>

</ul>

</p>

<p>Given a URL that causes a server error, try running the CGI program at the

command line with the same input to get additional information about the problem. For example, given <b><tt>http://pfarber.ws.umdl.umich.edu/cgi/t/text/text-idx?c=sampletc_utf8;page=simple</tt></b>

you can run the CGI program at the command line like this (note quotes):</p>

<p>

<pre> <b>

% cd $DLXSROOT/cgi/t/text

% ./text-idx 'http://pfarber.ws.umdl.umich.edu/cgi/t/text/text-idx?c=sampletc_utf8;page=simple' </b>

</pre>

</p>

==Running the Perl debugger at the command line==

<p>You can also run the Perl debugger at the command line with the <tt><b>-d</b></tt>

switch and step through the code line by line by typing '<tt><b>n</b></tt>' or run until an error occurs by typing '<tt><b>c</b></tt>'

at the Perl debugger prompt <tt><b>DB&lt;1&gt;</b></tt>. This assumes the code

compiles and can be executed:</p>

<pre>

<b>

% cd $DLXSROOT/cgi/t/text/text-idx

% perl -d ./text-idx 'http://pfarber.ws.umdl.umich.edu/cgi/t/text/text-idx?c=sampletc;page=simple' </b>

</b>

<i>Current directory is /l1/dev/pfarber/cgi/f/findaid/

Loading DB routines from perl5db.pl version 1.28

Editor support enabled.

Enter h or `h h' for help, or `man perldebug' for more help.

DB&lt;1&gt;</i>

</pre>

<h3><a name="dlpsdev"></a>Set the <tt>DLPS_DEV</tt> environment variable</h3>

<p>Set <tt>DLPS_DEV</tt> to 1 in your shell (debugging at the command line) or in your virtual host (developing under the browser) to get a full stack trace when a compilation error or runtime assertion failure occurs.</p>

==Log files==

<p>Here's a list of log files that will contain status and error messages related to various operations.</p>

<table style="font-size: 12pt;" border="1" width="90%">

<tr><td><b>Filename</b></td><td><b>Where configured</b></td><td><b>Errors logged</b></td></tr>

<tr><td><tt>/tmp/itemviewmkdiroutput.log</tt></td><td><tt>$DLXSROOT/lib/ItemView.cfg</tt></td><td>Pageviewer command errors to process source image files for web delivery and logs of all pageviewer commands when URL has <tt>debug=pageviewer</td></tr>

<tr><td><tt>/tmp/classmkdiroutput.log</tt></td><td><tt>$DLXSROOT/lib/LibGlobals.cfg</tt></td><td>General commands create cache directories for pageviewer frames and portfolio exports if URL has <tt>debug=pageviewer</tt>. Always logs if command error. </td></tr>

<tr><td><tt>/tmp/dbconnectionfailures.txt</tt></td><td><tt>Hardcoded in $DLXSROOT/lib/DbUtils.pm</tt></td> <td>Log of the DBI error string if a <tt>DBI-&gt;connect()</tt> to MySQL fails</td></tr>

<tr><td>/tmp/pageviewmode</td><td>Hardcoded in $DLXSROOT/lib/ItemView.pm</td><td>Records the mode (local or remote) of access to page image files. Only logged when URL has <tt>debug=pageviewer</tt></td></tr>

</table>

==Apache error log==

<p>It may be useful to examine the last few entries in the Apache web server's

error log in <tt>APACHE/logs/error_log</tt>. You can monitor the log in real

time as you send requests to the server from your browser. At your shell command

line:</p>

<blockquote>

<pre><b>

% tail -f APACHE/logs/error_log

</b></pre>

</blockquote>

==Perl module versions==

<p>The Installer prints out a report on missing Perl modules and Perl modules

you have installed whose versions differ from the recommended. Double-check

this list and make sure all modules are installed and that the versions match.

We have found this to be especially important when dealing with the DBI/DBD

database interface modules and with Apache::Session related modules.</p>

<p>You can check both existence and version for a given module at the command

line. For example, to check DBI and Apache::Session, respectively:</p>

<blockquote>

<pre>

<b>perl -e 'use DBI; print "$DBI::VERSION\n"'</b>

<i>1.50</i>

<b>perl -e 'use Apache::Session; print "$Apache::Session::VERSION\n"'</b>

<i>1.80</i>

</pre>

</blockquote>

==Configured vs. actual file locations==

<p>Double check the values in the database (via collmgr) that specify locations

for files to verify that they correspond to the actual file locations in your

file system.</p>

==Paths to binaries stored in $DLXSROOT/bin/symlinks vs. actual binary locations==

<p>The Installer records your answers to prompts about the location of binaries in your system in <tt>$DLXSROOT/bin/symlinks</tt>. Check that you can actually run the binaries from these symlinks.</p>

==Move "release" rows to "production"==

<p>If the database edits you make to a collection are not taking effect it may

be because you need to "Make a release to production" in <b>collmgr</b>. Recall

that when you edit rows as the user <b>dlxsadm</b>, you are changing the "release"

rows, i.e., those keyed by <tt><b>dlxsadm</b></tt>. When you <i>run</i> the

DLXS middleware in production mode (i.e. DLPS_DEV is NOT set), it is reading

the rows keyed by <tt><b>production</b></tt>. Your edits are not visible to

the running DLXS middleware unless you "Make a release to production".</p>

==Use newsid=1 URL parameter==

<p>You can add the <tt>newsid=1</tt> URL parameter to force middleware to create a new session. In past releases this would force a re-read of the collection database. Now the database is always read with each run of the CGI. Forcing a new session will clear accumulated state information and make the middleware behave as it would for a user arriving at site for the first time. Examples of stored information are:

<ul>

<li>back pointing links in ImageClass</li>

<li>last search key in ImageClass</li>

<li>cached item XML in ImageClass</li>

<li>application result object in TextClass</li>

<li>last sort order in TextClass</li>

<li>many others ...</li>

</ul>

</p>

==Remote connect error==

<p>There are a few error messages that crop up frequently.</p>

<blockquote><b> Could not start XPAT for only requested collection sampletc ...

terminating. Error: Could not fork XPAT process or start remote process or child

had exec error. Connection refused at /l1/dev/pfarber/lib/RemoteConnect.pm line

147. </b> </blockquote>

<p>This means that the <b><tt>host</tt></b> field for this collection in the database

is set to a different value than the virtual host running the CGI program. In this

event, the middleware attempts to start XPAT on that remote machine. Unless

the remote access daemon (<b>dlxsd</b>) is running on that remote machine (and

the collection data and indexes are there too) this error will occur. If your

data is never remote, setting <b><tt>host</tt></b> to the value <b><tt>localhost</tt></b>

is the simplest solution. Recall this <a target="external" href="http://pfarber.ws.umdl.umich.edu/cgi/c/collmgr/collmgr?class=text&type=Collections&collid=sampletc_utf8&submit=edit+working+collection">collmgr page</a></p>

==More tools==

<p><a href="tools.html">Here's a list of tools</a> we've found useful with links to their web sites. </p>