Support for ON DSNEVENT and ON STEP

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, Control-O intercepts the messages written by JES2 or JES3 to JESYSMSG. JESYSMSG is the third SYSOUT of the job.

Note: Control-O must be active before any tasks tracked by ON DSNEVENT or ON STEP rules begin; moreover, ON DSNEVENT and ON STEP rules only intercept data set events for jobs, started tasks, or TSO users that started after the rule was ordered.

The DSNEVENT process consists of the following parts:

1. When a job, or STC, or TSO user session starts, the system issues either the IEF403I message or the IEF125I message. Control-O 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, Control-O creates the DSNEVENT environment in the address space.

   Note: A job can only be handled by one Control-O. Therefore, in an environment where more than one Control-O can be active, for example, TEST and production, you must be accurate in defining the ON DSNEVENT. 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.

2. Control-O intercepts allocation, deallocation, and step termination messages, and determines whether there is at least one ON DSNEVENT or ON STEP event. If so, Control-O 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.

3. Control-O triggers the rule according to the following principles:
   1. 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
   2. 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.

   3. 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 Control-O 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 strongly recommends that you do not use this type of DSNEVENT because of the following:

• The overhead that results from Control-O analyzing every message written to the JESYSMSG for every job, STC, or TSO user session in the whole system.
• The Control-O limitation that only one Control-O can handle a DSNEVENT for a job. In an environment where more than one Control-O is active on the same system, this definition may cause the wrong Control-O to trap the event.