End-of-Job Rules

Contents
coema130
Contents
An end-of-job (EOJ) rule is triggered when any job or started task ends. EOJ rules facilitate the process of detecting when a job or started task ends, because one EOJ rule usually replaces several MSG rules that must be coded to detect job ending states such as abend and normal termination messages. In addition, some address spaces may end silently (no message notification). An EOJ rule can effectively detect this type of termination.
Often, you can use an EOJ and or an EOS rule to perform the same functionality of any code that your enterprise may have added to the default IEFACTRT SMF exit, which is written in assembler language.
Installation Requirements for EOJ Rules
Set the parameters INITSMF, EOJRULES, and EOSRULES to YES.
The installation IEFACTRT SMF exits must be implemented and SMF type 30 subtype records must be generated.
For more information, see the.
)EOJ -- Event Specifier of EOJ Rules
The following is the format for coding the EOJ-event definition section:
)EOJ jobnamespec
  • jobnamespec
    Specifies the job name. Follow these guidelines when specifying the character string:
    • Specify one to eight characters of the job name.
    • The string cannot contain embedded blank spaces.
    • You can use the wildcard (*) character. For example,
      • CICS* matches CICSA, CICSABC, CICS123, and any other job name containing a CICS prefix.
      • CICS*05 matches CICSD05, CICS205, CICS1105, and so on.
      • *05 matches any job name ending with 05.
      • * alone matches all job names.
    • Lowercase letters are acceptable, but the AOF converts them to uppercase for event testing.
Initialization, Processing, and Termination Sections of EOJ Rules
The general guidelines for coding the initialization, processing, and termination sections and the various AOF tools that you can use, apply to EOJ rules.
RETURN Statements in the )PROC Section of an EOJ Rule
The OPS/REXX RETURN statement has no special meaning in the processing section of an EOJ rule. The return value has no effect on AOF processing.
Execution Considerations for EOJ Rules
The processing section of a rule that responds to an EOJ event executes in the address space of the job or task that is ending. Therefore, schedule an OPS/REXX program to a
CA OPS/MVS
OSF TSO, TSL, or TSP serve to perform any type of logic that could possibly suspend the processing of an EOJ rule.
The active JSCB in the ending address space is the region control task, or the initiator. This causes the ACCOUNT, EXECPGM, and MODULE operands of OPSINFO to return the values for the RCT or initiator program, rather than the application program that is ending.
Since SMF may generate more than one type 30 record for reach EOJ event, only the first record containing all the job data that only occurs once is used to generate the EOJ event. The additional records containing repeatable sections such as EXCP counts for every data set are not visible to the EOJ rules.
OPS/REXX Host Environments in the )PROC Section of an EOJ Rule
The )PROC section of an EOJ rule has the following host environments with the following EOJ rule characteristics. Specify the AOFDEFAULTADDRESS parameter for the default host environment for EOJ rules.
  • ADDRESS AOF
    Sent to
    CA OPS/MVS
    . Does not wait. Output is not returned.
  • ADDRESS AP
    Sent to MSF and then forwarded to the CA Automation Point system. Does not wait. Output is not returned.
  • ADDRESS EPI
    Not supported. Schedule an OPS/REXX program in a server to perform this functionality.
  • ADDRESS HWS
    Not supported. Schedule an OPS/REXX program in a server to perform this functionality.
  • ADDRESS ISPEXEC
    Not supported. Schedule an OPS/REXX program in a server to perform this functionality.
  • ADDRESS LXCON
    The VM and Linux command requests sent to USS server for execution. Does not wait. Output is not returned. The List request runs inline and returns VM and Linux system data in stem variables.
  • ADDRESS MESSAGE
    Sent as a WTO. The AOFDEST parameter specifies the destination.
  • ADDRESS MQ
    Not supported. Schedule an OPS/REXX program in a server to perform this functionality.
  • ADDRESS NETMAN
    Sent to a
    CA OPS/MVS
    internal CA Netman request queue to issue MGPT commands. Does not wait. Output is not returned.
  • ADDRESS NETMASTR
    Sent to CA NetMaster NM for SNA on the local system. Does not wait. Output is not returned.
  • ADDRESS OPSCTL
    Sent to a specified facility. If the facility is ECF or OSF, does not wait. If the facility is MSF, slight wait occurs. The external data queue returns the output.
    If the command is MSF LIST, no wait occurs.
  • ADDRESS OPSDYNAM
    Not supported. Schedule an OPS/REXX program in a server to perform this functionality.
  • ADDRESS OSF
    Schedule TSO commands, CLISTs, or REXX EXECs to
    CA OPS/MVS
    OSF TSO servers.
  • ADDRESS OSFTSL
    Schedule TSO commands, CLISTs, or REXX EXECs to
    CA OPS/MVS
    OSF TSL servers.
  • ADDRESS OSFTSP
    Schedule TSO commands, CLISTs, or REXX EXECs to
    CA OPS/MVS
    OSF TSP servers.
  • ADDRESS SOF
    Not supported. Schedule an OPS/REXX program in a server to perform this functionality.
  • ADDRESS SQL
    Does not wait. Proceed synchronously for requests that can be satisfied on the local system. Output is returned in stem variable. Error messages, if any, are returned to an external data queue.
  • ADDRESS SYSVIEWE
    Not supported. Schedule an OPS/REXX program in a server to perform this functionality.
  • ADDRESS TSO
    Sent to an OSF TSO server. Does not wait. Output is not returned.
  • ADDRESS USS
    Sent to a USS server. Does not wait. Output is not returned. Schedule an OPS/REXX program in a server if the command output interrogation is needed.
  • ADDRESS WTO
    Does not wait. Output is sent to the specified console. When attempting a WTOR, the host command is sent to a TSO server for execution. The response is returned to the server. Schedule an OPS/REXX program in a server if the WTOR response interrogation is needed.
