TAA Tools
RTVSBSBCH       RETRIEVE SUBSYSTEM BATCH STATUS        TAAJOCZ

The  Retrieve Subsystem  Batch  Status command  is  intended to  be  an
assist  in determining  if any batch  jobs are  active in  a subsystem.
Return  values provide  information on the  number of  active jobs, the
number of batch jobs, and  the number for typical status types  such as
that caused  by DLYJOB.  A supplied  print command can be  used to help
determine the effectiveness of RTVSBSBCH.

Assume  you want to  end a subsystem when  there is no  more work.  How
do you make the determination?

It  can  be  a  simple  situation  if  a  subsystem  is   specified  as
MAXJOBS(1).    Or it  can  be  simple  if  a unique  subsystem  has  no
auto-start jobs  and has a single job queue  specified as MAXACT(1).  A
function such as the TAA Tool RTVSBSD  can be used to determine if  any
jobs are active.

However, other factors can make the determination complex such as:

  **   If the subsystem is specified as MAXJOBS greater than 1.

  **   If multiple job queues are feeding the same subsystem.

  **   If a job queue entry MAXACT value is more than 1.

  **   If auto start or pre-start jobs exist that remain active.

  **   If never ending jobs are submitted.

  **   If other  types  of jobs  exist in  the same  subsystem such  as
       interactive jobs.

All of these conditions are typical for the QBASE subsystem.

RTVSBSBCH is  designed for the case  where you want to  end a subsystem
when  there  is  no more  'actual  batch  work' being  performed.   The
definition of 'actual batch work' may vary per system.

RTVSBSBCH assumes that  jobs that are waiting  for some event (such  as
a data queue  entry) do not imply 'actual batch work'.   The default is
a  set of  standard values that  are typical  of jobs  that are waiting
for an event.  You may define your own status values to check.

In the  following  example,  RTVSBSBCH  is used  every  15  minutes  to
determine the number  of batch jobs and  the number of jobs  that match
a  list  of status  values.   The  standard  list is  used.    If these
numbers match,  the  program  delays  for 10  seconds  and  then  loops
again.  If  the numbers match 3 times  in a row, it is  considered that
no actual  batch work is  being performed.   At that point  it would be
assumed safe to end the subsystem.


             DCL        &BCHJOBS *DEC LEN(5 0)
             DCL        &WATSTS *DEC LEN(5 0)
             DCL        &COUNT *DEC LEN(5 0)
              .
 LOOP:       RTVSBSBCH  SBS(xxx) BCHJOBS(&BCHJOBS) WATSTS(&WATSTS)
             IF         (&BCHJOBS *EQ &WATSTS) DO /* All waiting */
             CHGVAR     &COUNT (&COUNT + 1)
             CHGVAR     (&COUNT *LT 3) DO /* LT 3 times */
             DLYJOB     DLY(10) /* Wait 10 seconds */
             GOTO       LOOP
             ENDDO      /* LT 3 times */
                        /*                                        */
                        /*      Your processing to end the SBS    */
                        /*                                        */
             ENDDO      /* All batch jobs are waiting             */
                        /* Number of jobs is not the same */
             CHGVAR     &COUNT 0
             DLYJOB     DLY(900) /* Wait 15 minutes */
             GOTO       LOOP

The  system does not  have a strict  definition of a  batch job.  There
can be  traditional batch jobs  submitted from  a job queue,  pre-start
jobs, auto-start jobs,  evoked jobs (started by a  procedure), MRT jobs
(multiple requestor terminal), etc.

WRKACTJOB  describes  the different  types such  as  BCH in  the 'Type'
column.  You may  position the cursor to this  column and use the  Help
key to see the descriptions of the different types.

RTVSBSBCH determines batch  jobs by using the CVTWRKACT  TAA Tool which
creates an  outfile of information.  The  value shown on WRKACTJOB such
as BCH does not exist in the  outfile, but the same information can  be
determined by using the  AJTYPE and AJSUBT fields in the  outfile.  The
following chart describes this:

                     CVTWRKACT Fields
                     ----------------
   WRKACTJOB Type    AJTYPE   AJSUBT     Description
   --------------    ------   ------     -----------

        BCH             B                 Normal batch job
        ASJ             A                 Auto start job
        EVK             B        E        Evoked job
        PJ              B        J        Pre-start job

