A DSNEVENT occurs when a file is deallocated, on the happening of one of the following events:
the dynamic deallocation of a file
deallocation of a file on the termination of a job STEP
deallocation of a file on the termination of a job
A STEP event occurs when a step ends.
To support the ON DSNEVENT and ON STEP parameters, CMEM intercepts the messages written by JES2 or JES3 to JESYSMSG. JESYSMSG is the third SYSOUT of the job.
The DSNEVENT process consists of the following parts:
When a job, or STC, or TSO user session starts, the system issues either the IEF403I message or the IEF125I message. CMEM intercepts this message, and checks whether there is at least one ON DSNEVENT or ON STEP rule for the job. If there is at least one rule for the job, CMEM creates the DSNEVENT environment in the address space.
Note: A job can only be handled by one CMEM. Therefore, in an environment where more than one CMEM can be active, for example, TEST and production, you must be accurate in defining the ON DSEVENT. The DSNEVENT environment for an address space remains intact when a new Control-O instance is started while the previous Control-O instance is still active.
CMEM intercepts allocation, deallocation, and step termination messages, and determines whether there is at least one ON DSEVENT or ON STEP event. If so, CMEM determines
whether the DSNEVENT or STEP events fulfil the selection criteria in the rule
whether, in the case of a DSNEVENT, the file is a new file or already exists
Note: A DSNEVENT can be triggered only on the Control-O/CMEM that runs on the same z/OS system on which the event occurs. Even a focal Control-O or CMEM in a Sysplex environment is insufficient. This is because Control-O or CMEM intercepts the messages written to JESYSMSG while they are being written, which can be done only on the same system where the event happens.
CMEM triggers the rule according to the following principles:
An ON STEP rule is always triggered when a STEP ends. However, a STEP is ignored when a rule is not executed due to one of the following:
a JCL error
failure to encounter a previous step condition code
An ON DSNEVENT can occur when a deallocation message is written, or when a step terminates. Whether it occurs depends on
how the file is deallocated
the setting of the STEPRC field in the DSNEVENT criteria, as follows:
- If the value of STEPRC is null, the rule is triggered at the time of deallocation.
- If the value of STEPRC is other than null, the rule is rechecked at the termination of the step to ascertain the STEPRC criteria.
Deallocation occurs when
the file is dynamically deallocated
the step ends, in the case of all allocated files in this step, whether the files were allocated by JCL or were dynamically allocated
the job terminates, in the case of any file that was not released on step termination, for example, if DISP is set to PASS
For CMEM actions to be triggered in this way, the following conditions must be satisfied:
Either the IEF403I message or the IEF125I message must appear in the job log.
The job, STC, or TSO user session must have its MSGLEVEL set to (x,1), to ensure that allocation, deallocation and step termination messages are written to the JESYSMSG. It is not sufficient for these messages to appear only in the system log or job log.
At least one ON DSNEVENT or ON STEP rule must be ordered and ready before the job, STC, or TSO user session starts.
Note: If the value of ON DSNEVENT is * (asterisk), every job, STC, or TSO user session is within the DSNEVENT environment. BMC recommends that you do not use this type of DSNEVENT because of
the overhead that results from CMEM analyzing every message written to the JESYSMSG
the CMEM limitation that only one CMEM can handle a DSNEVENT for a job In an environment where more than one CMEM is active on the same system, this definition may cause the wrong CMEM to trap the event.
