Control-M Event Manager (CMEM)

This chapter includes the following topics:

• Overview of CMEM

• CMEM Rule Parameters: Summary

• CMEM Parameter Descriptions

• DESCRIPTION (CMEM): General Parameter

• DO Statement (CMEM): Action Parameter

• DO COND (CMEM): Action Parameter

• DO FORCEJOB (CMEM): Action Parameter

• DO RULE (CMEM): Action Parameter

• DO SHOUT (CMEM): Action Parameter

• DO STOPJOB (CMEM): Action Parameter

• GROUP (CMEM): General Parameter

• MODE (CMEM): General Parameter

• On Spool Jobs

• On Spool Job Scheduling Definition Considerations

• ON JOBARRIV (CMEM): Event Parameter

• ON JOBEND (CMEM): Event Parameter

• ON STEP (CMEM): Event Parameter

• OWNER (CMEM): General Parameter

• RUNTSEC (CMEM): General Parameter

• THRESHOLD (CMEM): Runtime Scheduling Parameter

Overview of CMEM

The Control-M Event Manager (CMEM) facility enables Control-M to perform specified actions in response to external events. External events are events in the system that occur outside the direct control of Control-M, such as submission of a job not under the control of the Control-M monitor.   

The CMEM facility is an optional facility based on a monitor and a subsystem.

The CMEM facility utilizes sets of user-defined rules that specify events to monitor and actions to perform if a specified event occurs. These rules are defined online through the CMEM Rule Definition facility.

Multiple rules can be defined in a table (member) in a standard partitioned data set (library). Related rules are usually defined in the same table. Multiple tables can be defined in a library, and multiple CMEM rule libraries can be defined.

Types of Events Managed by CMEM

The CMEM facility handles the following events. These can be specified in ON statements in the rule:

Table 227 Events Handled by CMEM

Types of Actions that CMEM Can Perform

Any combination of the following actions can be performed when the specified event occurs. They are specified in DO statements in the rule:

• add or delete a prerequisite condition

  Prerequisite conditions can be added to or deleted from the IOA Conditions file. This may trigger the submission of jobs in the Active Jobs file. Specified in a DO COND statement in the rule.

• force a job or table

  A Control-M table or individual job can be forced (that is, ordered to the Active Jobs file regardless of its basic scheduling criteria). Specified in a DO FORCEJOB statement in the rule.

  Jobs can be forced for one of the following reasons:

  • to start a new process in Control-M (that is, new job submission)

  • to enable Control-M to assume full control of an externally submitted job that triggers the event; these jobs are referred to as On Spool jobs, discussed under On Spool Jobs.

• stop the job in which the event occurs

  At the end of the current job step, terminate the job in which the event occurred. Specified in a DO STOPJOB statement in the rule.

The following actions can be defined if Control-O is active:

• invoke a Control-O rule

  Control-O rules can be invoked within the current rule. Specified in a DO RULE statement in the rule.

• send a message

  Messages can be sent to specified locations through the Control-O Shout facility. Specified in a DO SHOUT statement in the rule.

CMEM Rule Ordering, Triggering and Deactivation

CMEM tables, along with their rules, are usually ordered (loaded to memory) when CMEM is started. They can also be refreshed or loaded by an operator command, or manually using the FORCE option in the CMEM Table List screen.

Once a CMEM rule has been loaded in memory, the occurrence of the events specified in its ON statements trigger the rule. All DO statements in the rule are then performed.

More than one rule can be triggered by the occurrence of an event. An event triggers each rule whose ON statement matches the event.

Generally, all actions from all triggered rules are performed.

The one exception occurs when multiple rules are triggered by the same job arrival event and each of the triggered rules contains DO FORCEJOB statements. In this case, the DO FORCEJOB statements of the first triggered rule are performed, but the DO FORCEJOB statements of the other rules triggered by the event are not performed. For more information, see On Spool Jobs.

CMEM rules remain activated, that is, they remain in memory, until they are overridden by the reloading of the rule table or deleted by an operator command.

CMEM AutoEdit Variables

The CMEM facility supports its own set of AutoEdit variables. No other AutoEdit variables can be used by the CMEM facility. Furthermore, in Control-M, these variables can only be specified in CMEM rules, not in job scheduling definitions or JCL.

CMEM AutoEdit variables are resolved upon triggering of the rule. Available CMEM AutoEdit variables are:

Table 228 CMEM AutoEdit Variables

On Spool Jobs

On Spool jobs are jobs or started tasks that are submitted externally to Control-M, such as jobs submitted by TSO users or CICS, or jobs received over the NJE network, but are brought under the control of the Control-M monitor using a CMEM rule.

The CMEM rule that causes a job to be an On Spool job, that is, a CMEM rule that brings the external job under the control of the Control-M monitor, must be an ON JOBARRIV rule or Control-O event (ON DSNEVENT or ON STEP) with a DO FORCEJOB statement. To inform Control-M that this is an On Spool job and not a regular FORCEJOB request, the job scheduling definition forced by the DO FORCEJOB must "match" the arriving job, as described below.

Control-M controls the entire life cycle of the job, from determining when to execute the job to performing job post-processing, according to the forced job scheduling definition.

Control-M processes On Spool jobs slightly differently than it processes regular jobs. Control-M does not submit the job because the job has already been submitted. Instead, Control-M releases the job (if held) when the runtime scheduling criteria are met.

Once the job starts execution, whether the job previously required releasing or not, it is controlled by Control-M in the same way that Control-M controls regular jobs. Control-M waits for the job to finish, reads its sysout, and performs all post-processing actions defined in the job scheduling definition.

Creating On Spool Jobs

The following components are necessary to create On Spool jobs:

1. job on spool

2. CMEM rule

3. job scheduling definition

Below is a detailed explanation of what must be defined for each of the above components to create an On Spool job.

Job On Spool

The job must have the following characteristics:

• The job must be submitted with TYPRUN=HOLD to delay its execution and permit Control-M to determine when to run the job.

  For users who have the Thruput Manager product installed, a conflict might occur between it and the Control-M On Spool processing.

  Thruput Manager intercepts JES JCL Interpretation processing, and temporarily changes the job's status.   If the Control-M Submittor task requests the job's status while it is being processed by Thruput Manager, it receives a response indicating that the Job is not HELD. As a result, the job is set to status WAIT EXECUTION, and Control-M does not try to release it. In this event, you may see messages from Thruput Manager (for example, DTM1459I) and from the Control-M Submittor (for example, SUB13AI) with the same time-stamp. This indicates that both tasks were processing the job at the same time.

  BMC recommends that the vendor of the Thruput Manager product be contacted to determine if a fix for this problem (to not change the job’s status) has been issued.

  In any case, the JOB card of the On Spool Job must be coded with TYPRUN=JCLHOLD, rather than TYPRUN=HOLD, to cause both Thuput Manager and the JCL Interpreter to process the job only after it has been released by Control-M.

• The MSGCLASS sysout of the job:

  • for JES3 users: must be equal to the Control-M SYSOUT held class

  • for JES2 users: can be any held SYSOUT class

