Last updated 2003-09-03 16:06:31 EDT
Doc Title Debugging DLXS Perl Code
Author 1 Farber, Phillip
Author 2 Pagliere, Alan
CVS Revision $Revision: 1.8 $
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.

Prints the contents of the AUTHZD_COLL and PUBLIC_COLL environment variables.
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.
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.
Prints out the contents of the link generated to redirect the user to your site's authorization system.
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.
Prints the type and label of each XPat Result Object as it is added to the given Result Set object ( XPatResutlSet ).
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.
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.
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.
Prints a dump of the environment variables in effect when the cgi program runs.
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.
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.
Prints connect string used to access the database and the database user name the connect was issued under. For example,, Username=dlxs .

Unique Text Class Debug Values

Prints the result of applying various filters to the results returned from a given query. Currently, the following filters' results are printed:
Prints the contents of the 'search within' link generated by TextClass::_SearchWithinLinks
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.
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.
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.
Prints a variety of information related to page viewing ( pageviewer-idx ) including:
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

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.

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

Environment Variables

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.
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 in your Perl install tree (At the shell prompt type: perldoc ).
Setting this environment variable to an email address (e.g. ) 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.
Setting this environment variable to the name of a file will cause the 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 .