Debugging DLXS Perl Middleware Code

Much code debugging can be accomplished in whatever development environment you may be using. At DLPS we generally use XEmacs, along with its Comint mode for the Perl debugger. However, it is often helpful to investigate a program's behavior within the browser environment as well. There are occasional debugging statements in the code that will print values of specific variables or even dump entire objects in HTML. These are controlled by adding a parameter to any URL. Simply add a " ;debug= value " to a URL in your browser where value is any of the following described below.

Note that the value all turns on all debugging switches and produces a considerable quantity of output, especially in the case of searches.

Debug Values Available in All Classes

These values pertain to the debugging output produced by modules in Lib i.e. DLXSROOT/lib and as such they are common to all of the class middleware.

tpl
show the path where files subject to fallback resolution (.xml, .xsl, .css, .js) are found.
xml
emit the raw xml from the middleware not subjected to XSLT transformation to HTML.
xslt
emit the virtual stylesheet constructed by the middleware.
auth
Prints the contents of the AUTHZD_COLL and PUBLIC_COLL environment variables.
cache
Prints information regarding the process of caching information in the session and when profiling time spent in certain parts of the code. See the debug variable time below.
collsinfo
Prints a variety of information about the Collection Information ( CollsInfo ) object primarily related to the contents of the object, also whether the object has been "reused" (e.g., from the cache) or created fresh from the database.
reauth
Prints out the contents of the link generated to redirect the user to your site's authorization system.
results
Prints each query just before it is sent to XPAT for evaluation and prints a formatted representation of the raw results returned by XPAT. Prints the "clean" result after XPAT result markup tags have been removed, displaying the order in which the result came back from XPAT, its byte offset, the data and the size of the data.
resultset
Prints the type and label of each XPat Result Object as it is added to the given Result Set object ( XPatResutlSet ).
session
Prints the session id under which the current invocation of the cgi program is running and indicates whether this is a new session id or the id of a previous session retrieved from the session cache.
xpat
Prints a dump of the XPat object when it is first created. Prints the local or remote startup command string to be sent to the forked process running XPAT and each query string sent to XPAT for evaluation.
cgi
Prints a dump of the CGI object created from the URL that invoked the cgi program. It is a key=value list of the URL parameters.
env
Prints a dump of the environment variables in effect when the cgi program runs.
search
time
Prints a summary of the amount of time it takes the Class CGI to run. It displays the elapsed time to compile and run the entire program (which includes time to communicate with a local or remote XPAT process, and so includes process startup, context switching, network latency, and inter-process communication overhead). It also displays the CPU time devoted solely to the process running the Class CGI. The difference between these two numbers is a rough indication of the overhead to which the CGI is subject.
version
Prints the value $LibVersion::VERSION that is the version of the separate Lib deliverable in use by the Class CGI. Prints the Release number of the middleware. Prints the Perl version number. Prints the main program version number.
db
Prints connect string used to access the database and the database user name the connect was issued under. For example, DSN=DBI:mysql:dlxs:mysql.umdl.umich.edu:, Username=dlxs .

Unique Text Class Debug Values

filter
Prints the result of applying various filters to the results returned from a given query. Currently, the following filters' results are printed:
links
Prints the contents of the 'search within' link generated by TextClass::_SearchWithinLinks
qf
Prints status when the QueryFactory object is created for a given collection object. If the collection implements the use of XPAT mapping of special characters (e.g. 'Y' for yogh in Middle English) the transformation of these characters in the CGI object is called out at this point.
target
Useful for tracing the construction of searches for the target of <PTR> type notes. Prints which mode of target region search was used, i.e. fabricated region search or explicitly coded list of regions. Prints the XPAT query for the target region and the parent region of the target region. Prints the overall restriction applied to limit the search to a particular main region. This debug output appears in the note popup window when the note is displayed.
sort
Prints information regarding the process of sorting results and when profiling time spent in certain parts of the code. See the debug variable time below.
pageviewer
Prints a variety of information related to page viewing ( pageviewer-idx ) including:
ww
Prints a variety of information about the Wordwheel CGI and Wordwheel Object. The information printed for the CGI includes the environment and the contents of the CGI object created from the URL that invoked the wordwheel CGI. The information printed for the Wordwheel object ( WW )consists of:

Unique Bib Class Debug Values

fisheye
A dump of the data computed for the construction of the fisheye navigation string.

Unique Image Class Debug Values

There are not many distinct values unique to Image Class for the debug URL parameter. Assigning any value to debug (e.g. 1 ) will turn on debugging output globally within Image Class. Of course, the common distinct values mentioned earlier must be specified as documented to turn on their given debug function.

hs
Prints the collection ID for each collection processes in the HandleSearch subroutine.

Environment Variables

charents
Not a debug parameter value. Rather, if the DEBUG environment variable is set to charents at the command line or debugging environment, each character entity reference encountered in the data is printed together with the graphic image or equivalent character to which it will be mapped in the output.
DBI_TRACE
This will enable a dump of the interaction of the middleware with the Perl DBI (database interface) module. It must be set before Perl executes. Refer to the POD for DBI.pm in your Perl install tree (At the shell prompt type: perldoc DBI.pm ).
ASSERTION_EMAIL
Setting this environment variable to an email address (e.g. umdl-errors@umich.edu ) will cause the ASSERT subroutine to send a complete email summary of the data that caused an assertion failure. This is useful in monitoring the health of production code in the absence of user feedback.
XPAT_LOGGING
Setting this environment variable to the name of a file will cause the XPat.pm module to log process ids and associated URL strings for each XPAT process forked to execute a query. At DLPS we couple this log file with a runaway process killer which kills XPAT processes that run for more than 1.5 minutes. The process killer sends email notification and with the additional logged data we can determine the URL that generated the runaway and resolve the problem.

Support for Virtual Host-based Work Directories

Related to the issue of ebugging is the issue off having multiple work directories for each developer. DLXS middleware supports this. There are ways of setting up "sandboxes" so that individuals can have their own environments for running and testing changes they are making, independently of others' work. For more information, see DLPS/DLXS Development Environment .