This enables Control-M to read the job sysout and perform post-processing according to the job scheduling definition.

CMEM Rule

The CMEM rule definition must contain the following:

• ON JOBARRIV or Control-O Event (ON DSNEVENT or ON STEP) statement

  The job name specified in the ON JOBARRIV/ON DSNEVENT/ON STEP statement in this rule must match the name of the job to be monitored. It can be a full job name, or it can be a mask if a group of jobs is to be monitored. For more information, see ON JOBARRIV (CMEM): Event Parameter, On Spool Job Scheduling Definition Considerations, or ON STEP (CMEM): Event Parameter.

  Control-O users are advised that message rules triggered by $HASP395 (under JES2) or IEF404I (under JES3) are treated the same as JOBEND rules.

• DO FORCEJOB statement

  The first DO FORCEJOB statement in the rule must force a matching job scheduling definition, described immediately below. For more information, see DO FORCEJOB (CMEM): Action Parameter.

  When monitoring for a group of jobs via job name masking, the JOB parameter in the DO FORCEJOB statement must specify the CMEM AutoEdit variable %%$JNAME. This allows the Control-M monitor to use the job name mask when performing the job name match process in the table. Using this method allows a single CMEM rule to act together with a single job scheduling definition (whose MEMNAME specifies the same job name mask) for jobs that require similar tracking requirements.

Job Scheduling Definition

The job scheduling definition must have the following characteristics:

• The job scheduling definition must be forced by the first DO FORCEJOB statement in the CMEM rule.

• The MEMNAME value in the job scheduling definition must match the name of the external job. A mask can be specified in the MEMNAME field if the same job scheduling definition is used for more than one job.

• Appropriate runtime scheduling criteria for the job must be defined in the job scheduling definition. This enables Control-M to control the execution of the job, that is, when the job must be run.

• Desired post-processing actions must be defined in the job scheduling definition.

Handling On Spool Jobs

On Spool jobs are handled as follows:

• When the job arrival event occurs, Control-M forces the requested table or job.

  If the MEMNAME value in the requested table or job does not match the name of the arriving job, the table or job is forced and processed regularly by Control-M (a job is submitted when its runtime scheduling criteria are met, and so on).

  If the MEMNAME value in the requested table or job matches the name of the arriving job, the job becomes an On Spool job and Control-M performs the following actions:

  • replaces the MEMNAME mask (if a mask was specified in MEMNAME) with the name of the arriving job

  • assigns the job ID of the job that triggered the event to the forced job

  • forces the job; for details and exceptions see On Spool Job Scheduling Definition Considerations

  The forced job appears in the Active Environment screen with status WAIT SCHEDULE ON SPOOL.

• Control-M starts processing the forced job when all runtime scheduling criteria defined in the job scheduling definition are satisfied. If there are no runtime scheduling criteria in the job scheduling definition, Control-M starts processing the job immediately.

• Control-M looks for the job in the spool, to release it, if required.

  • If the external job is waiting for execution in HELD state, that is, if the job arrives on spool with TYPRUN=HOLD, Control-M releases it for execution.

  • Otherwise, Control-M verifies that the job is still in the spool (waiting for execution, executing or ended) before deciding to perform post-processing.

• Control-M waits for the job to finish execution, reads its SYSOUT, analyzes the execution results and performs all the post-processing actions defined in the job scheduling definition.

On Spool Job Scheduling Definition Considerations

Job Forcing Considerations

Only one On Spool job can be created in response to a job arrival event. However, in several cases, multiple DO FORCEJOB actions might match the arriving job. Each of these cases and the job forcing logic applied to them, to prevent multiple On Spool processes for the same external job, are described below.

• The job arrival rule contains multiple DO FORCEJOB requests. Each might match the arriving job. In this case, job forcing logic is as follows.

  The On Spool process, the match between the external job name and MEMNAME, is performed for the first DO FORCEJOB in the first matching job arrival rule only:

  • If a match is found, the job is an On Spool job.

  • If a match is not found, the job is not an On Spool job, even if subsequent DO FORCEJOB actions might match.

  In either case, all subsequent DO FORCEJOB statements in the same rule (if they exist) are handled normally, that is, not as forcing On Spool jobs.

• The DO FORCEJOB forces a table in which more than one MEMNAME matches the arriving job. In this case, job forcing logic is as follows.

  If a table containing more than one job is forced, by the first DO FORCEJOB statement in the rule, as described above, the first matching job causes the job to be an On Spool job. All the other jobs in the table are forced as regular Control-M jobs, even if they match the job name of the external job.

• Multiple job arrival rules are triggered by the same job arrival event, and each rule contains one or more DO FORCEJOB statements that might match the arriving job. In this case, job forcing logic is as follows.

  Only the DO FORCEJOB statements from the first triggered rule are executed, as described above. DO FORCEJOB from all other triggered job arrival rules are ignored.

JCL Management Considerations

When defining JCL, the following issues must be considered:

• Any attempt to rerun the job, that is, as a cyclic job, by a DO RERUN statement, or by a manual rerun request, might fail if the JCL of the job is not found in the library specified in the MEMLIB parameter of the job scheduling definition.

• If the job is not submitted with TYPRUN=HOLD, Control-M cannot determine when the job runs, even if runtime scheduling criteria are defined. In this case, the job might start executing before all the runtime scheduling criteria are satisfied. Post-processing, however, is not performed by Control-M until the runtime scheduling criteria are satisfied.

• Since On Spool jobs are not submitted by Control-M:

  • The JCL of the On Spool job cannot contain AutoEdit statements, and SETVAR statements in the job definition are ignored. This is because the job is not submitted by Control-M.

  • Because the job is not submitted by Control-M, the following job scheduling definition parameters are ignored:

    • SCHENV

    • SYSTEM ID

    • NJE NODE

  • NJE enhanced tracking support is inoperative

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, 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:

1. 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.

   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.

2. 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

     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. CMEM 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 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.

  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 CMEM analyzing every message written to the JESYSMSG for every job, STC, or TSO user session in the whole system.

  • 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.

Regular Allocation and Deallocation

In the case of regular files, meaning files not managed by SMS, CMEM traps the following deallocation messages:

• IEF283I

• IEF285I

• IEF287I

SMS Support

In the case of SMS-managed data sets, CMEM traps the IGD101I and IGD104I allocation and deallocation messages, and determines whether the file is new according to the following rules:

• If both messages are issued, the file is new.

• If the IGD101I message is not found, CMEM treats the file as not new.

Generation Data Sets (GDG)

For CMEM to support Generation Data Sets (GDG), the following messages must be found:

• IGD105I

• IGD107I

• IGD108I

• IGD17101

CMEM Support for FTP

CMEM actions can be triggered by the transfer of files by FTP products.

In order to enable CMEM rules to be triggered by such file transfers, do the following:

1. Use one of the following methods to insert the expression MSGLEVEL=(1,1) in the STC of the FTP product:

   • Customize the JESxPARM member in the SYS1.PARMLIB library.

   • Modify the job statement in the PROCLIB library member that contains the procedure JCL for the STC of the FTP product.

