TAA Tools
STRBCHDBG       START BATCH DEBUG                      TAADBGD

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
					

Added to TAA Productivity tools April 15, 2005


Home Page Up to Top