The Start Batch Debug command assists in debugging a program or
service program in batch. STRBCHDBG removes the tedious and
confusing steps involved in setting up an environment to debug in
batch. With STRBCHDBG, debugging in batch becomes about as easy as
debugging an interactive program. The ILE debugger is used to debug
(this will allow debugging of OPM programs).
If you are not familiar with debugging in batch, you should start
with the section 'Batch Debug Steps' so you have an understanding of
what STRBCHDBG must do.
In some cases the batch program you want to debug is submitted by a
complex program and passes parameters from the program. After you
understand the basics of STRBCHDBG, see the section on 'Submitting
from a program'.
Authority
---------
The user of the command must have *USE authority to the following
commands (the system shipped defaults allow QPGMR *USE authority):
STRSRVJOB
ENDSRVJOB
STRDBG
To debug a program, the user must have *CHANGE authority to the
program.
The *PUBLIC has *USE authority to the STRBCHDBG command, but
authority to the other required commands and authority to the program
are checked.
Using STRBCHDBG
---------------
STRBCHDBG issues the commands you need to debug a batch program. The
STRBCHDBG CPP is a CL program that uses system commands such as
SBMJOB, STRSRVJOB, STRDBG, RLSJOB. STRBCHDBG will also display
prompts to remind you of what to do. The actual debugging is
performed by the ILE debugger.
A typical command to enter would be:
STRBCHDBG PGM(xxx)
The program is checked to ensure that it can use the ILE debugger
OPM programs must specify OPTION(*SRCDBG)
ILE programs/modules must specify a DBGVIEW of
*SOURCE, *LIST, *COPY, or *ALL
The source and the object must be in synch. STRBCHDBG will not let
you proceed if the source has been changed after the program was
created.
A prompt would appear describing the SBMJOB prompt which will follow.
On the SBMJOB prompt, it is assumed that you will be submitting a
call to the program you described without any passed parameters. You
may change the command to be submitted for such things as 1) adding
parameters to be passed, 2) enter a different program name that must
be called first or 3) entering a command that will will eventually
invoke the program to be debugged.
HOLD(*YES) is specified to prevent the job from going into execution
until later commands are run and the job is released.
The JOBQ parameter specifies *JOBD as the default which uses the Job
Description associated with the user profile. You must ensure that
the job queue to be used will allow the job to go into execution
immediately when RLSJOB is run. A solution is to have a DBGJOBQ job
description which specifies a job queue that will allow immediate
execution.
If the batch job is not immediately active, the interactive job will
hang and debugging may not be successful.
After submitting the job, another prompt appears describing what will
appear next and the steps you must take. These include:
- Press Enter to display the 'Start Serviced Job' display
- Press F10 (this causes DSPMODSRC to be run)
- Enter debug commands such as set a breakpoint
- Press F3 twice to return to the 'Start Serviced Job' display
- Press Enter
- Debug the program
- End the program normally (avoid using F3 or 'End Request')
If the batch job ends normally, you will see a message sent to the
external message queue 'Job being serviced ended'. STRBCHDBG will
then perform cleanup.
If you end the batch program with F3 or 'End Request', then you must
enter:
ENDDBG
ENDSRVJOB
Batch debug steps
-----------------
The following steps are needed to debug a program in batch (some
different alternatives exist, but these are the steps followed by
STRBCHDBG). If you are not familiar with these steps, you should
enter them manually so you have a better understanding of what the
STRBCHDBG function does.
** The program must be created as follows:
OPM programs must specify OPTION(*SRCDBG)
ILE programs/modules must specify a DBGVIEW of
*SOURCE, *LIST, *COPY, or *ALL
** SBMJOB with HOLD(*YES). The CMD parameter should name the
program to be debugged. It could be a higher level program or
command which will eventually call the program you want to
debug.
The Job Description being used should specify a job queue that
will allow the job to go into execution immediately when
RLSJOB is used.
** STRSRVJOB of the job name that was submitted.
** STRDBG of the program you want to debug. If this is an OPM
program, you must specify OPM(*YES).
You normally specify DSPMODSRC(*NO). If the default *YES is
used, your source is displayed, but you cannot enter any debug
statements because the program is not active.
** RLSJOB to release the job so it goes active.
** The 'Start Serviced Job' display appears. Press F10 to access
a command entry display.
** Enter DSPMODSRC.
** Enter debug commands such as set one or more breakpoints.
** Press F3 twice to return to the 'Start Serviced Job' display.
** Press Enter and the debugger should stop the program at your
first breakpoint.
** Finish debugging the program.
** End the program normally (avoid using F3 or 'End Request').
** When the program ends, a message is sent to the external
message queue stating that the job being serviced has ended.
** Enter ENDDBG to end debugging.
** Enter ENDSRVJOB to end the service job.
Submitting from a program
-------------------------
In some cases the batch program you want to debug is submitted by an
interactive program which passes parameters (or a command with
parameters) These cases can be difficult to simulate with the basic
STRBCHDBG command.
A special solution exists for these cases with the JOB parameter.
The default for JOB is *SBMJOB meaning the job name will come from
the SBMJOB prompt.
If a job name is entered, you are requesting that the batch program
from a job held on a job queue is to be debugged.
The following are the requirements:
** The SBMJOB from your program must specify HOLD(*YES) to allow
the serviced job concept to occur and a release of the job.
This probably means you must make a temporary change to your
program to specify HOLD(*YES) on SBMJOB.
** There can only be one job of the specified name on a job
queue.
** As with STRBCHDBG the program that is submitted (it could be a
command with parameters) does not have to be the program named
on the STRBCHDBG PGM parameter. The program to be debugged
could be invoked later on in the batch job.
** As with the normal STRBCHDBG, you must ensure that the job
queue being used will allow immediate execution of the job.
When a specific job is named, the first display that normally appears
from STRBCHDBG is bypassed (it describes the SBMJOB prompt to
follow). The SBMJOB prompt that you normally see from STRBCHDBG is
bypassed and the second screen is displayed (it describes the use of
F10 etc).
You can test this function by doing the following (assume your
program to be tested is named TSTPGM):
SBMJOB JOB(DBGTST) CMD(CALL TSTPGM) HOLD(*YES)
STRBCHDBG PGM(TSTPGM) JOB(DBGTST)
The first display you see will describe the use of F10 etc.
STRBCHDBG escape messages you can monitor for
---------------------------------------------
None. Escape messages from based on functions will be re-sent.
Command parameters *CMD
------------------
PGM The qualified name of the program to be debugged.
The library value defaults to *LIBL. *CURLIB may
also be used.
You must ensure that the job queue used for SBMJOB
will allow the job to go into execution immediately
when RLSJOB is used internally by STRBCHDBG.
PGMTYPE The program type to be debugged.
*PGM is the default for *PGM objects.
*SRVPGM should be specified for *SRVPGM objects.
MODULE The module to be debugged. The default is *PGM
which must be used when debugging OPM programs.
If CRTBNDxxx was used, use the default.
If CRTPGM was used, you must specify the module name
to be debugged.
UPDPROD A *YES/*NO parameter for whether to allow update of
production objects. This value is passed thru to
the STRDBG command.
*NO is the default to prevent changes to production
objects (primarily data base).
*YES may be specified to allow changes.
JOB Whether the job name comes from the SBMJOB prompt or
has already been submitted.
*SBMJOB is the default meaning the name of the batch
job will be specified on the SBMJOB prompt.
A job name may be entered if the job has already
been submitted in with HOLD(*YES). There can only
be one job on a job queue with this name. See the
previous section on 'Submitting from a program'.
Restrictions
------------
** The source and the object must be in synch. STRBCHDBG will
not let you proceed if the source has been changed after the
program was created.
** You must ensure that the job queue used for SBMJOB will allow
the job to go into execution immediately when RLSJOB is used.
** The program must have been created to allow the ILE debugger
to be used and observability must still exist.
Prerequisites
-------------
The following TAA Tools must be on your system:
ADJVAR Adjust variable
EDTVAR Edit variable
FILEFDBCK File feedback
HLRMVMSG HLL Remove message
LOCKMSG Lock message
RSNALLMSG Resend all messages
RTVDIAGMSG Retrieve diagnostic message
RTVJOBSTS Retrieve job status
RTVILEMODA Retrieve ILE module attributes
RTVMODA Retrieve module attributes
RTVPGMA Retrieve program attributes
RTVPGMDBGA Retrieve program debug attributes
RTVSBMJOB Retrieve submitted job
RTVSRVMODA Retrieve service program module attributes
RTVSRVPGMA Retrieve service program attributes
SNDCOMPMSG Send completion message
SNDDIAGMSG Send diagnostic message
SNDESCINF Send escape information
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
STRBCHDBG *CMD TAADBGC QATTCMD
TAADBGCC *PGM CLP TAADBGCC QATTCL
TAADBGCD *FILE DSPF TAADBGCD QATTDDS
|