2. Start the CMEM monitor with at least one DSNEVENT rule that refers to the STC of the FTP product. You can use a dummy DSNEVENT rule that forces CMEM to monitor the STC of the FTP product.

3. Start the FTP product.

4. Modify existing rules, or order new rules (or do both). Rules that have been modified or ordered before a file reaches the FTP server are applied to all files subsequently transferred by the FTP product.

CMEM triggers rules when the requirements of an ON DSNEVENT statement are satisfied. If an FTP product fails to transmit a data set and issues a message relating to this failure, CMEM cannot react to that message. However, you can use CMEM rules to react to FTP product messages.

CMEM Support for IBM FTP

The IBM FTP process is executed under the OMVS address space, which is BPXAS. BPXAS address spaces do not usually write messages to the JESYSMSG.

In order to enable CMEM DSNEVENT support for IBM FTP, the following occurs:

1. When the CMEM monitor starts, it activates the OpenEdition interface for processes in the BPXAS. Having done this, CMEM issues the following messages:

   Copy

   CTO782I SUBSYSTEM REGISTERED WITH OPENEDITION INTERFACE
   CTO783I INITIALIZATION OF OPENEDITION ENVIRONMENT ENDED SUCCESSFULLY

   When CMEM initialization is complete, message CTO147I is displayed. After this, CMEM gets control every time that an OpenEdition process starts in the BPXAS address space.

2. When a new process starts in the BPXAS, the interface routine issues the CTO403I pseudo-message. This pseudo-message causes CMEM to simulate IEF403I processing, which is described in Support for ON DSNEVENT and ON STEP.

3. Under z/OS, IBM FTP functions as a UNIX process running under z/OS. Therefore it follows the UNIX standard, one aspect of which is that the name of the job is set to the userID of the person who issued the FTP request. This UNIX standard creates a problem, because the operator who writes the CMEM rule must know at that stage which user will issue an FTP request.

   The solution to this problem is to use the statement ON DSNEVENT FTP*. The result is that any FTP process will trigger the rule.

Recovering Lost Dataset Events from SMF

In case of a CMEM outage, Control-M CMEM provides a process for recovering the DSNEVENTs that were not handled.

The process involves two utilities, one (CTMEVRT) to retrieve the missing dataset events and a second (CTMEVEX) to execute the matching DO actions (DO COND and DO FORCEJOB). The output file of CTMEVRT is first manually edited by the user, who then provides the edited file as an input to CTMEVEX. Note that only DSNEVENTs are processed; all other non-dataset events are ignored. Similarly, only the DO COND and DO FORCEJOB actions are processed, all other DO actions are ignored.

The CTMEVRT utility uses SMF records written by z/OS and z/OS Communications Server to identify events that occurred during the CMEM outage. The user must specify the start and end times that define the approximate duration of the CMEM outage. The user can also specify include and exclude statements so that only the relevant events will be listed.

The output of CTMEVRT, the DAEVENTS file, is a list of events, identified as most probably requiring handling. BMC recommends that the user review the DAEVENTS file and edit it if necessary (for example, by removing events that are no longer relevant or might have already been processed by CMEM before the outage).

The CTMEVEX utility processes the edited DAEVENTS file, converting the DO actions of the events listed in DAEVENTS to IOACND commands (for adding or deleting conditions) and CTMJOB commands (to order jobs to the Control-M Active Jobs File using the FORCE option).

CTMEVEX can be run in simulation mode for displaying the statements that could be used as the input to the IOACND and CTMJOB utilities. The user can review the statements and decide if any adjustments are required before actually running CTMEVEX in execution mode.

For more information, see the INCONTROL for z/OS Utilities Guide.

Recovery Scenario Example

*Date      Time     SIDC Data Set Name       JobNameDisp RuleName        Actions
2016/01/30 11:34:14 MVS3 N FTP.FILE.INCOMING1FTPUSERC    0001-PROD:FTP* DO COND FILE_INCOMING1 ODAT +
2016/01/30 11:34:14 MVS3 N FTP.FILE.INCOMING1FTPUSERC    0001-PROD:FTP* DO FORCEJOB TABLE FTP JOB FTPA UFLOW N DATE ODAT LIBRARY PROD.JCL
2016/01/30 11:39:22 MVS3 Y FTP.FILE.INCOMING2FTPUSERC    0001-PROD:FTP* DO COND FILE_INCOMING2 ODAT +
2016/01/30 11:39:22 MVS3 Y FTP.FILE.INCOMING2FTPUSERC    0001-PROD:FTP* DO FORCEJOB TABLE FTP JOB FTPA UFLOW N DATE ODAT LIBRARY PROD.JCL

*Date      Time     SIDC Data Set Name       JobNameDisp RuleName          Actions
*2016/01/30 11:34:14 MVS3 N FTP.FILE.INCOMING1FTPUSERC    0001-PROD:FTP* DO COND FILE_INCOMING1 ODAT +
*2016/01/30 11:34:14 MVS3 N FTP.FILE.INCOMING1FTPUSERC    0001-PROD:FTP* DO FORCEJOB TABLE FTP JOB FTPA UFLOW N DATE ODAT LIBRARY PROD.JCL
2016/01/30 11:39:22 MVS3 Y FTP.FILE.INCOMING2FTPUSERC    0001-PROD:FTP* DO COND FILE_INCOMING2 ODAT +
2016/01/30 11:39:22 MVS3 Y FTP.FILE.INCOMING2FTPUSERC    0001-PROD:FTP* DO FORCEJOB TABLE FTP JOB FTPA UFLOW N DATE ODAT LIBRARY PROD.JCL

CMEM Rule Parameters: Summary

Figure 338 CMEM Rule Definition Screen

RL: JOBNAM1    LIB CTM.PROD.RULES                      TABLE: CMEMRULE
COMMAND ===>                                           SCROLL===> CRSR
+--------------------------------------------------------------------+
  ON JOBARRIV = JOBNAM1 JTYPE   SMFID      SYSTEM           And/Or/Not 
  OWNER CTMCTLMGROUP                     MODE PROD    RUNTSEC NONE  
  THRESHOLD                                                           
  DESCRIPTION CONVERSION: ON JOB JOBNAM1ARRIVAL FORCEJOB            
  DESCRIPTION                                                         
  ====================================================================
  DO FORCEJOB = TABLE  TABLE1     JOB           UFLOW N    DATE ODAT
                LIBRARY CTM.PROD.SCHEDULE                             
  DO                                                                  
  ====================================================================
======= >>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
                                                                                    
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF               21.00.36

The parameters of the CMEM Rule Definition screen are divided into the following categories:

• Event Selection Parameters

• General Parameters

• Action Parameters

A brief summary of the parameters in each category is provided on the following pages. This is followed by a detailed description of each parameter in alphabetical order.

CMEM Event Selection Parameters

The following parameters identify the events that trigger the rule.

Table 229 CMEM Event Selection Parameters

Subparameters of these parameters are described in the detailed description of each parameter later in this chapter.

CMEM General Parameters

The following parameters contain general information about the rule.

Table 230 CMEM General Parameters

CMEM Action Parameters

The following parameters (DO statements) specify actions to be performed.