AOF Variables Available in an EOJ Rule
You can use all AOF variable types in EOJ rules. You can use the following unique AOF event variables in the )PROC section of a EOJ rule, and you can manually interrogate the corresponding OPSLOG display field as an aid in debugging or implementing rule logic.
  • EOJ.ACCOUNT
    The value of the job card accounting field. This field is a character string where each accounting field is separated by a comma.
    Data Type:
    Character, read-only
    Sample Value:
    12 (Reason code 12)
  • EOJ.COLOR
    The color that the message text has in OPSLOG Browse
    Data Type:
    1-byte binary (unprintable), read/write
    Sample Value:
    '00'X
    Note:
    Use the OPSCOLOR function of OPS/REXX to set the EOJ.COLOR variable.
    OPSLOG Browse Column:
    COLOR
  • EOJ.CONDCODE
    The condition code of the last step of the job that was executed. The format is the same as EOJ.MAXCC and is often the same value. The value for this field is derived from SMF30SCC in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    0008 (Condition code 8)
  • EOJ.CPUSRB
    The amount of CPU time (measured in hundredths of seconds) that was consumed by the job while running in SRB mode. This is roughly equivalent to the amount of CPU time to service I/O requests by the application. This value is field SMF30CPS in the type 30 SMF record.
    Data Type:
    Integer, read-only
    Sample Value:
    20 (.2 seconds of SRB time consumed)
  • EOJ.CPUTCB
    The amount of CPU time (measured in hundredths of seconds) that was consumed by the job while running under a z/OS TCB. This is roughly equivalent to the CPU usage of the application program. This value is field SMF30CPT in the type 30 SMF record.
    Data Type:
    Integer, read-only
    Sample Value:
    910 (9.1 seconds of CPU time consumed)
  • EOJ.EXCPCNT
    The total number of data blocks transferred from I/O channel program executions. This is a measure of the amount of I/O done by the job. This value is field SMF30TEP in the type 30 SMF record.
    Data Type:
    Integer, read-only
    Sample Value:
    400 (400 blocks transferred)
  • EOJ.JOBCLASS
    The JES job class for an initiated batch job. This value is field SMF30C18 in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    A
  • EOJ.JOBNAME
    The job name or started task that has ended. JOBNAME is taken from the identification section of the SMF type 30 record.
    Data Type:
    Character, read-only
    Sample Value:
    IBMUSER
    OPSLOG Browse Column:
    JOBNAME
  • EOJ.MAXCC
    The maximum condition code of any step executed during the job. This value is always five characters.
    The condition code has the following formats:
    • S0XXX-System hexadecimal abend code
    • unnnn-User decimal abend code
    • nnnnn-Normal decimal return code
    • FLUSH-All steps of the job were flushed
    System abends are considered the highest values, followed by user abends and normal return codes. FLUSH is only returned if all steps of the job are not executed.
    Data Type:
    Character, read-only
    Sample Value:
    S00C7 (system abend 0C7)
    EOSRULES needs to be set to YES for the EOJ.MAXCC to work properly. The end-of-step cc is tracked to place the proper data in this variable.
  • EOJ.NONSPTAPE
    The number of non-specific tape mounts for the job. This value is field SMF30PTM in the type 30 SMF record.
    Data Type:
    Integer, read-only
    Sample Value:
    2
  • EOJ.PGMRNAME
    The programmer name field from the JOB statement. This value is field SMF30USR in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    JOHN DOE
  • EOJ.REASCODE
    If an abend occurs in the last executed step of the job, the reason code passed in register 15 is sometimes a reason code for the abend. The value for this field is derived from SMF30ARC in the type 30 SMF record.
    Data Type:
    Integer, read-only
    Sample Value:
    12 (Reason code 12)
  • EOJ.RESGROUP
    The WLM resource group name for the job if the system is using the z/OS Workload Manager for system management. This value is field SMF30GRN in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    ALLCICS
  • EOJ.SECGROUP
    The security group ID taken from the ACEE. This value is field SMF30GRP in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    OPERS
  • EOJ.SECUSER
    The security user ID taken from the ACEE. This value is field SMF30RUD in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    OPER1
  • EOJ.SERVCLAS
    The WLM service class for the job if the system is using the z/OS Workload Manager for system management. This value is field SMF30SCN in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    SPEEDY
  • EOJ.SMF30AD
    The address of the SMF type 30 record. This address may be used with the OPSTORE function of OPS/REXX to access any field in the type 30 record to obtain data that is not provided by the EOJ event variables. The IBM macro IFASMFR (30) generates the assembler DSECT for the SMF type 30 record.
    Data Type:
    4-byte binary (unprintable), read-only
    Sample Value:
    '00702C00'X
  • EOJ.SPTAPE
    The number of volume specific tape mounts for the job. This value is field SMF30TPR in the type 30 SMF record.
    Data Type:
    Integer, read-only
    Sample Value:
    6
  • EOJ.STARTDATE
    The sample value date that the system began execution of this job or started task. The date is in the format YYYY/MM/DD.
    Data Type:
    Character, read-only
    Sample Value:
    2000/05/12
  • EOJ.STARTTIME
    The time that the system began execution of this job or started task. The time value is in hundredths of seconds since midnight.
    Data Type:
    Character, read-only
    Sample Value:
    3600000 (10AM)
  • EOJ.SUBSYS
    The subsystem name of the job used by SMF for workload accounting. Subsystem names are defined in the SMFPRMxx member of PARMLIB and extracted from the OUCBSUBN field of the OUCB control block.
    Data Type:
    Character, read-only
    Sample Value:
    TSO
  • EOJ.TERMNAME
    The symbolic name of the TSO terminal for a TSO session. This value is field SMF30TSN in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    OPSS1
    OPSLOG Browse Column:
    TERMNAME
  • EOJ.TEXT
    The OPSLOG message text that describes the end of a job event including the maximum condition code
    Data Type:
    Character, read-only
    Sample Value:
    IBMUSER JOB00123 ENDED MAXCC=00000 SUBSYS=TSO
    OPSLOG Browse Column:
    Text is always displayed
  • EOJ.USER
    An 8-byte variable providing communication between rules executing for the same EOJ event. The variable can contain any installation data that these rules need, and it can store a character string displayable through OPSLOG Browse.
    Data Type:
    User-defined, read/write
    Notes:
    Before AOF processing, this variable is initialized to binary zeros. It is then passed to each rule that executes for the same EOJ event; each rule can look at or change the variable contents before passing the variable to the next rule for the EOJ event.
    The primary purpose for the USER variable is to provide a method to pass a small amount of data between the rules. This data may be binary or mixed case. The USER field may also be used for filtering in the OPSLOG. However, USER data used for OPSLOG filtering must be uppercase and displayable.
    OPSLOG Browse Column:
    USER
  • EOJ.USERCOM
    The value contained in the JMRUCOM of the JMR control block. This field is sometimes used to point to tables or control blocks used by installation SMF exits.
    Data Type:
    4-byte binary (unprintable), read-only
    Sample Value:
    '0A002CFC' X
    Use the OPSTORE function of OPS/REXX to access any storage pointed to by EOJ.USERCOM.
  • EOJ.WORKLOAD
    The WLM workload name of the job if the system is using the z/OS Workload Manager for system management. This value is field SMF30WLM in the type 30 SMF record.
    Data Type:
    Character, read-only
    Sample Value:
    PRODCICS
