Listening for Events

During the course of JES operations, data sets and jobs are subject to changes for various reasons. When such events occur for a client data set (for example, a data set that was allocated with the DALRTCTK text unit) or a job containing at least one client data set, JES issues an Event Notification (ENF) signal. The ENF number of the signal is 58. The signal is issued only for data sets that have been allocated using the DALRTCTK text unit.

To listen for this signal, you could do something like the following:

ENFREQ ACTION=LISTEN,CODE=58,EXIT=exit_address,XSYS=YES,
     PARM=parameter_address,DTOKEN=end_token_address

Note: The XSYS=YES parameter is used because JES could be issuing signals on a different processor from the one where your server runs.

To stop listening for this signal, you could do something like the following:

ENFREQ ACTION=DELETE,CODE=58,DTOKEN=end_token_address

The data area received by your listen exit from ENF is mapped by the IAZENF58 macro. You must include this macro in your program in order to use the data supplied by the ENF signal. This data area contains the following information:

ENF58_LENGTH

Length of parameter list

ENF58_QUALIFIER

Qualifier code — defined below:

ENF58_Q_PURGE: Data set was purged
ENF58_Q_SELECT: Data set was selected
ENF58_Q_DESELECT_PROCESSED: Data set was processed
ENF58_Q_DESELECT_NOT_PROCESSED: Data set is no longer selected, disposition was not changed
ENF58_Q_DESELECT_NOT_PROCESSED_HELD: Data set is no longer selected, disposition was not changed and data set is held
ENF58_Q_DESELECT_ERROR: An error resulting in a system level hold occurred
ENF58_Q_EOD_OK: End of data set notification occurred — successful
ENF58_Q_EOD_ERROR: End of data set notification occurred — unsuccessful
ENF58_Q_JOB_CHANGE: Job-status change occurred
ENF58_Q_TOKEN_CHANGE: Client token has changed
ENF58_Q_CHECKPOINT: A checkpoint has occurred on the printer on which the data set is printing.

ENF58_SYS_HOLD

System hold reason — refer to IAZOHLD for possible values

ENF58_JES_NAME

JES2 Member Name / JES3 MAIN name

ENF58_REASON

Reason text

ENF58_CTOKEN

Data Set Client Token

ENF58_NEW_CTOKEN

New client token that should replace the CTOKEN for a TOKEN_CHANGE ENF type

You should determine what action you need to take based on this event. For example, if you receive a signal with ENF58_Q_PURGE it usually means that you should delete from your list all information pertaining to the dataset with the CTOKEN of ENF58_CTOKEN.

To take action on the CTOKEN, you must first go through your CTOKEN list and issue IAZXCTKN macros, comparing ENF58_CTOKEN to CTOKENs from your list until you find the CTOKEN specified in the signal in your list. If ENF58_QUALIFIER is ENF58_Q_JOB_CHANGE, it means that ENF58_CTOKEN is a job level CTOKEN and you must go through your entire list of CTOKENs until you have identified, and taken action on, all data set level tokens covered by the job level CTOKEN.

Note:

When ENF58_QUALIFIER is ENF58_Q_JOB_CHANGE, the CTOKEN in ENF58_CTOKEN is a job level CTOKEN. At all other times it is a data set level CTOKEN.
When ENF58_QUALIFIER is ENF58_Q_TOKEN_CHANGE, the ENF58 parameter list contains a new CTOKEN and ENF58_LENGTH reflects the existence of this new CTOKEN.
When an event with ENF58_Q_TOKEN_CHANGE is received, the CTOKEN in your list should be replaced with the contents of ENF58_NEW_CTOKEN. This is the only time that you should change the contents of a CTOKEN. Replacing this CTOKEN does not change the ordering of the CTOKEN you previously had in your list for this data set.
ENF58_NEW_CTOKEN is present only when ENF58 QUALIFIER is ENF58_Q_TOKEN_CHANGE. ENF58_LENGTH is larger for this qualifier type than it is for other types.
When an event with ENF58_Q_CHECKPOINT is received, the below fields are also present and contain the status of the print at the time that the checkpoint is taken.
ENF58_COPY

Checkpointed copy count

ENF58_RECORD

Checkpointed current record

ENF58_PAGE

Checkpointed current page

These fields are present only when ENF58_QUALIFIER is ENF58_Q_CHECKPOINT. ENF58_LENGTH is larger for this qualifier type than it is for other types except ENF58_NEW_CTOKEN.

If checkpoints occur frequently, ENF58 checkpoint signals may be generated at a fast rate.

If a restart of JES or the printer occurs after a checkpoint, the next checkpoint could be for a page or record count that represents reprocessed records or pages. This is because after a restart a writer will continue at the last checkpointed record or page, not the last one that completed printing.
Trace ID 43 traces ENF58 events that are sent and trace ID 44 traces ENF58 events that are received.

See z/OS MVS Programming: Authorized Assembler Services Guide and z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG for information about using the ENFREQ macro and coding the listen exit.