The Trace Debug tool provides a trace of a program describing the
original source statements as they are executed and optionally
describing the values of named variables. Both OPM and ILE programs
are supported (CRTSQLxxx is not). The source member used for the
create must exist.
A specific create option is required to provide the debug information
in the object.
OPM OPTION(*SRCDBG)
ILE DBGVIEW(*SOURCE)
Only a single module per ILE program can be debugged at one time.
TRCDBG can be very effective, but is not a fast performer. For a
faster execution of your program, you will want to minimize the
number of statements being traced.
Assume you have created an RPG ILE program using CRTBNDRPG ...
DBGVIEW(*SOURCE) and you now want to debug the program from SEU
statement numbers 8.00 to 16.00. You want to display the values of
the fields RQSTYP and DCCHGD when they change. You would enter:
STRTRCDBG PGM(xxx) STMT(800 1600) PGMVAR(TYPE COUNT)
You then enter a command that will cause the program to be run during
the processing of the command (it could be a call to the program).
When your command completes, you enter:
ENDTRCDBG
ENDTRCDBG creates a spooled file with the trace output and displays
it (by default).
---------------------------------------------------------------------
Variable *...+....1....+....2....+....3....+....4....+
TYPE
Variable *...+....1....+....2....+....3....+....4....+
COUNT 00000
Seq SEU Stmt Source Statement
1 8.00 C MOVE 'ABC' CHAR3
2 9.00 C MOVE CHAR3 TYPE
Variable *...+....1....+....2....+....3....+....4....
TYPE ABC
3 10.00 C ADD 7 COUNT
Variable *...+....1....+....2....+....3....+....4....
COUNT 00007
4 11.00 C TYPE IFEQ 'DEF'
5 13.00 C ENDIF
6 14.00 C TYPE IFEQ 'ABC'
7 15.00 C ADD 15 COUNT
Variable *...+....1....+....2....+....3....+....4....
COUNT 00022
8 16.00 C ENDIF
---------------------------------------------------------------------
**********************************************************************
Heading lines that describe command options and source information
**********************************************************************
** Both a sequence number (consecutively assigned to each print
line) and the first line of each SEU statement are shown.
** The spooled file will allow for a 100 bytes of each source
statement to be printed (the sample is truncated).
** All specified variables are shown with their initial value at
the beginning of the trace. After that, the variable value is
only shown if it changes. An option exists to print all
specified variable values when any one changes. Up to 32K of
data may be printed for a variable with options to start at a
specific position and restrict the maximum length.
Special handling of RPG programs for STMT(*ALL)
-----------------------------------------------
The default for STMT is *ALL. Tracing all RPG statements is not
generally desired because all I, D, and O specs will be debugged.
This causes extra clutter and slower performance.
Because of this, the meaning of *ALL is changed for RPG programs to
mean all the RPG C specs (Some Op Codes like PLIST and PARMS are
bypassed).
You may trace all RPG statements by entering specific statement
numbers.
Additional Comments
-------------------
** The source member must exist where the object was created
from. The last change date of the source member must agree
with the equivalent date stored in the program. This avoids
all the confusion which can occur when attempting to debug
source which does not agree with the object.
** STRTRCDBG ends debug mode if it is active and then starts
debug mode. ENDTRCDBG ends debug mode.
** You must use ENDTRCDBG to not only cause the spooled file of
trace information, but also to allow cleanup of work spaces.
Even if you decide you do not want the spooled output,
ENDTRCDBG should be run.
** When debugging CL programs, the variable names are entered
without an & and without quotes. To see the value of &VARA,
you would specify PGMVAR(VARA).
** The trace output shows the changed variables after the
statement that made the change. In some cases this cannot be
done such as some uses of the RPG CHAIN and READ operations
(the changed values appear after the following statement).
** In some cases, RPG code shows the first statement as being run
after an operation such as EXCPT. This is based on the
internal implementation of the RPG object code.
Advantages of TRCDBG over the system debuggers
----------------------------------------------
** A trace function is not provided for ILE programs. Only the
interactive function exists.
** There is less to learn. You do not need to become an expert
about the interactive debug display.
** There are far fewer interactions to get good debug
information.
** The last source change date of the source must match the
equivalent date in the program. This avoids the problem of
attempting to debug source which does not agree with the
object.
** Each use of STRTRCDBG ends debug (if it was active) and enters
debug mode. Each use of ENDTRCDBG ends debug mode. This
avoids the error where ENDDBG must be specified before another
STR command can be used.
** The SEU statement numbers are used to describe what should be
debugged rather than an internal consecutively assigned
number. This avoids all the confusion of attempting to
determine which statement should be debugged and which should
be changed.
** The trace shows the actual source statements and specified
variables as they are changed. The spooled file is a
permanent record of execution rather than relying on the
interactive step function which can be difficult to follow and
does not allow a review.
** Allowing a range of statements provides a better solution than
describing breakpoints. You do not have know where the
problem is to get some debug information. When a logic
problem exists, it can be difficult to set a breakpoint
because you must know where the problem is. The range of
statements allowed by STRTRCDBG provides a more 'forgiving'
type of debug approach.
** The value of a variable that has changed appears after the
statement that has changed it (some exceptions exist). Some
debug approaches do not show the changed value until the
following statement is executed.
** Flexibility in displaying the contents of large variables is
provided.
Placing the debug option into the source member
-----------------------------------------------
The SBMPARMS TAA Tool allows you to place the debug option (such as
OPTION(*SRCDBG) into the source. For example, for OPM RPG source you
would enter:
F*PARMS OPTION(*SRCDBG)
The special PARMS comment must appear within the first 5 statements
in the source.
To use the PARMS statement in the source, you must use a special PDM
option or the Programmer Menu exit function.
For example, you can add a 'CP' Option (Compile program) to PDM and
use it instead of Option 14. See the discussion with the SBMPARMS
tool.
STRTRCDBG escape messages you can monitor for
---------------------------------------------
None. Several CPF9898 messages are sent for invalid command
parameters, missing source, etc.
Escape messages from based on functions will be re-sent.
STRTRCDBG Command parameters *CMD
----------------------------
PGM The program named to be debugged. Both OPM and ILE
programs are supported.
OPM programs must be created with OPTION(*SRCDBG).
ILE programs must be created with DBGVIEW(*SOURCE).
MODULE The MODULE parameter names the module to be debugged
if an ILE program is named in the PGM parameter.
The default is *PGM meaning the same name as the
program. The default should be used when a
CRTBNDxxx command was used to create the program.
Only a single module at a time may be debugged for a
multi-module program.
This parameter is ignored for OPM programs.
STMT The statements to be traced. *ALL is the default to
trace all statements.
If an RPG program is specified, *ALL means all C
(Calculation) Specs. To trace RPG Input and Output
specifications, a specific range of statements must
be entered.
One or more ranges of statements may be specified.
The source statement number should be specified.
For example, if you want to trace from the statement
shown in SEU as 37.00 to 52.00 you would enter
STMT(3700 5200).
A single statement may be entered such as STMT(3700)
meaning trace only that statement (the To statement
will default to the From statement).
PGMVAR The program variables to be traced. Up to 10
variable names may be entered.
RPG field names should be entered normally.
CL variable names should be entered without the
leading & and without surrounding quotes. For
example, to display &VARA, use PGMVAR(VARA).
The maximum size of the output for any field is
65,456.
MAXTRC The maximum number of statements to be traced. The
default is 20,000. When the maximum is reached, the
program continues to run, but no more tracing
occurs. The value must be between 1 and 99999.
UPDPROD A *YES/*NO value for whether to allow update of
production data.
The parameter has the same meaning as on any system
debug command.
The default is *NO meaning the command to be run
will not attempt to update any data base objects.
Note that the program to be debugged may be 'read
only', but if the command being run attempts to
change a data base object, the trace will fail.
*YES must be specified if the command to be run will
cause changes to data base objects.
START The start position of the output variables to be
debugged. The default is 1.
Naming a specific start position may be helpful when
a large variable must be displayed in the PGMVAR
parameter.
LEN The length of the output variables to be displayed.
The default is *DCL meaning the full length of any
variables named in the PGMVAR parameter will be
output. The maximum variable size that can be
output is 32K.
A specific length may be entered to describe a
maximum length that may be output.
OUTFMT The output format of the variables named in the
PGMVAR parameter. The default is *CHAR meaning the
data will be displayed as character. Decimal fields
will appear as digits.
*HEX may be specified to display the variables in
hex format.
*BOTH may be specified to display the variables in a
side-by-side view in both character and hex format.
OUTVAR The value determines when the variables named in the
PGMVAR parameter will be output. *CHGONLY is the
default meaning that the variable value is output
only when it changes. For example, if PGMVAR(VAR1
VAR2) is specified, and VAR1 is changed in the
program, only the value of VAR1 would be output.
*CHG may be specified to output all of the variable
values named for PGMVAR when any one of them
changes. For example, if PGMVAR(VAR1 VAR2) is
specified, and VAR1 is changed in the program, both
VAR1 and VAR2 would be output.
PRTHEADING A *YES/*NO value for whether page headings should be
printed after the first page. The default is *NO so
that only the first page will have a heading. This
allows the use of DSPSPLF to be uncluttered with
page headings.
*YES may be specified to cause a page heading for
each page.
ENDTRCDBG Command parameters *CMD
----------------------------
DSPTRCSPL A *YES/*NO value for whether to display the spooled
file of trace data. The default is *YES to display
the spooled file.
*NO may be specified which will cause the spooled to
be created, but not displayed.
If the command is run in batch, *NO is assumed.
Restrictions
------------
OPM programs must be created with OPTION(*SRCDBG).
ILE programs must be created with DBGVIEW(*SOURCE). Only a single
module per ILE program can be debugged at one time.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHGUSRSPC Change user space
CRTUSRSPC Create user space
EDTVAR Edit variable
EXTLST Extract list
MOVCHRDEC Move character to decimal
PMTOPR Prompt operator
RSNALLMSG Resend all messages
RTVDIAGMSG Retrieve diagnostic message
RTVILEMODA Retrieve ILE module attributes
RTVPGMA Retrieve program attributes
RTVSYSVAL3 Retrieve system value 3
RTVUSRSPC Retrieve user space
SNDCOMPMSG Send completion message
SNDDIAGMSG Send diagnostic message
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
STRTRCDBG *CMD TAADBGB QATTCMD
ENDTRCDBG *CMD TAADBGB2 QATTCMD
TAADBGBC *PGM CLP TAADBGBC QATTCL
TAADBGBC2 *PGM CLP TAADBGBC2 QATTCL
TAADBGBR *PGM RPGLE TAADBGBR QATTRPG
Structure
---------
STRTRCDBG
TAADBGBC CL Pgm - Does STRDBG and names TAADBGBR
TAADBGBR RPG Pgm - Does debug work - Called from API
ENDTRCDBG
TAADBGBC2 CL Pgm
|