Debug an EOJ Rule
The following are EOJ Rule Debugging Techniques:
  • Set the
    CA OPS/MVS
    BROWSEEOJ parameter to YES and the EOJ event profile of your OPSLOG display to Y to view all EOJ events. With these parameters set, display the OPSLOG EVENT column to see recorded EOJ events.
  • If OPSLOG is not recording EOJ events, see Installation Requirements for EOJ Rules.
For additional debugging techniques that you can use with all AOF rules, see Coding Guidelines.
Example EOJ Rule
Assume that you defined an RDF table containing information on the production payroll jobs. When each batch job in the processing sequence ends, the start and stop times and the maximum condition codes must be recorded.
)EOJ PAY* )PROC /* Only process productions jobs a by checking EOJ event variable */ if eoj.jobclass = 'P' then /* Update RDF table with the EOJ data. Call the internal CONVTIME */ /* subroutine to format the start time to HH:MM:SS. This value */ /* is originally in hundredths of seconds since midnight. */ address SQL Update PAYTAB Set "Start_date='"eoj.startdate" ',", "Start_time='"Convtime(eoj.starttime)"' ,", /* convert data */ "End_date='"Date('B')"',", "End_time='"Time('N')"',", "Cond_code='"eoj.maxcc"'", "Where Jobname='"eoj.jobname" ' " return "NORMAL" /* Convert binary time from hundredths of seconds since midnight */ CONVTIME: cvtime=Arg(1)%100 return Right(cvtime%3600,2,'0')':'||, /* HH: */ Right((cvtime%60)//60,2,'0')':'||, /* MM: */ Right(cvtime//60,2,'0') /* SS */ )END