Perl Debugger Information and Cheat-Sheet


Template level External Article ID

KBA00039873

Issue

 Important information regarding debugging perl reports, including pertinent files/directories and a cheat-sheet.

Resolution

Common important files: 

$INDBDIR/perllib/sdsdate.pl – contains date converting subroutines
$INDBDIR /perllib/sds.pl – automagically includes sdsdate.pl for you
$INDBDIR /perllib/ctree.pl – automagically includes sds.pl
$FORCEDIR/perllib/xml_rpt.pl - includes data needed to render PDF (.xx) reports
$FORCEDIR/util/reportCron.pl - used for PDF crons and sending emails (includes emailAttach.pl)
$INDBDIR /perllib/wherefile.pl – defines a subroutine to help you find a file your script requires

Important directories:

$INDBDIR/perllib/ - Many important perl files are located here, such as sds.pl and ctree.pl
$FORCEDIR/perllib – These directories contain many Perl files that are needed for all reports.  For example, ucr_subs.pl and ucr_cfg.pl reside here, which are necessary for running all UCR reports.
$FORCEDIR/xsl – Contains style sheets which can be applied with AddStylesheet() within a report
$FORCEDIR/uxsl - Contains custom style sheets and agency logos
$FORCEDIR/rpt – Standard reports are contained here
$FORCEDIR/urpt – Standard custom reports are contained here
$FORCEDIR/prt – Screen (print) reports are contained here
$FORCEDIR/uprt – Custom screen (print) reports are contained here
$FORCEDIR/util - Contains necessary files such as reportCron.pl and emailAttach.pl

Perl Debugger Cheat-Sheet:

 
Commands used to navigate through the program:
n – next statement (skips subroutines)
s – single step (steps into subroutines)
c [line | sub] – continue (optionally stop at the specified line or subroutine, otherwise continues until a breakpoint is reached or the program terminates)
r – return from a subroutine
T – stack trace; shows which subroutine(s) you are in		 
Commands used to control execution of the program:
b [line|sub] – place a breakpoint at line or subroutine
B [line|*] – delete a specific / all breakpoints
w $variable – break when a variable’s value changes
W [line|*] – delete a specific / all watchpoints
R – restart the script.  Doesn’t always work the way you want it to when debugging a CtPerl report, so beware.		 
Commands used to examine data:
p $variable – print content of a variable
x $variable – examine a variable.  Works best when used on a scalar.  To examine a hash or array, put a backslash "\" in front of the sigil (@, $, % & are sigils) to turn it into a reference.		 
Commands used to list / search source lines:
l [sub] – shows the next 10 lines of code; given a subroutine name, it will show the first 10 lines of that subroutine
l line – shows a single line of code
v [line] – shows a few lines surrounding the specified line number
S [pattern] – lists names of all subroutines matching pattern (hint: S ^main:: shows names of all user-defined subroutines)
/pattern/ - search forward for a line of code containing pattern
?pattern? - search backward for a line of code containing pattern		 
What to do if you’re stuck:
h – general help
h [cmd] – more help on a specific command
See man perldebug or perldoc perldebug for more help		 
Debugging rpt/ reports on UNIX:
  1. Shell out of Summit (use the sh command on the Summit command-line)
  2. Open the report screen, enter search criteria, and click the Print button.  Do not click any buttons on the Print dialog.  If you click Print or Preview now, the report will execute and delete itself.
  3. Change to the directory (usually /var/tmp; see note below) containing the fleshed-out copy of the report.  There will be a file with a name such as rptAAAjZai8H-rplwisr.rb_1
  4. Open the file with the cool name in vi or equivalent.  Go to the bottom of the file and delete the call to unlink()
  5. Run the report with this command: ctperl -d rptAAAjZai8H-rplwisr.rb_1
  6. Each time you click Print or Preview on the Summit print dialog, you will make a new copy of the report in the temp directory.  You can tell these files apart because the last digit in the filename will increment with each new report.
Debugging prt/ reports on UNIX:
  1. Shell out of Summit (use the sh command on the Summit command-line)
  2. Open the force screen, search for or select some records, and click the Prt button.  Choose your format.
  3. Do something to find out where the temp file will be
  4. Change to the directory (usually /var/tmp; see note below) containing the temp file, which will have a randomly-generated name.
  5. ctperl $FORCEDIR/prt/reportname.r1 -t[name of table] -f[/path/to/tempfile]
Debugging rpt/ reports on Windows:
(Note: whenever you see ctperl in a command, translate that to perl -MCtperl for use on Windows)
  1. Shell out of Summit (use the sh command on the Summit command-line)
  2. Open the report screen, enter search criteria, and click the Print button.  Do not click any buttons on the Print dialog.  If you click Print or Preview now, the report will execute and delete itself.
  3. Browse to the directory %FORCEDIR%\tmp\reportTmp_SDS.  The bold-italicized part of the directory name is the username which you logged in to Summit, and may vary.  This directory contains the fleshed-out copy of the reports, with a name such as rptAAAjZai8H-rplwisr.rb_1
  4. Open the file with the cool name in vi or equivalent.  Go to the bottom of the file and delete the call to unlink()
  5. Run the report with this command: perl -MCtperl -d rptAAAjZai8H-rplwisr.rb_1
  6. Each time you click Print or Preview on the Summit print dialog, you will make a new copy of the report in the temp directory.  You can tell these files apart because the last digit in the filename will increment with each new report.
Q: The first thing I see is 'Debugged program terminated.  Use q to quit or R to restart.' Where did I go wrong?
A: Your program must compile before it can be run; most compilation errors arise from invalid syntax.  Perl will tell you more about what is wrong if you ask it nicely.  Here’s how: ctperl -c -Mdiagnostics report.x1
Q: When I print out a value (p $variable), nothing appears on the screen!
A: After perl executes the require 'sds.pl'; line of code, all output is redirected to the location referred to by the environment variable $SPOOLER.  To get it back, run this command in the debugger: select STDOUT
Q: How do I get a report into debug mode in Force?
A: Shell out of Spillman, change to the directory containing the report, and execute the following command: report dscript rpreport (Do not give the file’s extension!)
Choose the Debug option, and change the –S in the shebang line into a –d, save and exit.  When you run the report, it will put you in the debugger.