Event-filtering exit (User Exit 4)
The event-filtering exit is called when an HCL Workload Automation for Z event writer is about to write an event to the event data set or, where EWSEQNO is used, add the event to an XCF or NCF queue. In this exit, you can choose to discard events created by JES and SMF exits, or you can indicate that an event that would normally be queued to JCC is not processed by the JCC.
This exit is commonly used to filter the events created by non-production work. If you run a significant number of test jobs and other work, and your job naming standards let you do so, consider using EQQUX004 to filter the non-production work.
If the exit abends, it is flagged as not executable and HCL Workload Automation for Z does not try to call the exit again.
HCL Workload Automation for Z invokes the User Exit 4 in AMODE 31 and RMODE 24.
Editing the exit
exit4.h, which contains the following
routine: - void updateRetCode (int newRetCode, struct exit4struct *params)
- To update the return code of the exit.
The
paramsinput is the same as the input passed toexit4do.
The header contains also the struct exit4Struct structure, which is
provided as an input to the exit4do routine. Each string in the data
structure is expanded by 1 character to reserve space for the end-of-text character
\0, which corresponds to byte 0.
User Exit 4 parameters
struct exit4Struct{
char jobName[JOBNAME_LEN+1];
int* retCode;
struct EXRStruct *exr;
};
#define JOBNAME_LEN 8
#define EXR_LEN 80- JOBNAME
- Name of the job for which a job-tracking event has been recognized and fro which an event record is about to be written to the event data set.
- RETCODE
- Set by the exit to one of the following values:
- 0
- Normal return. The event writer continues normal processing; the event is written to the event data set. If the event is a job-termination event (type 3P) it is passed to the JCC, if the JCC is active.
- 4
- No JCC processing for this event. The event is written to the event data set but is not passed to the JCC for processing.
- 8
- This is not a scheduler event. The event is not written to the event data set and is not passed to the JCC for processing. However, if the event is a reader event (type 1) and the job was held by a scheduler job-tracking exit, the job is released from hold by the event writer.
- EXR
- Exit record describing the job-tracking event. This record is built by the SMF or
JES exit that recognized the event. If the event is created for a job, the job number
offset, EXRJOBID, contains JOB as the first three characters; if the event is created
for a started task EXRJOBID contains STC as the first three characters.The sub-structure containing the detailed exit record information is mapped as follows:
struct EXRStruct { struct { char exrsyst; // System type: A or B char exrevtyp; // Event type: 1, 2, 3, 4, 5, 6 } exrtype; // Record type char exrstype; // Event subtype (only for type 3) struct { unsigned exrretry : 1; // Retry release command unsigned exropcho : 1; // This job is in hold unsigned exroheld : 1; // Job was held by OPC unsigned exrjkill : 1; // Job killed by JES in rdr unsigned exrjccec : 1; // Error code from JCC unsigned exrjccch : 1; // Checked by JCC unsigned exrjccer : 1; // Error in JCC unsigned exrrlast : 1; // Retcode(last) active } exrflags; // Exit flags struct { unsigned exrjcset : 1; // exrjcout is valid unsigned exrjcout : 1; // Job has JCC sysout unsigned exrdiscr : 1; // Discrepancy msg unsigned exrmchld : 1; // 1= mmsgclass is held unsigned exrcmreq : 1; // 1= requeue msg class unsigned exrexts : 1; // 1= ext sub (NMM)@D90C$DMBc unsigned exrabend : 1; // 0=normal, 1=abend (step) unsigned exrflush : 1; // 0=normal, 1=flushed step } exrtermf; // Termination flags struct { unsigned exrfail : 1; // Job failed unsigned exrJQA : 1; // ON= is a JQA @21C unsigned exrZ2level : 1; // Z2 level @21C unsigned exrR4level : 1; // R4 level @21C unsigned exrsinfo : 1; // 1= step awareness @91c unsigned exrcfal : 1; // Job failed on cond codes unsigned exrjcjob : 1; // JCJOB processed ok @D54A unsigned exrlastfl : 1; // last step flushed $BGIA } exrerror; // Job error switch lcterror uint16_t exrgmtof; // GMT offset in minutes char exrjobn[8]; // Job name char exrjobid[8]; // Job number struct { uint32_t exrdate : 31; // Date format (00yydddf) uint32_t exrtime : 31; // Time format (secs*100) } exrcreat; // event creation time struct { uint32_t exrrdate : 31; // Date format (00yydddf) uint32_t exrrtime : 31; // Time format (secs*100) } exrjsrdr; // jes reader date & time uint32_t exrsdate; // Operation start date uint32_t exrstime; // Operation start time uint32_t exredate; // Operation end date uint32_t exrorgid; // nje origin job number struct { char exrclass; // Printout class char reserved; // Reserved @9OA uint16_t exrasid; // Job asid @0xx uint32_t exrexeid; // NJE execution jobn @0xx } exronje; // name of orig nje nod@9OC char exrform[8]; // form number uint16_t exrcode; // Completion/condition code struct { unsigned exrjesv4 : 1; // JES sp4 or above1/3P/5@92A unsigned exrspun : 1; // Spun off ds rcd unsigned exrterm : 1; // Oper terminated datagroup unsigned exrinter : 1; // Oper interrupted -:- unsigned exrrstrt : 1; // Oper restarted -:- unsigned exrndest : 1; // Not final f/$sysmsgs 3P unsigned exrnods4 : 1; // No $sysmsgs found 3P unsigned exrsuspd : 1; // Suspended } exrindic; // Status indicators struct { unsigned filler : 3; // Not used @52C unsigned exrSDEP : 1; // SDEP filter used @52A unsigned exrlastab : 1; // Last step abended $CAVA unsigned exrstall : 1; // Stepevents(all) @d4a unsigned exrstnz : 1; // Stepevents(no) flag @0BC unsigned exropcan : 1; // Cancelled by oper } exrpurge; // Job purge bits char exropcid[4]; // OPC identifier };