WRKACTJOB  provides  a status  for  each  job.   You  may position  the
cursor  to  the  'Status'  column  and use  the  Help  key  to  see the
descriptions of  the different status  values.  A  few of these  status
values  are typical  of user  applications  that are  waiting for  some
event.

RTVSBSBCH  uses a return value  WATSTS to describe how  many jobs match
the specified  status values.   The  following are  the default  values
that are checked for:

    Status
    ------

    DEQW      - Used by various functions including a DTAQ wait
    DLYW      - Used by DLYJOB
    EOFW      - Used by the data base OVRDBF EOFDLY function
    EVTW      - Used by some functions for an event wait
    MSGW      - Used when waiting for a message
    PSRW      - Used for pre-start jobs wait function

You may  define your  own list  to match  your requirements.   See  the
later discussion of the SBSBCHSTS data area.

Testing RTVSBSBCH with the PRTSBSBCH command
--------------------------------------------

A  special command PRTSBSBCH  exists to allow  you to try  the function
to ensure that the correct decision is being made on your system.

A typical command would be:

           SBMJOB      JOB(PRTSBSBCH) CMD(PRTSBSBCH SBS(xxx))
                         JOBQ(QSYSNOMAX) SCDTIME(nnnnnn)

Use the SCDTIME  parameter, to estimate  when you think  there will  be
very little work being done in the subsystem.

The  previous command  would  submit  the job  to  run in  the  QSYSWRK
subsystem (by  using the QSYSNOMAX job  queue).  The job  would wake up
every  15  minutes  (by  default)  and  use  the  RTVSBSBCH  command to
determine the status  of batch  work in the  named subsystem (*ALL  may
be specified to allow all subsystems to be checked).

There  is  no command  to  end  the PRTSBSBCH  job.    Use ENDJOB  when
needed.

Each  time RTVSBSBCH is used, the same  spooled file is added onto with
the  results plus  one  line  for  each  job  that  is  active  in  the
subsystem  at   that  time  (an  option   exists  to  just   print  the
exceptions).

