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
|
