TAA Tools
    My commands are TRACE and TRC
BKP             BREAKPOINT (DEBUG FRONT END)           TAADBGA
---             ----------------------------           -------

The debug  with breakpoint tool  provides several commands  to simplify
using debug on OPM programs:

     BKP         Debug with breakpoint
     TRACE       Debug with trace
     STEP        Debug with step trace
     DBGVAR      Display debug variable
     CHGDBGVAR   Change debug variable

These commands  work together in conjunction with a  data area in QTEMP
and  a prompt override  program to simplify what  needs to be specified
to work with the system debug function.

The commands are normally run from the command entry display.

Sample BKP scenario
-------------------

Assume  you  want  to  enter  debug  for  PGMA,  set  a  breakpoint  at
statement  42.00, and display  the variables  ABC and  XYZ.   You would
issue the following commands:

     BKP        STMT(4200) PGMVAR(ABC XYZ) PGM(PGMA)
     CALL       PGMA

The  BKP  command  would  issue  the  STRDBG  command  and  the  ADDBKP
command.  If  you are  already in  debug mode, the  command ends  debug
and issues  STRDBG again.  When  the CALL command runs,  the breakpoint
display  would occur  just prior  to executing  statement 42.00.   Note
that the statement  numbers are entered  the same as they  are for  the
normal debug commands.

It  is  fairly  normal to  find  that  whatever  breakpoints  you  have
requested  are  insufficient  after  running  your command.    The  BKP
command  makes it  easy to request  a different breakpoint  on the same
program.   Once  a program  and  variables have  been  named, they  are
remembered  in  a  data  area   in  QTEMP  and  used  as  the  default.
Therefore,  if  you  wanted  to  issue  another  breakpoint, you  would
specify:

     BKP        STMT(5500)
           or
     BKP        5500

The variables  you  specified earlier  would  be  displayed.   You  can
modify  the  variables to  be  displayed  at  any  time.   The  typical
solution  would be to prompt  for the BKP  command so you  can key over
what already exists.

Many users are  confused or  make errors  when attempting  to debug  CL
programs  because the  variables  to  be  displayed must  be  specified
within apostrophes such as:

         ... PGMVAR('&ABC' '&XYZ')  /* System solution */

This problem  is eliminated with  the BKP tool.   You do  not enter the
apostrophes or the ampersand (&).

         ... PGMVAR(ABC XYZ)  /* BKP tool solution */

This  makes debugging  other HLL programs  and CL  programs appear very
similar.

Note that  the  data area  used  in QTEMP  by  the BKP  commands  still
exists even  though you re-create the  program.  Thus  the following is
valid.

     BKP        STMT(4200) PGMVAR(ABC XYZ) PGM(PGMA)
     CALL       PGMA
                /* At this point you discover the error, correct */
                /*   the source and re-create.                   */
     BKP        4200
     CALL       PGMA
                /* Variables ABC and XYZ would be displayed again */

You  can also specify  a conditional  breakpoint.  This  can be helpful
if you have  an error that  does not appear  until a particular  record
is read from the  data base.  Rather than trace or  get a breakpoint on
every  record,  you would  specify  the unique  condition  at  which to
start.  For  example, if you  wanted to start the  breakpoint when  the
field CUST = 12345, you would specify:

     BKP        STMT(4200) PGMVAR(ABC XYZ)
                  BKPCOND(CUST *EQ 12345) PGM(PGMA)

Sample TRACE scenario
---------------------

The TRACE  command operates in  a similar manner  to BKP.   You specify
the  trace  points  and any  variables  to  be  displayed.   A  typical
sequence of commands would be:

     TRACE      STMT((3500 4200)) PGMVAR(ABC XYZ) PGM(PGMA)

The  TRACE  command  uses  a  default  of  4000  statements  before the
'maximum trace'  condition  occurs instead  of  the STRDBG  default  of
200.

If you had already specified:

     BKP        STMT(4200) PGMVAR(ABC XYZ) PGM(PGMA)

you can now specify:

     TRACE      STMT((3500 4200))
            or
     TRACE      (3500 4200)

the program  name and  the variables are  picked up  automatically from
the data area.

To debug all statements you would specify:

     TRACE

Sample STEP scenario
--------------------