You  should  review  the  listing  for  the  period  of time  when  you
consider there is no  more 'actual batch work'  being performed in  the
subsystem.   Check the  listing to  see if  the number of  jobs in  the
'Wait  Status' count  is  equal to  all  batch jobs  in  the Subsystem.
(The  other way  to explain  this is  that the  number of jobs  in 'Run
Status' and 'Other Status'  must be zero).   If there are some  jobs in
a 'Run' or  'Other' status, review the listing  to determine those jobs
that are causing the difference (exceptions are flagged).

You  may need to define  your own status values  (see the discussion of
the SBSBCHSTS data area).

SBSBCHSTS data area
-------------------

You can  define a data  area and  place your  own status  values to  be
compared for  rather than  using the defaults.   The  RTVSBSBCH command
uses  the  library list  to  search for  a  data area  by  the  name of
SBSBCHSTS.   If it  cannot be  found, the  defaults  status values  are
used.

If the data  area exists, the values  in the data area are  used rather
than the default  values.  The data area must  have been created by the
CRTCONARR command as:

             CRTCONARR   DTAARA(xxx/SBSBCHSTS)
                           TEXT('Used by RTVSBSBCH TAA tool')
                           ENTLEN(4) ENTTXT('Status value')
                           ENTOBJ(*OBJ1)

You may enter up to 45 status values using the command:

             EDTCONARR   DTAARA(xxx/SBSBCHSTS)

The  status values entered must be the  same as appear in the PRTSBSBCH
listing (these are also the same as used by WRKACTJOB).

RTVSBSBCH escape messages you can monitor for
---------------------------------------------

      TAA9894    The subsystem is not active.

Escape messages from based on functions will be re-sent.

PRTSBSBCH escape messages you can monitor for
---------------------------------------------

      TAA9894    The subsystem is not active.

Escape messages from based on functions will be re-sent.

RTVSBSBCH command parameters                          *CMD
----------------------------

   SBS           The   name  of   the   subsystem   to   retrieve   the
                 information from.  The subsystem must be active.

   TOTJOBS       The  total number  of  jobs active  in the  subsystem.
                 This  is an  optional return  value that if  used must
                 be specified as *DEC LEN(5 0).

   BCHJOBS       The  total  number  of   batch  jobs  active  in   the
                 subsystem.    This  is  a sum  of  the  return  values
                 RUNSTS,  WATSTS, and OTHSTS.   Batch  jobs are defined
                 to be those  shown on  WRKACTJOB with a  type of  BCH,
                 ASJ, EVK, and  PJ.  This  is an optional  return value
                 that if used must be specified as *DEC LEN(5 0).

   RUNSTS        The total  number of batch  jobs in a  'RUN' status in
                 the  subsystem.    'RUN' means  actual  work  is being
                 performed (CPU  cycles are being  used) as opposed  to
                 a job  that is  waiting.  This  is an  optional return
                 value  that if  used must  be specified as  *DEC LEN(5
                 0).

   WATSTS        The total  number of  batch jobs  that  have a  status
                 value  that  matches  the   supplied  list  of  status
                 values.    The default  values are  DEQW,  DLYW, EOFW,
                 EVTW, MSGW, and  PSRW.   The default  values are  used
                 if the  SBSBCHSTS  data area  cannot be  found on  the
                 library list.

                 You  can   define  your  own  list   by  creating  the
                 SBSBCHSTS  data area using  the CRTCONARR TAA command.
                 See the previous discussion.

                 This is  an optional return  value that  if used  must
                 be specified as *DEC LEN(5 0).

   OTHSTS        The total  number of batch  jobs that are  not counted
                 in  the RUNSTS  or WATSTS return  values.   This is an
                 optional return value that  if used must be  specified
                 as *DEC LEN(5 0).

PRTSBSBCH command parameters                          *CMD
----------------------------

   SBS           The name  of the  subsystem to  print the  information
                 for  or  *ALL  for  all  subsystems.   If  a  specific
                 subsystem is named it must be active.

   WAIT          The number of  seconds the function  will wait  before
                 waking  up  and using  the  RTVSBSBCH  command  again.
                 The default  is 900 seconds  (15 minutes).   The value
                 (number  of  seconds)  must be  in  a range  of  10 to
                 86400 (24 hours).

   STATUS        Whether  to  print all  of  the  jobs  that  meet  the
                 status  conditions or  just  those that  do not  match
                 the  list  of  status values  (the  exceptions).   The
                 default is *ALL to print all of the jobs.

                 *UNMATCHED may be specified  to print only those  jobs
                 that  have  a  status  that is  not  included  in  the
                 status list.

                 The  default  status  values  are  DEQW,  DLYW,  EOFW,
                 EVTW, MSGW, and  PSRW.   The default  values are  used
                 if the  SBSBCHSTS  data area  cannot be  found on  the
                 library list.

                 You  can   define  your  own  list   by  creating  the
                 SBSBCHSTS  data area using  the CRTCONARR TAA command.
                 See the previous discussion.

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

None.

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

The following TAA Tools must be on your system:

     CONARR          Constant array
     CVTWRKACT       Convert work active
     RTVACTSBS       Retrieve active subsystem
     RTVSBSD         Retrieve subsystem description
     RTVSYSVAL3      Retrieve system value 3
     SNDESCMSG       Send escape message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   RTVSBSBCH     *CMD                   TAAJOCZ       QATTCMD
   PRTSBSBCH     *CMD                   TAAJOCZ2      QATTCMD
   TAAJOCZC      *PGM       CLP         TAAJOCZC      QATTCL
   TAAJOCZC2     *PGM       CLP         TAAJOCZC2     QATTCL
   TAAJOCZR2     *PGM       RPG         TAAJOCZR2     QATTRPG

Structure
---------

RTVSBSBCH   Cmd
   TAAJOCZC   CL pgm

PRTSBSBCH   Cmd
   TAAJOCZC2   CL pgm
     TAAJOCZR2   RPG Pgm
					

Added to TAA Productivity tools December 15, 2000


Home Page Up to Top