Table 231 CMEM Action Parameters

CMEM Parameter Descriptions

The following pages contain detailed descriptions of all parameters available in the CMEM Rule Definition screen. Parameters are arranged in alphabetical order. Within each parameter, subparameters are arranged according to the order of the fields on the screen.

Each parameter begins on a new page, including:

• a brief explanation of the purpose of the parameter

• the format required for defining the parameter within an extract of the CMEM screen

• general information explaining the parameter and its usage

• where applicable, some practical examples illustrating implementation of the parameter

For more information on the CMEM Rule Definition facility, see Online Facilities.

DESCRIPTION (CMEM): General Parameter

Description of the rule to be displayed in the Rule List screen.

Figure 339 DESCRIPTION (CMEM) Parameter Format

Optional. The DESCRIPTION parameter consists of one or more lines that can contain free text. Each line is 61 characters in length. Upon typing text in a DESCRIPTION line and pressing Enter, a new DESCRIPTION line is opened.

General Information for DESCRIPTION (CMEM)

The DESCRIPTION parameter does not affect rule processing. The text entered in the first DESCRIPTION line appears to the right of the rule name in the Rule List screen. It is intended to let the user know at a glance the purpose of, or some other key information about, the rule. The text can be typed in any language.

Example for DESCRIPTION (CMEM)