The  STEP command is  a special  form of trace  that allows  you to see
one statement number at  a time while your  program is executed.   STEP
is  achieved  by  specifying  MAXTRC(1)  thus  forcing  the  breakpoint
display after  each statement is executed.   No variables are displayed
when the  breakpoint screen  occurs,  but you  can access  the  command
entry display using F10  and then display variables.   An error message
is  shown at  the bottom  of the  breakpoint  display stating  that the
maximum  number of trace  statements has been reached.   You must press
'Error  Reset'  and  'Enter'  to  advance  the  program   to  the  next
statement.  A typical command would be:

     STEP       STMT((3500 4200)) PGM(PGMA)

If you have already specified the program name, you need say only:

     STEP       STMT((3500 4200))
           or
     STEP       (3500 4200)

To see all of the statements in execution, specify:

     STEP

STEP can also work in conjunction with BKP.  See the next section.

Using F10 from the breakpoint display
-------------------------------------

When the  'Display Breakpoint'  display occurs from  either the  BKP or
STEP  function, pressing  F10 brings  you to  a command  entry display.
You can then enter  other BKP, TRACE or STEP  commands.  You return  to
the  'Display Breakpoint'  display  by pressing  F3.   Pressing  'Error
Reset'  and 'Enter'  then resumes  the debug  process and  will utilize
your new statements as well as the old.

Note that at  this point  you could have  BKP, TRACE  and STEP  active.
This only  occurs when  TRACE or  STEP is  run from  the command  entry
display after F10.

BKP, TRACE, and  STEP will all attempt to ENDDBG  and STRDBG as part of
their  processing.    ENDDBG  will  fail  from  the  F10  command entry
display because you  are already in debug.   This is monitored  for and
a different completion message is sent.

The  DBGVAR  and CHGDBGVAR  commands  are  normally  only used  on  the
command  entry   display  after  F10  is  used.    These  commands  are
primarily simple front  ends to  DSPPGMVAR and CHGPGMVAR,  but they  do
take  advantage of  the existing  information in  the data  area.   For
example,  if you  have  previously specified  some variables  on  a BKP
command, you can display them with:

     DBGVAR

As an example of how all of  the commands can be used, assume that  you
are having difficulty  with your program beginning at  statement 50.00.
You want  to set a  breakpoint at 50.00 and  then use STEP.   You would
specify:

     BKP        STMT(5000) PGM(PGMA)
     CALL       PGMA

The  breakpoint display  would appear  at statement  50.00.   You would
press F10 to access the command entry display.  Then request STEP.

     STEP

Press F3 to return  to the breakpoint display.   Press Error Reset  and
Enter to  advance the  program.   At statement 55.00,  you want  to see
the  value of  variable XYZ.   Press  F10 to  access command  entry and
enter:

     DBGVAR     XYZ

Advantages
----------

Not all  of the functions  supported by  the debug  function are  valid
with the BKP tool  commands.  The intent is  to simplify the interface.

The following are the major advantages:

  **   Simpler

  **   Less key strokes

  **   Less error prone

  **   Faster  (less system interaction).   The time  to perform actual
       debug is not improved

The following are detail advantages:

  **   The command  prompter  can be  more  easily used.    The  normal
       ADDTRC  and ADDBKP  command prompts  are  confusing and  require
       multiple displays.   The BKP prompts are  simple and normally do
       not require additional displays.

  **   Following  a  successful  BKP,  TRACE,  or  STEP  command  is  a
       completion message that  reminds you what  to do.  For  example,
       after TRACE the  message tells you to run  your command and then
       use DSPTRCDTA.

  **   To  minimize the amount of re-keying,  a data area named DBGCMDS
       is created in QTEMP as part  of BKP, TRACE, and STEP.  The  data
       area  contains the  last  values  specified for  the  parameters
       PGMVAR,  PGM,  UPDPROD,  OUTFMT, and  MAXTRC.    If  a value  is
       entered on a  command, it  is inserted  into the  data area  and
       used as  the default.   This is achieved  in combination with  a
       prompt override program.

       The  advantage is  that once  you make  a specification  such as
       the  program name, the  other commands assume  that program name
       by default.   You do  not have to  re-specify program name  even
       though  debug is  ended and  restarted by  BKP, TRACE,  or STEP.
       The  same is  true  of UPDPROD,  MAXTRC, and  OUTFMT.   When you
       prompt for the commands, you  will see the value that exists  in
       the data area.

       Program variables  are also  treated in the  same manner.   Once
       you  decide what  variables you  want to  display, they  are the
       assumed default until you change your specification.

  **   The BKP commands do  not require the  entry of apostrophes  when
       entering  program variables  for  CL  programs.   The  variables
       must  be entered  without  apostrophes and  without  the leading
       ampersand (&).

  **   The  BKP commands  will ignore the  error if you  are already in
       debug mode.    For example,  a  typical error  would  be to  use
       STRDBG  followed   by  ADDBKP   and  then  decide   a  different
       breakpoint  is needed or maybe a  different program.  Many users
       prefer  to  start  over  with  debug  and  therefore  enter  the
       following command sequence:

              ENDDBG
              STRDBG  ...
              ADDBKP  ...

       With the BKP commands, you just enter a single command:

              BKP     ...

       If debug  is active,  it is ended  and a  new STRDBG  command is
       internally run.  You must still use ENDDBG when complete.

       If ENDDBG  cannot be run, the typical reason  is that you are on
       the F10 command  entry display.   This  is monitored  for and  a
       different completion message occurs.

  **   Another  confusing  situation  is  also  avoided  with  the  BKP
       commands.   Assume  you have used  STRDBG and  ADDBKP.   You see
       the  error  and correct  the  source and  re-create  the program
       taking the default  of REPLACE(*YES).  You  now want to try  the
       same or a  similar debug test.  If you  forget to specify ENDDBG
       and  start over, the  system responds  by acting as  if debug is
       not  active.   This  is  caused  by  the  fact  that  the  debug
       function  is  still  partially   pointing  at  the  old  program
       version  in the  QRPLOBJ library.   This  is another  reason why
       many programmers always treat each  debug test by starting  over
       rather than trying to fully understand what is required.

  **   If  errors occur  with  the  normal debug  commands,  diagnostic
       messages are  sent followed by the CPF1999  escape message which
       states   'Errors  occurred  on  command'.     The  BKP  commands
       eliminate  this  escape  to  make  the   errors  more  readable.
       Instead,  the last  or only  diagnostic  message is  sent as  an
       escape message.

       Certain  messages  are  handled by  the  BKP  command processing
       programs and  the  text  is  altered.   For  example,  if  a  CL
       program is  being debugged and the  variable cannot be  found to
       display, the  message text will not  include the apostrophes and
       the ampersand.

       Another example is  where the statement  number cannot be  found
       because a  2 or 3  digit sequence number  was used which  is the
       normal  way you think  about statement  numbers in  SEU (without
       the  trailing two zeros).   In this  case, the text  will ask if
       you meant to include the extra two zeros.

  **   The MAXTRC  default  for  tracing is  4000  instead of  the  200
       default on the STRDBG command.

Forgetting to specify ENDDBG
----------------------------

Because  the BKP,  TRACE, and  STEP commands  automatically  use ENDDBG
when they  are executed, it is normal to  forget to use ENDDBG when you
are finally completed debugging.

SEU provides  a message  when  you enter  that says  you are  in  debug
mode.   It is awkward if  you enter SEU  and miss the message  and make
several  changes because  you cannot  make the  updates while  in debug
mode to a production library.

You can get  to a  command entry  line in  the middle  of any  function
(including SEU) by use of  the TAA Tool SYSRQSCMD.  You  can then enter
ENDDBG and return  to the function you would  like to achieve, but were
prevented by the debug function.

BKP command parameters                                *CMD
----------------------

The  BKP command starts  debug and establishes  one or more breakpoints
for a program.  The variables to be displayed can be specified.

   STMT          The statement(s) for the  breakpoint to occur at.   Up
                 to 10 statements can be entered.

   PGMVAR        The  program variable(s) to  be displayed.   Up  to 10
                 names may be specified.

                 Variable  names  are  optional.    The variable  names
                 will be  the  same as  those  used  on the  last  BKP,
                 TRACE,  or STEP  command.   If  no  variable name  was
                 ever supplied, the default is *NONE.

                 For  CL   variables,  the  name  without  the  leading
                 ampersand (&) and no  beginning or ending  apostrophes
                 must be entered.

   BKPCOND       The breakpoint condition.   This is a 3  element list.
                 The  default  is  none.   This  is  the same  function
                 provided on the ADDBKP command.

                 VARIABLE:   The  variable  to  be  compared  to.    CL
                 variables  must   be  entered   without  the   leading
                 ampersand and without the surrounding apostrophes.

                 OPERATOR:   The  compare   operator.     One  of   the
                 following  may be  entered: *EQ,  *GT, *LT,  *NE, *GE,
                 *NL, *LE, *NG, or *CT.

                 COMPARE VALUE: The value to  be compared against.   It
                 cannot be a variable name.

   PGM           The  qualified  program  name  of the  program  to  be
                 debugged.   Unlike the normal  debug commands, you can
                 only debug a single  program at a  time.  The  library
                 defaults to  *LIBL.   If a  program has  been used  by
                 one of  the BKP commands,  the library of  the program
                 will appear in the next prompt.

                 The  program name  is an  optional parameter  once you
                 have  entered  it on  a  prior  BKP,  TRACE,  or  STEP
                 command.

   UPDPROD       A *YES/*NO value  that has the same meaning  as on the
                 STRDBG command.

                 The  value  is  optional.   The  default  will  be the
                 value you  used  on a  previous  BKP, TRACE,  or  STEP
                 command.  If  no value was ever  supplied, the default
                 is *NO.

   OUTFMT        The  format  of the  output.   *CHAR  or  *HEX  may be
                 specified and has  the same meaning  as on the  normal
                 debug commands.

                 The  value is  optional.    The  default will  be  the
                 value  you used  on a  previous  BKP, TRACE,  STEP, or
                 DBGVAR  command.  If  no value was  ever supplied, the
                 default is *CHAR.

TRACE command parameters                              *CMD
------------------------

The TRACE command  causes the system  to trace the executed  statements
within a  specified range(s).   You  display the trace  data by  use of
the DSPTRCDTA command.

   STMT          The  starting  and  ending  statements  to  be traced.
                 This is  a  list  of  two entries  per  range  with  a
                 maximum of  10 ranges.  *ALL  is the default  and will
                 trace all statements in the program.

   PGMVAR        The  program variable(s)  to be displayed.   Up  to 10
                 names may be specified.

                 Variable names  are  optional.    The  variable  names
                 will  be the  same  as those  used  on the  last  BKP,
                 TRACE,  or STEP  command.    If no  variable  name was
                 ever supplied, the default is *NONE.

                 For   CL  variables,  the  name  without  the  leading
                 ampersand (&) and  no beginning or  ending apostrophes
                 must be entered.

   PGM           The  qualified  program  name  of the  program  to  be
                 debugged.   Unlike the normal  debug commands, you can
                 only debug a  single program at a  time.  The  library
                 defaults to  *LIBL.   If a  program has  been used  by
                 one  of the BKP  commands, the library  of the program
                 will appear in the next prompt.

                 The program  name is  an optional  parameter once  you
                 have  entered  it  on a  prior  BKP,  TRACE,  or  STEP
                 command.

   UPDPROD       A *YES/*NO  value that has the same  meaning as on the
                 STRDBG command.

                 The  value  is  optional.   The  default  will  be the
                 value you  used  on a  previous  BKP, TRACE,  or  STEP
                 command.   If no value was ever  supplied, the default
                 is *NO.

   OUTFMT        The  format  of the  output.    *CHAR or  *HEX  may be
                 specified and has  the same meaning  as on the  normal
                 debug commands.

                 The  value  is optional.    The  default will  be  the
                 value  you used  on a  previous  BKP, TRACE,  STEP, or
                 DBGVAR command.   If no value  was ever supplied,  the
                 default is *CHAR.

   MAXTRC        The maximum number of statements to be traced.

                 The  value is  optional.    The  default will  be  the
                 value  you used on  a previous  TRACE command.   If no
                 value  was ever  supplied, the  default is  4000 which
                 differs from the STRDBG default of 200.

STEP command parameters                               *CMD
-----------------------

The STEP command is a  special form of trace that allows you  to single
cycle  through your  program.   This  is achieved  by using  MAXTRC(1).
This  will cause a breakpoint  display after each statement.   You must
press 'Error  reset' and  'Enter'  to advance  to the  next  statement.
You  cannot display  variables  on the  breakpoint  display.   You  can
display variables  by using F10 and accessing  a command entry display.

   STMT          The starting  and  ending  statements  to  be  traced.
                 This  is a  list  of  two  entries per  range  with  a
                 maximum of  10 ranges.   *ALL is the  default to trace
                 all statements in the program.

   PGM           The  qualified  program  name  of  the  program  to be
                 debugged.  Unlike the  normal debug commands, you  can
                 only debug  a single program  at a time.   The library
                 defaults  to *LIBL.   If  a program  has been  used by
                 one of the  BKP commands, the  library of the  program
                 will appear in the next prompt.

                 The program  name is  an optional  parameter once  you
                 have  entered  it  on  a  prior  BKP, TRACE,  or  STEP
                 command.

   UPDPROD       A *YES/*NO value that has  the same meaning as on  the
                 STRDBG command.

                 The  value is  optional.    The  default will  be  the
                 value  you used  on  a  previous BKP,  TRACE,  or STEP
                 command.   If no value  was ever supplied, the default
                 is *NO.

DBGVAR command parameters                             *CMD
-------------------------

The Debug  Variable command  is  a simple  front end  to the  DSPPGMVAR
command.  It  can only be used after the  breakpoint display occurs and
you use F10 to access command entry.

   PGMVAR        The  program variable(s)  to be  displayed.  Up  to 10
                 names may be specified.

                 Variable names  are  optional.    The  variable  names
                 will  be the  same  as those  used  on  the last  BKP,
                 TRACE,  or  STEP command.    If no  variable  name was
                 ever supplied, the default is *NONE.

                 For  CL  variables,  the  name  without  the   leading
                 ampersand (&) and  no beginning or  ending apostrophes
                 must be entered.

   OUTFMT        The  format  of the  output.   *CHAR  or  *HEX may  be
                 specified  and has the  same meaning as  on the normal
                 debug commands.

                 The value  is  optional.    The default  will  be  the
                 value  you used  on a  previous BKP,  TRACE,  STEP, or
                 DBGVAR  command.  If  no value was  ever supplied, the
                 default is *CHAR.

CHGDBGVAR command parameters                          *CMD
----------------------------

The Change  Debug  Variable  command  is  a simple  front  end  to  the
CHGPGMVAR command.   The  new value  is moved  beginning in position  1
for the length of the value (not the length of the input area).

The  command can only be  used after the breakpoint  display occurs and
you use F10 to access command entry.

   PGMVAR        The program  variable(s) to  be displayed.   *NONE  is
                 the default.

                 For  CL  variables,  the  name   without  the  leading
                 ampersand (&)  and no beginning  or ending apostrophes
                 must be entered.

   VALUE         The  value  to be  assigned.   Up to  20 bytes  may be
                 entered.

   ADDQUOTES     Whether  quotes  should  be  added  to   surround  the
                 value.   The  default  is *NO  which  means no  quotes
                 will  be  added.   The  default  is  adequate  in most
                 cases where  the  first  character of  the  new  value
                 determines its type (character or decimal).

                 *YES  should be  specified  when a  value  such as  an
                 indicator  (0  or 1)  is  being set.    Indicators are
                 character  variables  and  quotes  must  be  added  to
                 avoid interpreting the new value as decimal.

Restrictions
------------

The full debug support is not provided.

CL variables  to be  displayed must  be entered  without the  ampersand
(&) and without the surrounding apostrophes.

Only OPM programs may be used.

Prerequisites
-------------

The following TAA Tools must be on your system:

          EDTVAR        Edit variable
          EXTLST        Extract list
          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
   ------        ----        ---------      ----------    ----------

   BKP           *CMD                       TAADBGA       QATTCMD
   TRACE         *CMD                       TAADBGA2      QATTCMD
   STEP          *CMD                       TAADBGA3      QATTCMD
   DBGVAR        *CMD                       TAADBGA4      QATTCMD
   CHGDBGVAR     *CMD                       TAADBGA5      QATTCMD
   TAADBGAC      *PGM           CLP         TAADBGAC      QATTCL
   TAADBGAC2     *PGM           CLP         TAADBGAC2     QATTCL
   TAADBGAC3     *PGM           CLP         TAADBGAC3     QATTCL
   TAADBGAC4     *PGM           CLP         TAADBGAC4     QATTCL
   TAADBGAC5     *PGM           CLP         TAADBGAC5     QATTCL
   TAADBGAC6     *PGM           CLP         TAADBGAC6     QATTCL

Structure
---------

The  CL program TAADBGAC6  is the prompt  override program used  by all
of the commands.

BKP
  TAADBGAC   CL pgm is the CPP

TRACE
  TAADBGAC2  CL pgm is the CPP

STEP
  TAADBGAC3  CL pgm is the CPP

DBGVAR
  TAADBGAC4  CL pgm is the CPP

CHGDBGVAR
  TAADBGAC5  CL pgm is the CPP
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top