The Retrieve Job Completion tool retrieves the completion status for
a job. Two solutions are provided: 1) RTVJOBCMPM (Retrieve Job
Completion Message) and 2) RTVJOBCMPA (Retrieve Job Completion
Accounting). Both solution provide for a delay time and a number of
iterations to allow a program to wait for a reasonable time.
RTVJOBCMPM (Retrieve Job Completion Message)
--------------------------------------------
The SBMJOB command provides the MSGQ parameter which allows the
system to send either a normal or abnormal completion message when
the submitted job is ended. The message may be sent to any message
queue.
To use RTVJOBCMPM, you must first create a message queue that is only
used by the function where you want to run RTVJOBCMPM. The message
queue must not be shared if you have multiple requirements for
RTVJOBCMPM.
Assume you created message queue ABC in library LIBM to hold the
message sent by a submitted job.
You would then use the following type of CL code:
DCL &COMPTYPE *CHAR LEN(8)
.
CLRMSGQ MSGQ(LIBM/ABC)
SBMJOB ... MSGQ(LIBM/ABC)
.
RTVJOBCMPM MSGQ(LIBM/ABC) COMPTYPE(&COMPTYPE)
MONMSG MSGID(TAA9892) EXEC(DO) /* Not complete */
/* */
/* The job did not finish in the */
/* number of seconds and number */
/* of iterations specified. */
/* */
ENDDO /* Not complete */
IF (&COMPTYPE *EQ 'NORMAL') DO /* Normal */
/* */
/* Your code for normal completion */
/* */
ENDDO /* Normal */
IF (&COMPTYPE *EQ 'ABNORMAL') DO /* Abnormal */
/* */
/* Your code for abnormal completion */
/* */
ENDDO /* Abnormal */
The defaults for RTVJOBCMPM are DLYTIM(5) and ITERATIONS(5). This
means that the command will attempt to receive a message from the ABC
message queue and if no message exists, the command will delay 5
seconds and try again. If after 5 iterations, no message is found,
the command will abort with the TAA9892 escape message.
If RTVJOBCMPM receives a message with an ID of CPF1241, NORMAL will
be returned in the &COMPTYPE variable. If a message exists with a
message ID of CPF1240, ABNORMAL will be returned in the &COMPTYPE
variable.
If a message other than CPF1240 or CPF1241 is read, an escape message
will be issued as the message queue should be devoted to the
RTVJOBCMPM function.
Any message that is read, remains in the message queue when
RTVJOBCMPM completes.
The RTVJOBCMPM command does not have to immediately follow the
SBMJOB. You may perform other CL functions before checking whether
the batch job has completed.
RTVJOBCMPA (Retrieve Job Completion Accounting)
-----------------------------------------------
The system job accounting function will write a journal entry when a
job completes to the job accounting journal which includes the end
code as described by the CPF1164 message (00 = Normal, .., 20 =
ENDSEV exceeded) which is sent at the end of every job. The TAA tool
JOBACG provides a solution for converting the journal entries to a
data base file. You may either convert multiple job accounting
entries using CVTJOBACG (part of the JOBACG tool) or the separate
tool CVTJOBACG3 which converts each entry as it is placed in the
journal (a delay time parameter exists).
The RTVJOBCMPA command uses the RTVJOBACGR (Retrieve Job Accounting
Record) command (part of the JOBACG tool) to retrieve the job
completion information from the converted journal entry.
You must know the fully qualified job name you want to retrieve
information for to use RTVJOBCMPA. If you use SBMJOB, you can follow
the command with the RTVSBMJOB TAA command which will return the
qualified job name. The following would be typical code:
DCL &COMPCODE *CHAR LEN(2)
DCL &JOB *CHAR LEN(10)
DCL &USER *CHAR LEN(10)
DCL &JOBNBR *CHAR LEN(6)
.
SBMJOB ...
RTVSBMJOB JOB(&JOB) USER(&USER) JOBNBR(&JOBNBR)
.
RTVJOBCMPA JOB(&JOBNBR/&USER/&JOBNBR) +
COMPCODE(&COMPCODE)
MONMSG MSGID(TAA9892) EXEC(DO) /* Not complete */
/* */
/* The job did not finish in the */
/* number of seconds and number */
/* of iterations specified. */
/* */
ENDDO /* Not complete */
IF (&COMPCODE *EQ '00') DO /* Normal */
/* */
/* Your code for normal completion */
/* */
ENDDO /* Normal */
IF (&COMPTYPE *GT '00') DO /* Abnormal */
/* */
/* Your code for abnormal completion */
/* */
ENDDO /* Abnormal */
RTVJOBCMPA uses the RTVJOBACGR command to attempt to retrieve the job
accounting record. The defaults for RTVJOBCMPA are DLYTIM(5) and
ITERATIONS(5). If the job accounting record does not exist, the
command will delay 5 seconds and try again. If after 5 iterations,
no job accounting record is found, the command will abort with the
TAA9892 escape message.
Note that the RTVSBMJOB command must immediately follow SBMJOB to
access the qualified job name information.
The job that you are attempting to determine the completion code for
must not use CHGACGCDE command which causes an interim accounting
entry with a completion code of 99. If this occurs, an escape
message is issued.
RTVJOBCMPM escape messages you can monitor for
----------------------------------------------
TAA9892 The job completion message was not found
after the number of iterative attempts
Escape messages from based on functions will be re-sent.
RTVJOBCMPA escape messages you can monitor for
----------------------------------------------
TAA9892 The job accounting record was not found
after the number of iterative attempts
Escape messages from based on functions will be re-sent.
RTVJOBCMPM Command parameters *CMD
-----------------------------
MSGQ The qualified name of the message queue that is
specified on the SBMJOB command which will receive
the job completion message. A unique message queue
must be used for each use of RTVJOBCMPM.
The library value defaults to *LIBL. A specific
library or *CURLIB may also be used.
COMPTYPE The completion type returned. This is a required
return variable that must be specified as *CHAR
LEN(8). It will contain either NORMAL or ABNORMAL.
DLYTIM The number of seconds to delay before checking if
the job completion message has been sent to the
message queue. The default is 5.
When RTVJOBCMPM begins processing, it immediately
checks to see if a message exists. If not, it
delays for the number of seconds specified and then
checks again.
This process continues for the number of iterations
specified for the ITERATIONS parameter.
ITERATIONS The number of iterations to occur. The default is
5. If a message is not found after the number of
iterations has been met, the TAA9892 escape message
occurs.
RTVJOBCMPA Command parameters *CMD
-----------------------------
JOB The fully qualified name of the job to retrieve job
accounting information for. This is 3 part entry of
job, user, and job name. All parts must be entered.
If the job has completed, the accounting journal
information must have been converted to the JOBACGP
file using either CVTJOBACG or CVTJOBACG3.
COMPCODE The completion type returned. This is a required
return variable that must be specified as *CHAR
LEN(2). The entries are the same as described by
the CPF1164 message where '00' indicates a normal
completion and all others are abnormal.
DLYTIM The number of seconds to delay before checking if
the job accounting record exists. The default is 5.
When RTVJOBCMPA begins processing, it immediately
checks to see if the job accounting entry exists.
If not, it delays for the number of seconds
specified and then checks again.
This process continues for the number of iterations
specified for the ITERATIONS parameter.
ITERATIONS The number of iterations to occur. The default is
5. If the job accounting record is not found after
the number of iterations has been met, the TAA9892
escape message occurs.
JOBACGLIB The library where the JOBACGP file exists.
Restrictions
------------
RTVJOBCMPM requires that a unique message queue exist for each use of
RTVJOBCMPM.
RTVJOBCMPA requires that the job accounting journal is used and that
the JOBACG tool has been set up. The entry to be checked for must be
converted from the job accounting journal by the use of either
CVTJOBACG or CVTJOBACG3. The CHGACGCDE command may not be used in
the job to retrieve information for.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKOBJ3 Check object 3
EDTVAR Edit variable
RSNLSTMSG Resend last message
JOBACG Job accounting
SNDESCINF Send escape information
SNDESCMSG Send escape message
Implementation
--------------
RTVJOBCMPM requires that a unique message queue be created for each
use of RTVJOBCMP.
RTVJOBCMPA requires the use of the system job accounting function and
the TAA JOBACG tool,
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVJOBCMPM *CMD TAAJOGD QATTCMD
RTVJOBCMPA *CMD TAAJOGD2 QATTCMD
TAAJOGDC *PGM CLP TAAJOGDC QATTCL
TAAJOGDC2 *PGM CLP TAAJOGDC2 QATTCL
Structure
---------
RTVJOBCMPM Cmd
TAAJOGDC CL pgm
RTVJOBCMPA Cmd
TAAJOGDC2 CL pgm
|