RL: CICSPROD   LIB CTM.PROD.RULES                         TABLE: STCS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
 ON JOBEND   = CICSPROD JTYPE   SMFID    SYSTEM            And/Or/Not
 OWNER ADMIN    GROUP CICS                    MODE PROD    RUNTSEC
 THRESHOLD
 DESCRIPTION   START THE BATCH SHIFT
 DESCRIPTION
 ====================================================================
 /* INFORM CONTROL-M THAT THE BATCH CAN BE STARTED
 DO COND     = START-BATCH          ODAT +
 DO
 ====================================================================
======= >>>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

DO Statement (CMEM): Action Parameter

Actions to perform when the rule is triggered.   

Figure 341 DO (CMEM) Parameter Format

At least one DO statement must be specified in each rule. Specify DO statements as follows:

• Type the action keyword (such as COND) in the DO field and press Enter.

• When required, subparameter fields are displayed. Fill in the subparameters and press Enter again.

Multiple DO statements can be specified. After entering a DO statement, another DO line is automatically displayed. Multiple DO statements have an AND relationship and are performed sequentially.

The following are valid DO actions. Each is discussed individually in this chapter.

Table 232 DO (CMEM) Parameter Actions

DO COND (CMEM): Action Parameter

Add or delete prerequisite conditions.    

Figure 342 DO COND (CMEM) Parameter Format

Optional. Type the word COND (or its abbreviation CON) in the DO field and press Enter. The following subparameters are displayed:

Table 233 DO COND (CMEM) Subparameters

General Information for DO COND (CMEM)

When a rule containing a DO COND statement is triggered, the designated prerequisite conditions are added or deleted (as specified) from the IOA Conditions file by the Control-M monitor.

A prerequisite condition can define any user-specified situation. The following are a few examples of prerequisite conditions:

IMS-ACTIVE
WEEKEND
SALARY-OK

Prerequisite conditions created or deleted by the DO COND parameter can activate or deactivate Control-O rules, or trigger (or stop) the execution of processes (jobs, and so on) in Control-M, Control-D and other environments.

CMEM AutoEdit System variable %%$JNAME and, for ON DSNEVENT events, variables %%$Dx, %%$DSN, or %%$DSNDISP can be specified in condition names in DO COND statements and are replaced (resolved) at time of rule triggering. For more information, see CMEM AutoEdit Variables.

Representative dates (such as ODAT) are resolved to the actual corresponding date in the site-standard format.

Examples for DO COND (CMEM)

RL: CICSPROD   LIB CTM.PROD.RULES                         TABLE: STCS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBEND   = CICSPROD JTYPE   SMFID      SYSTEM         And/Or/Not 
  OWNER ADMIN    GROUP CICS                    MODE PROD   RUNTSEC    
  THRESHOLD                                                           
  DESCRIPTION   START THE BATCH SHIFT                                 
  DESCRIPTION                                                         
  ===================================================================
  /* INFORM CONTROL-M THAT THE BATCH CAN BE STARTED                   
  DO COND     = START-BATCH          ODAT +                      
  DO                                                                  
  ===================================================================
======= >>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

RL: NDM        LIB CTM.PROD.RULES                          TABLE: MGT
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON DSNEVENT = NDM      JTYPE   SMFID      SYSTEM                
     DSN      TRAN.*                                      DISP CATLG 
     PROCSTEP            PGMSTEP            STEPRC OK      And/Or/Not 
  OWNER ADMIN    GROUP NDM                     MODE         RUNTSEC   
  THRESHOLD                                                           
  DESCRIPTION   NOTIFY CONTROL-M THAT TRAN DATASET ARRIVED VIA NDM    
  DESCRIPTION                                                         
  ===================================================================
  DO COND     = FILE-RECEIVED        ODAT +                       
  DO                                                                  
 ====================================================================
======= >>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

DO FORCEJOB (CMEM): Action Parameter

Force a job.

Figure 345 DO FORCEJOB (CMEM) Parameter Format

Optional. Type the word FORCEJOB (or its abbreviation F) in the DO field and press Enter. The following subparameters are displayed:

Table 234 DO FORCEJOB (CMEM) Subparameters

The following CMEM Auto-Edit variables are available to newly forced jobs and can be used in the Control-M job scheduling definition or JCL:

Table 234a CMEM AutoEdit Variables

General Information for DO FORCEJOB (CMEM)

DO FORCEJOB places a job order in the Control-M Active Jobs file, even if the basic scheduling criteria of the job are not satisfied. For more information, see Job Ordering and Job Forcing.

The DO FORCEJOB statement in CMEM enables Control-M to order Control-M tables based on the occurrence of an event, for example, job arrival, job end, data set event, or step event.

When forcing all jobs in a table, the UFLOW subparameter enables you to determine whether the jobs are run as a unique flow.

The DO FORCEJOB statement is executed by the Control-M monitor.

If the Control-M monitor is not active, the DO FORCEJOB request is queued and performed when the Control-M monitor becomes active.

DO FORCEJOB logic works differently for job arrival events than for job end, data set or step events:

Job End Events

DO FORCEJOB statements specified in a job end event rule are performed only if the terminating job is not under Control-M.

Data set or Step Events

Data set or step event rules are performed regardless of where the job was submitted. However, if the triggering job was ordered or submitted by Control-M, the job will not become an On Spool job. For more information about On Spool jobs, see On Spool Jobs.

Job Arrival Events

For the first DO FORCEJOB statement in a rule:  

• If the job that triggered the job arrival event was submitted by Control-M, the DOFORCEJOB statement is ignored.

• If the job that triggered the job arrival event was not submitted by Control-M, Control-M forces the requested table or job. Control-M scans the forced table looking for a job whose MEMNAME value matches, or is a mask for, the name of the job whose arrival triggered the rule.

  • If a matching job is found, it becomes an On Spool job. For more information, see Creating On Spool Jobs.

  • If a matching job is not found, or more than one job is ordered, all other jobs are not On Spool jobs, and are processed normally by Control-M.

For other DO FORCEJOB statements in the same rule:

• DO FORCEJOB is performed regardless of the source of the job.

• The table is forced.

DO FORCEJOB is not executed if a preceding ON JOBARRIV rule with a DO FORCEJOB action was already executed for this event.

Examples for DO FORCEJOB (CMEM)

RL: *          LIB CTM.PROD.RULES                         TABLE: JOBS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBARRIV = *       JTYPE J SMFID      SYSTEM          And/Or/Not 
  OWNER ADMIN    GROUP EXTJOBS                MODE         RUNTSEC    
  THRESHOLD                                                           
  DESCRIPTION   CONTROL ALL JOBS NOT SUBMITTED BY CONTROL-M           
  DESCRIPTION                                                         
  ===================================================================
  DO FORCEJOB = TABLE  ANYJOB   JOB            UFLOW N    DATE ODAT
                LIBRARY CTM.PROD.SCHEDULE                         
  DO                                                                  
  ===================================================================
======= >>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

RL: A*         LIB CTM.PROD.RULES                         TABLE: JOBS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBARRIV = A*       JTYPE J SMFID      SYSTEM       And/Or/Not O
  ON JOBARRIV = C*       JTYPE J SMFID      SYSTEM       And/Or/Not
  OWNER ADMIN    GROUP CICS                    MODE         RUNTSEC   
  THRESHOLD                                                           
  DESCRIPTION CONTROL ALL JOBS SUBMITTED BY CICS
  DESCRIPTION (BEGINNING WITH A*OR C*)                               
  DESCRIPTION                                                        
  ===================================================================
  DO FORCEJOB = TABLE  CICSJOB  JOB %%$JNAME   UFLOW Y    DATE  ODAT
                LIBRARY CTM.PROD.SCHEDULE                           
  DO                                                                  
  ===================================================================
======= >>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

DO RULE (CMEM): Action Parameter

Invoke a Control-O rule from within the current rule. Available only if Control-O is active.

Figure 348 DO RULE (CMEM) Parameter Format

Optional. Type the word RULE (or its abbreviation RU) in the DO field and press Enter. The following subparameters are displayed:

Table 235 DO RULE (CMEM) Subparameters

General Information for DO RULE (CMEM)

To define a DO RULE statement in a CMEM rule, and to access a CMEM rule containing a DO RULE statement, Control-O must be installed.

When a DO RULE statement is encountered during rule processing, Control-O invokes the specified rule. When processing of the invoked rule is completed, processing continues sequentially from the point after the DO RULE statement in the initial (calling) rule.

When a DO RULE statement is executed, the specified rule is searched for among the loaded rules according to the specified rule name, table, library, and owner. If the rule is found but is not active, for example, if the runtime scheduling criteria are not satisfied, the "invoked" rule is not executed and the calling rule continues execution with the next DO statement.

The CMEM calling rule can pass an argument string as input to the called rule. This argument string can contain CMEM AutoEdit expressions that are resolved at time of rule execution. The argument string can be accessed by the called rule through Control-O System variable %%$ARGS. If a called rule calls another Control-O rule, the %%$ARGS values passed in the earlier call are overwritten by the %%$ARGS values passed by the later call. For information about the AutoEdit facility in Control-O, see the Control-O User Guide.

A Control-O rule specified with an ON RULE statement can be invoked any number of times by DO RULE calls.

A called Control-O rule can invoke other Control-O rules using DO RULE statements. Nesting of DO RULE calls, for example, rule 1 calls rule 2, that calls rule 3, up to 20 deep is supported. A Control-O rule can be called recursively.

Example for DO RULE (CMEM)

RL: TCPIP      LIB CTM.PROD.RULES                        TABLE: TRANS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON DSNEVENT = TCPIP    JTYPE   SMFID      SYSTEM                    
     DSN      PROD.TRAN.*                                  DISP CATLG 
     PROCSTEP            PGMSTEP            STEPRC OK     And/Or/Not  
  OWNER ADMIN    GROUP TCPIP                   MODE         RUNTSEC   
  THRESHOLD                                                           
  DESCRIPTION   WHEN DATASET PROD.TRAN.* IS CATALOGED BY TCIP,        
  DESCRIPTION   START A TASK TO PROCESS IT                            
  DESCRIPTION                                                         
  ===================================================================
  /* START A STARTED TASK TO PROCESS THE RECEIVED FILE.               
  /* WHEN THE DATASET IS CATALOGED, INVOKE RULE PROCFILE.             
  /* PARAMETERS PASSED ARE THE STC NAME AND THE TIMEOUT VALUE.        
  DO RULE     = PROCFILE  %%$DSN                         OWNER  PROD  
     TABLE    PRODRULE   LIBRARY CTO.PROD.RULES                       
     SYSTEM              SHARELOC       TIMEOUT                       
  DO                                                                  
  ===================================================================
======= >>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< ======
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF,             21.00.36

DO SHOUT (CMEM): Action Parameter

Send ("shout") a message to a specific destination. Available only if Control-O is active.

Figure 350 DO SHOUT (CMEM) Parameter Format

Optional. Type SHOUT in the DO field and press Enter. The following subparameters are displayed:

Table 236 DO SHOUT (CMEM) Subparameters

General Information for DO SHOUT (CMEM)

The message is sent to the required destination when the accompanying ON statement criteria are satisfied.

It is also possible to shout to a ROSCOE user. For additional information, see your INCONTROL administrator.

Subparameter TO (CMEM)

Type TO=USERID-userid to write the message to the IOA Log under the user ID specified in the parameter.

Type TO=OPER[dd]-{rrr,-ccc} to send the message to all operator consoles, or to operator consoles selected according to route code (rrr) or console ID number (-ccc). The descriptor code (dd) determines the type of message displayed. The dd, rrr, and -ccc parameters are optional and can be assigned any valid value. Dashes (–) are used to separate the parameters specified.

For more detailed information regarding route and descriptor codes, refer to the IBM publication Routing and Descriptor Codes, GC38-1102.

Examples

Table 237 DO SHOUT OPER (CMEM) Subparameter Examples

Type TO=TSO-logonid to send the message to a groupid or logonid. The Shout facility first searches the IOA Dynamic Destination table for the specified ID. If the table contains an entry that matches the value, the content of the entry is used as the target for the shouted message. The entire TO field is used. Therefore, when directing the message to a remote user, do not append Nn or Mm. Instead, do this in the IOA Dynamic Destination Table itself. For more information, see the description of Dynamic Destination Tables in the INCONTROL for z/OS Administrator Guide.

If no matching ID is found in the Dynamic Destination table, the Shout facility assumes the specified ID is a logonid. It then creates a TSO message that it hands over to MVS. MVS then sends the message to that logonid. If the logonid does not exist, MVS cannot send the message, but no error message is generated. When a second value is used, the message is sent to the TSO logonid in the specified computer or node (machine ID). To determine the machine ID under JES2, enter JES command $D MEMBER.

The URGENCY subparameter

The URGENCY value indicates the urgency level of the message.

In addition, if the destination is USERID-userid (or U-userid), the user can control, according to urgency, which messages are displayed when the IOA Log file is accessed. Urgent and very urgent messages are highlighted on the screen. For more details, see IOA Log Facility.

The CTO282I Subparameter

By default, the CTO282I subparameter has a value of Y, and CTO282I is placed as the message ID preceding the message text. When CTO282I is set to N, the first word of the message text becomes the message ID.

Control-O AutoEdit Variables

Control-O AutoEdit variables embedded in the TO and MSG subparameters are automatically resolved at time of rule activation. For more information about the AutoEdit facility, see JCL and AutoEdit Facility.

Example for DO SHOUT (CMEM)

RL: DB2MSTR    LIB CTM.PROD.RULES                         TABLE: STCS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBEND   = DB2MSTR  JTYPE S SMFID      SYSTEM        And/Or/Not  
  OWNER ADMIN    GROUP DB2                     MODE         RUNTSEC   
  THRESHOLD                                                           
  DESCRIPTION   WARN DBA THAT DB2 MASTER ENDED                        
  DESCRIPTION                                                         
  ===================================================================
  DO SHOUT    = TO TSO-DBA         URGENCY  U  SYSTEM         CTO282I
     MESSAGE DB2 MASTER ENDED - PLEASE CHECK!                        
  DO                                                                 
  ===================================================================
======= >>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

DO STOPJOB (CMEM): Action Parameter

Stop execution of the job that triggered the rule after the current step.

Figure 352 DO STOPJOB (CMEM) Parameter Format

Optional. Type STOPJOB, or its abbreviation ST, in the DO field and press Enter.

General Information for DO STOPJOB (CMEM)

When DO STOPJOB is performed, the job that triggered the rule is terminated after the current step, and no further steps (including those marked COND=EVEN or COND=ONLY) are executed. An appropriate message is written to the job log. If the stopped job is controlled by Control-M, it terminates with a status of ENDED NOTOK.

DO STOPJOB is not executed for TSO users.

DO STOPJOB is meaningful only:

• for data set events or step events

• when there are additional steps in a job or started task

Example for DO STOPJOB (CMEM)

RL: PROD*      LIB CTM.PROD.RULES                          TABLE: JOBC
OMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON DSNEVENT = PROD*    JTYPE J SMFID      SYSTEM                    
     DSN      PROD.*                                       DISP NCT2  
     PROCSTEP            PGMSTEP            STEPRC         And/Or/Not 
  OWNER ADMIN    GROUP PRODJOBS                MODE         RUNTSEC   
  THRESHOLD                                                           
  DESCRIPTION   STOP THE JOB ON NCT2 DISPOSITION                      
  DESCRIPTION                                                         
  ===================================================================
  /* STOP THE JOB                                                     
  DO STOPJOB                                                    
  DO                                                                  
  ===================================================================
======= >>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

GROUP (CMEM): General Parameter

Name of the group to which the rule belongs.

Figure 354 GROUP (CMEM) Parameter Format

Optional. Name of 1 through 20 characters, with no embedded blanks.

General Information for GROUP (CMEM)

The GROUP parameter is used to provide more convenient handling of rules. It enables retrieval of information on a group basis. The group name appears in all important IOA Log file messages relating to the rules of the group.

Example for GROUP (CMEM)

RL: CICSPROD   LIB CTM.PROD.RULES                         TABLE: STCS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBEND   = CICSPROD JTYPE   SMFID      SYSTEM         And/Or/Not
  OWNER ADMIN    GROUP CICS                    MODE PROD    RUNTSEC   
  THRESHOLD                                                           
  DESCRIPTION   START THE BATCH SHIFT                                 
  DESCRIPTION                                                         
  ===================================================================
  /* INFORM CONTROL-M THAT THE BATCH CAN BE STARTED                   
  DO COND     = START-BATCH          ODAT +                      
  DO                                                                  
  ===================================================================
======= >>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

MODE (CMEM): General Parameter

Rule operation mode.

Figure 356 MODE (CMEM) Parameter Format

Optional. Valid values, and their abbreviations, for the MODE parameter are:

Table 238 MODE (CMEM) Parameter Values

General Information for MODE (CMEM)

Test mode provides the opportunity to test the effects of a rule definition without actually performing the specified DO actions.

Log mode provides a transition between Test and Production mode. Like Production mode, Log mode enables performance of the specified DO actions. However, Log mode also records the trace information in the test journal for tracking purposes.

When tracking of the performed actions for test purposes is no longer required, the rule can be placed in Production mode.

For sites in which Control-O is not installed, or in which the Control-O Automation Log facility is not active, the trace information is written to the sysout referenced by DD statement DAACTLOG.

For Control-O sites in which the Automation Log facility is active, the trace information is recorded in the Automation log. For more information, see the Control-O User Guide.

Example for MODE (CMEM)

RL: CICSPROD   LIB CTM.PROD.RULES                         TABLE: STCS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBEND   = CICSPROD JTYPE   SMFID      SYSTEM         And/Or/Not  
  OWNER ADMIN    GROUP CICS                    MODE PROD    RUNTSEC   
  DESCRIPTION   START THE BATCH SHIFT                                 
  DESCRIPTION                                                         
  ===================================================================
  /* INFORM CONTROL-M THAT THE BATCH CAN BE STARTED                   
  DO COND     = START-BATCH          ODAT +                           
  DO                                                                  
  ===================================================================
======= >>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

ON Statement (CMEM): Event Parameter

Event selection criteria that trigger performance of the rule.

Figure 358 ON (CMEM) Parameter Format

Mandatory. At least one ON statement must be entered. Type an ON statement, or its abbreviation, in the ON field and press Enter. Additional subparameters are displayed.

The following are valid ON statements (and their abbreviations). Each is described in detail later in this chapter.

Table 239 ON (CMEM) Parameter Statements

The And/Or/Not subparameter is always displayed in each specified ON statement. It is a conjunctional parameter for linking ON statements. Optional.

Entering a value for this subparameter opens a new ON statement and links the newly opened statement to the current ON statement.

When multiple ON statements are entered, the combinations of ON statements that can satisfy the selection criteria depend on the And/Or/Not values linking those ON statements. The logic applied to And/Or/Not subparameters is described in "General Information", which follows.

Valid values are:

• A (And) – indicates AND logic between the two statements
  If both ON statements are true, the event criteria are satisfied.

• O (Or) – indicates OR logic between the preceding and following ON statements
  If either statement is true, the event criteria are satisfied.

• N (Not) – indicates AND NOT logic between the two statements
  If the prior statement is true and the subsequent statement is false, the event criteria are satisfied.

General Information for ON Statement (CMEM)

Upon typing an ON parameter and pressing Enter, additional fields (subparameters) are displayed. Each ON parameter and its subparameters comprise an ON statement. At least one ON statement is required in a rule definition. Additional ON statements can be entered using the And/Or/Not option.

The first eight characters of the event name appear as the name of the rule in the Rule List screen.

And/Or/Not Subparameter Logic (CMEM)

The following logic is applied:

• AND and NOT logic are applied before OR logic

• NOT means AND NOT as represented below

• A NOT B is interpreted as A AND (NOT B)

• A OR B AND C is interpreted as A OR (B AND C)

• A AND B OR C NOT D is interpreted as [(A AND B) OR (C AND NOT D)]

Use of OR logic reduces the amount of redundant data in the CMEM rule library and improves rule management.

ON DSNEVENT JOBA STEPA
AND 
ON DSNEVENT JOBA STEPB

Character Masking (CMEM)

The following mask characters can be used when entering ON statement values:

• * represents any number of characters, including no characters

• ? represents any one character

ON DSNEVENT (CMEM): Event Parameter

Monitor a data set disposition event.

Figure 359 ON DSNEVENT (CMEM) Parameter Format

Optional. Type D (DSNEVENT) in the ON field and press Enter. The following subparameters are displayed:

Table 240 DSNEVENT (CMEM) Subparameters

General Information for ON DSNEVENT (CMEM)

ON DSNEVENT rules are triggered by the setting of data set disposition at time of deallocation (during step termination or dynamic deallocation).

DO statements in the rule are executed either immediately upon detection of the data set event or at the end of the job step that caused the data set event, depending on the value entered in the STEPRC subparameter (described above).

Immediate execution is useful for performing actions when data sets are dynamically de-allocated using long running address spaces (for example, CICS, TSO users, and file transfer monitors).

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

ON DSNEVENT rules do not intercept data set events, such as cataloging, uncataloging, or scratching, when they are performed using MVS CATALOG or SCRATCH macros.

The following restrictions apply to ON DSNEVENT statements:

• Do not specify an ON DSNEVENT statement with any other type of ON statement in a rule.

• Do not specify different STEPRC values in the same rule. If you do, the last specified value is used.

Entering values for the optional subparameters PROCSTEP, PGMSTEP and STEPRC limits the situations that can satisfy the step termination event. Conversely, if a subparameter is blank, that subparameter is ignored.

For example,

• If a PGMSTEP and PROCSTEP value are both entered, the rule is triggered only if the specified PGMSTEP is completed in the specified PROCSTEP.

• If a PGMSTEP value is entered without a PROCSTEP value, the rule is triggered if the PGMSTEP is completed anywhere within the job stream.

The STEPRC Subparameter (CMEM)

When entering a condition code or abend code in the STEPRC subparameter, any characters in the code can be replaced by an asterisk (*). An asterisk means "any value" for the character it replaces. For example, if S*13 is entered, the code criteria is satisfied by codes S013, S613, S913, and so on.

When entering condition and/or abend codes, the following qualifiers can be used as indicated:

Table 241 Valid STEPRC Code Qualifiers

The SMFID and SYSTEM Subparameters (CMEM)

The default values for the SMFID and SYSTEM subparameters are the current system. If no value is entered for either SMFID or SYSTEM, the rule is triggered only by events that occur in the current system.

Example for ON DSNEVENT (CMEM)

RL: PRDJ0003   LIB CTM.PROD.RULES                       TABLE: BACKUP
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON DSNEVENT = PRDJ0003 JTYPE   SMFID      SYSTEM                    
     DSN      PROD.*                                       DISP CATLG 
     PROCSTEP            PGMSTEP            STEPRC OK      And/Or/Not 
  OWNER ADMIN    GROUP BACKUP                  MODE PROD    RUNTSEC   
  THRESHOLD                                                           
  DESCRIPTION   NEW DATASET CREATED - TRIGGER A BACKUP JOB            
  DESCRIPTION                                                         
  ===================================================================
  /* SCHEDULE A CONTROL-M JOB TO HANDLE THE BACKUP                    
  /*                                                                  
  DO FORCEJOB = TABLE  BACKUP   JOB BACKUP     UFLOW N    DATE ODAT
                LIBRARY CTM.PROD.SCHEDULE                        
  /*                                                                  
  DO                                                                  
  ===================================================================
======= >>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF,             21.00.36

ON JOBARRIV (CMEM): Event Parameter

Monitor a job arrival event on the JES spool.

Figure 361 ON JOBARRIV (CMEM) Parameter Format

Optional. Type JA (JOBARRIV) in the ON field and press Enter. The following subparameters are displayed:

Table 242 ON JOBARRIV (CMEM) Subparameters

General Information for ON JOBARRIV (CMEM)

ON JOBARRIV statements can be used to trigger Control-M actions based on the appearance of a job on the JES spool.

Combination of an ON JOBARRIV statement and a DO FORCEJOB statement can be used to control an external job through Control-M. Such a job is called an On Spool job. For more information, see On Spool Jobs.

The default values for the SMFID and SYSTEM subparameters are the current system. If no value is entered for either SMFID or SYSTEM, the rule is triggered only by events that occur in the current system.

Example for ON JOBARRIV (CMEM)

RL: BKP*       LIB CTM.PROD.RULES                       TABLE: BACKUP
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBARRIV = BKP*     JTYPE   SMFID      SYSTEM         And/Or/Not
  OWNER ADMIN    GROUP BACKUP                  MODE PROD    RUNTSEC
  DESCRIPTION   MONITOR EXTERNAL BACKUP JOBS                      
  DESCRIPTION                                                         
  ===================================================================
  /* TELL CONTROL-M TO MONITOR THIS JOB                               
  /*                                                                  
  DO FORCEJOB = TABLE  BACKUP   JOB            UFLOW N    DATE ODAT
                LIBRARY CTM.PROD.SCHEDULE                             
  /*                                                                  
  DO                                                                  
  ===================================================================
==== >>>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<<<<< ==
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

ON JOBEND (CMEM): Event Parameter

Monitor a job termination event.

Figure 363 ON JOBEND (CMEM) Parameter Format

Optional. Type JE (JOBEND) in the ON field and press Enter. The following subparameters are displayed:

Table 243 JOBEND (CMEM) Subparameters

General Information for ON JOBEND (CMEM)

ON JOBEND statements can be used to trigger Control-M actions based on the termination of a job.

The default values for the SMFID and SYSTEM subparameters are the current system. If no value is entered for either SMFID or SYSTEM, the rule is triggered only by events that occur in the current system.

Example for ON JOBEND (CMEM)

RL: CICSPROD   LIB CTM.PROD.RULES                         TABLE: STCS
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBEND   = CICSPROD JTYPE   SMFID      SYSTEM         And/Or/Not
  OWNER ADMIN    GROUP CICS                    MODE PROD    RUNTSEC   
  DESCRIPTION   START THE BATCH SHIFT                                 
  DESCRIPTION                                                         
  ===================================================================
  /* INFORM CONTROL-M THAT THE BATCH CAN BE STARTED                   
  DO COND     = START-BATCH          ODAT +                        
  DO                                                                  
  ===================================================================
======= >>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

ON STEP (CMEM): Event Parameter

Monitor a job step termination event.

Figure 365 ON STEP (CMEM) Parameter Format

Optional. Type S (STEP) in the ON field and press Enter. The following subparameters are displayed:

Table 244 ON STEP (CMEM) Subparameters

General Information for ON STEP (CMEM)

ON STEP rules are triggered when specified job steps terminate with specified return codes or statuses.

Entering values for the optional subparameters PROCSTEP, PGMSTEP and STEPRC limits the situations that can satisfy the step termination event. Conversely, if a subparameter is blank, that subparameter is ignored.

• If a PGMSTEP and PROCSTEP value are both entered, the rule is triggered only if the specified PGMSTEP is completed in the specified PROCSTEP.

• If a PGMSTEP value is entered without a PROCSTEP value, the rule is triggered if the PGMSTEP is completed anywhere within the job stream.

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

The SMFID and SYSTEM Subparameters

The default values for the SMFID and SYSTEM subparameters are the current system. If no value is entered for either SMFID or SYSTEM, the rule is triggered only by events that occur in the current system.

The STEPRC Subparameter

When entering a condition code or abend code in the STEPRC subparameter, any characters in the code can be replaced by an asterisk (*). An asterisk means "any value" for the character it replaces. For example, if S*13 is entered, the code criteria is satisfied by codes S013, S613, S913, and so on. When entering condition and/or abend codes, the following qualifiers can be used as indicated:

Table 245 ON STEP Subparameter STEPRC Qualifiers

Example for ON STEP (CMEM)

RL: PRD00010   LIB CTM.PROD.RULES                     TABLE: CMEMRULE
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON STEP     = PRD00010 JTYPE   SMFID      SYSTEM                
     PROCSTEP STEP2      PGMSTEP            STEPRC OK      And/Or/Not
  OWNER CTMCTLM  GROUP                      MODE PROD    RUNTSEC NONE 
  THRESHOLD                                                           
  DESCRIPTION FOLLOWING STEP2 IN JOB PRD00010 ADD A CONDITION         
  DESCRIPTION INDICATING THAT THE FILE WAS CREATED                    
  DESCRIPTION                                                         
  ===================================================================
  DO COND     = FILE-CREATED         ODAT +                       
  DO                                                                  
  ===================================================================
======= >>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

OWNER (CMEM): General Parameter

Identifies the user requesting CMEM services.

Figure 367 OWNER (CMEM) Parameter Format

Mandatory. The OWNER parameter must be 1 through 8 characters.

General Information for OWNER (CMEM)

The OWNER parameter is primarily used by the internal security mechanism of CMEM to determine, together with an external security product, such as TOP SECRET, RACF or ACF2, those operations each user is authorized to perform.

Example for OWNER (CMEM)

RL: BKP*       LIB CTM.PROD.RULES                       TABLE: BACKUP
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON JOBARRIV = BKP*     JTYPE   SMFID      SYSTEM         And/Or/Not 
  OWNER ADMIN    GROUP BACKUP                  MODE PROD    RUNTSEC   
  THRESHOLD                                                           
  DESCRIPTION   MONITOR STARTUP OF BACKUP JOBS                        
  DESCRIPTION                                                         
  ===================================================================
  /* TELL CONTROL-M TO MONITOR THIS JOB                               
  /*                                                                  
  DO FORCEJOB = TABLE  BACKUP   JOB            UFLOW N    DATE ODAT
                LIBRARY CTM.PROD.SCHEDULE                             
  /*                                                                  
  DO                                                                  
  ===================================================================
======= >>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF              21.00.36

RUNTSEC (CMEM): General Parameter

Specifies the runtime security environment for the rule.

Figure 369 RUNTSEC (CMEM) Parameter Format

Optional. The abbreviation, that is, the first letter, of the desired value can be entered. Valid values are:

Table 246 Valid RUNTSEC (CMEM) Values

SECURITY RUNTDFT=NONE,
RUNTCACH=100 RUNTIME SECURITY CACHE specified.

General Information for RUNTSEC (CMEM)

The RUNTSEC parameter is used by the CMEM security interface for interaction with external security products, such as CA-RACF, CA-TOP SECRET, and CA-ACF2. For more information see the INCONTROL for z/OS Security Guide.

CMEM security checks are carried out in two stages: at order time and at runtime.

At order time, security checks are carried out to ascertain whether the owner of the rule, as specified in the OWNER subparameter, is authorized to code each one of the rule statements.

At runtime, additional security checks are carried out to determine whether the user who owns the rule (RUNTSEC=OWNER) or the user who triggered the rule (RUNTSEC=TRIGGER) is authorized to execute a DO COND or DO FORCEJOB statement defined in the rule.

Example for RUNTSEC (CMEM)

RL: PRDJ0003   LIB CTM.PROD.RULES                       TABLE: BACKUP
COMMAND ===>                                          SCROLL===> CRSR
+-------------------------------------------------------------------+
  ON DSNEVENT = PRDJ0003 JTYPE   SMFID      SYSTEM                    
     DSN      PROD.*                                      DISP CATLG  
     PROCSTEP            PGMSTEP            STEPRC OK     And/Or/Not  
  OWNER ADMIN    GROUP BACKUP              MODE PROD  RUNTSEC TRIGGER
  THRESHOLD                                                           
  DESCRIPTION   NEW DATASET CREATED - TRIGGER A BACKUP JOB            
  DESCRIPTION                                                         
  ===================================================================
  /* SCHEDULE A CONTROL-M JOB TO HANDLE THE BACKUP                    
  /*                                                                  
  DO FORCEJOB = TABLE  BACKUP   JOB BACKUP     UFLOW N    DATE ODAT
                LIBRARY CTM.PROD.SCHEDULE                             
  /*                                                                  
  DO                                                                  
  ===================================================================
======= >>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF,             21.00.36

THRESHOLD (CMEM): Runtime Scheduling Parameter

Limits the number of times that a rule can be triggered in one CMEM Monitor cycle.

Figure 371 THRESHOLD (CMEM) Parameter Format

Optional. Valid values are 1 through 999999999.

General Information for THRESHOLD (CMEM)

The THRESHOLD parameter is used to prevent unlimited loops within the system. The value assigned to the parameter indicates the maximum number of times that CMEM will trigger the rule in a single CMEM interval.

Before CMEM triggers a rule, it determines whether the rule has already been triggered the maximum number of times in the current CMEM interval. If so, CMEM does not trigger the rule again, but instead sets the STATUS of the rule to SUSPEND and issues message CTO285W to the console.

If no value, or a value of 0, is entered for THRESHOLD, CMEM does not limit the number of times that the rule can be triggered.

Example for THRESHOLD (CMEM)

RL: PRDJOB01   LIB CTM.PROD.RULES                          TABLE: JOB
COMMAND ===>                                          SCROLL===> CRSR
+--------------------------------------------------------------------
  ON JOBARRIV = JOBNM233 JTYPE   SMFID      SYSTEM         And/Or/Not 
  OWNER N18      GROUP                       MODE PROD    RUNTSEC     
  THRESHOLD 000000010                                                 
  DESCRIPTION                                                         
   ==================================================================
  DO COND     = JOBNX-ARRIVED        ODAT +                           
  DO                                                                  
  ===================================================================
======= >>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<<< ====
=====FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF         13.21.53