TAA Tools
RTVJOBCMP       RETRIEVE JOB COMPLETION                TAAJOGD

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
					

Added to TAA Productivity tools January 15, 2014


Home Page Up to Top