TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Debugging Features

This chapter contains the following debugging topics:


Parsing

apex_shell supports the csh "parse only" option -n. However, unlike csh, apex_shell always completely parses the script first. If an error is found, execution terminates with an error messages that identifies the line number of the offending statement.

Due to late binding, parsing will not catch all errors. Consider the following statement:

This might translate into a legal procedure call, (such as v.show, where v is a view object), or it might translate into gibberish. Static parsing is not capable of catching this type of problem.


Tracing

Apex shell supports the standard csh -x and -v tracing options. It also supports some more powerful options which provide additional detail.

Statement tracing indents statements to reflect the program structure. End statements are shown for clarity.

-v
trace statements (show each statement as it is executed)
-x
trace substituted statements (show each statement after substitutions)
-l
show line numbers in trace
-a
show subexpressions in trace (displays contents of substituted variables and arguments in calls)
-h
highlight each statement executed (opens a text window and colors statements as they executed)


Apex Shell Debugger

The apex_shell debugger is entered when a breakpoint is hit. The debugger displays a prompt and you can type a command.

Anything typed at the prompt which is not a debugger command is taken as a one-line shell command and is run in the context at which the program is stopped. Essentially, you have full access to interactive operation.

Variables can be displayed or set using the usual cshell command:

echo $var
(Show a single variable)
echo `foo.op`
(Show the result of object's operation)
set
(Show all variables)
set var="a b"
(Set a variable)

To see the debugger-specific commands, enter "?" a the prompt.

Commands
break (b)
set/show breakpoints
tbreak (tb)
set temp breakpoint
delete (d)
delete breakpoint
tdelete (td)
delete temp breakpoint
show (s)
show source lines
stack (st)
show stack
run (r)
continue execution
rerun (re)
rerun program
visit (v)
visit location in editor
bvisit (bv)
visit on break
evisit (ev)
visit on error
vstmts (vs)
visit each statement executed
hstmts (hs)
highlight each statement executed
hexec (he)
highlight statements already executed
cexec (ce)
clear statement info
trace (t)
enable/disable tracing
dump (du)
show compiled code
help (h)
show command info
kill
terminate script
number
run number statements then break


Debugger Quick Start

apex_shell -d causes the script to break at the first executable statement. apex_shell -e executes the script to the point of an error before breaking. When debugging lengthy scripts, sometimes it's easiest to insert a break_here statement in the script at the point where you want to start debugging.

We'll walk through a script by way of example, using the following commands:

Note that 1 will single step to the next line.

Start up in the debugger and display the program.


Debugging Standard cshell

Since Apex Shell is nearly a superset of cshell, in general apex_shell works for most scripts written in cshell. In particular, the Apex Shell debugger is a compelling tool to develop standard cshell scripts since there isn't a similar tool available elsewhere.

However, there may be cases where Apex Shell and cshell do not have exactly the same behavior. This is the same situation that sometimes occurs when moving cshell scripts from one architecture to another. If this happens, there are usually several different ways of doing the same thing, one of which works in both Apex Shell and cshell. Typically, breaking up a single complex statement into simpler component statements does the trick.

Use the +A option when invoking standard cshell scripts to suppress Apex Shell extensions.


Apex Optimization

Statements in an Apex Shell script which run certain Apex commands will execute the command directly, without forking a separate process.

These command names are:

apex_display
apexd
testmgmt
apex_guigen
apex_action
Apex_Build_Support

This can have some performance benefit for a long running shell script with many invocations.


Debugging Server Scripts

To change options in a running server which processes Apex Shell or dlisp scripts, there are special subcommands of apex_display.

For example,

With no value given, it enables statement level tracing.

The other values are:

off
turn tracing off
all
includes subexpression tracing
lines
includes line numbers in trace
stmts
no subexpression tracing
original
trace statements before substitution
resolved
trace statements after args evaluated
visit_errors
visit source file on line with error
visit_stmts
visit statements as they execute
visit_exprs
visit every subexpression executed for dlisp
hilite_stmts
highlight statements as they execute
hilite_errors
highlight statements on which an error occurs
dump_original
show original statement in tree dump
dump_internals
show more information in tree dump
stdout
have the script tracing go to the standard output

For example:

These can be suffixed with 0 to disable that characteristic, For example:

If the server which is running a script that you are debugging is also the server which is used to visit files, the visiting and highlighting capabilities will not be available.

Set a Script Breakpoint

To set a script breakpoint in a server which processes these scripts you can use:

For example:

The value(s) can be

To remove all script breakpoints from within a server:

When a server encounters a script breakpoint and its standard input and output are not set to an xterm, it automatically creates an xterm window and redirects the input and output to that xterm.

If a server has been explicitly started in an xterm then this will not be necessary and the script debugging will be done there.

Script Tracing and Breaking Options

For a command executable which might invoke the Apex and Summit interpreter as part of its execution and run an Apex Shell script, for example, the taskmgmt executable running a customization action, there are command line options to control script tracing and breaking which can be given on that executable's command line:

-script_trace (-st)

-script_trace_value (-stv) <value>

-script_break (-sb) <value>

For Example:

The values to give to these options are as described above for the apxd script_... commands. A two token value must be given as a single quoted string.

Reread the .dlisp file

Changes made to server scripts must be reread to be recognized by the server. For example, the debugger is run by the compiled version of a server script and changes to the script cannot be seen by the debugger until the script is reread.

For the dialog server, the command to reread a .dlisp file is:

To parse the file and check for errors, highlighting the errors in the editor:

For editor action files, the server can reread all of its rules files from the menus path. This command is:

To parse an editor rules file:


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS