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
|
