TAA Tools
TRCDBG          TRACE DEBUG                            TAADBGB

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  creates a  spooled file with  the trace  output and displays
it (by default).


Variable                *...+....1....+....2....+....3....+....4....+
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

You  may  trace  all  RPG  statements by  entering  specific  statement

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

  **   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

  **   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

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:


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

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

   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

   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.


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.


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


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


  TAADBGBC   CL Pgm - Does STRDBG and names TAADBGBR

     TAADBGBR  RPG Pgm - Does debug work - Called from API


Added to TAA Productivity tools January 15, 2002

Home Page Up to Top