Rule Parameters

This chapter contains the following topics:

• Overview

• Working With Control-O Rules

• Parameter Descriptions

• CONFCAL: Basic Scheduling Parameter

• CONTINUE SEARCH: Runtime Scheduling Parameter

• DATES: Basic Scheduling Parameter

• DAYS: Basic Scheduling Parameter

• DESCRIPTION: General Parameter

• DO statement: Automated Console Action Parameter

• DO ASKOPER: Automated Console Action Parameter

• DO COMMAND: Automated Console Action Parameter

• DO COND: Automated Console Action Parameter

• DO CTD REQ: Automated Console Action Parameter

• DO CTOPCMSG: Automated Console Action Parameter

• DO DISPLAY: Automated Console Action Parameter

• DO DOM: Automated Console Action Parameter

• DO ENDMSG: Automated Console Action Parameter

• DO EXIT: Automated Console Action Parameter

• DO FORCEJOB: Automated Console Action Parameter

• DO IF / DO ELSE / DO ENDIF: Automated Console Action Parameter

• DO KSL: Automated Console Action Parameter

• DO RESOURCE: Automated Console Action Parameter

• DO RETURN: Automated Console Action Parameter

• DO EXIT: Automated Console Action Parameter

• DO SET: Automated Console Action Parameter

• DO SHELL: Automated Console Action Parameter

• DO SHOUT: Automated Console Action Parameter

• DO SMSCLASS: Automated Console Action Parameter

• DO SMSMSG: Automated Console Action Parameter

• DO SNMP: Automated Console Action Parameter

• DO STOPJOB: Automated Console Action Parameter

• DO SYSREQ: Automated Console Action Parameter

• DO TERMINAT: Automated Console Action Parameter

• DO TSO: Automated Console Action Parameter

• DO WAIT: Automated Console Action Parameter

• DO WHILE / DO ENDWHILE: Automated Console Action Parameter

• ENVIRONMENT: Basic Scheduling Parameter

• GROUP: General Parameter

• IN: Runtime Scheduling Parameter

• INTERVAL: Runtime Scheduling Parameter

• MODE: General Parameter

• MONTHS: Basic Scheduling Parameter

• ON Statement: Message/Event Selection Parameter

• ON AOREQ: Message/Event Selection Parameter

• ON COMMAND: Message/Event Selection Parameter

• ON CTOPCMSG: Message/Event Selection Parameter

• ON DSNEVENT: Message/Event Selection Parameter

• ON EVENT: Message/Event Selection Parameter

• ON JOBARRIV: Message/Event Selection Parameter

• ON JOBEND: Message/Event Selection Parameter

• ON MESSAGE: Message/Event Selection Parameter

• ON MVALARM: Message/Event Selection Parameter

• ON OMEGAEXP: Message/Event Selection Parameter

• ON RULE: Message/Event Selection Parameter

• ON SMS: Message/Event Selection Parameter

• ON STEP: Message/Event Selection Parameter

• ON STRING: Message/Event Selection Parameter

• ON SYSOUT: General Parameter

• OWNER: General Parameter

• PRIORITY: Runtime Scheduling Parameter

• RUNTSEC: General Parameter

• THRESHOLD: Runtime Scheduling Parameter

• TIME: Runtime Scheduling Parameter

• WDAYS: Basic Scheduling Parameter

Overview

The selection criteria and instructions defined in each Control-O rule are called rule parameters. This chapter is comprised of detailed descriptions of all the rule definition parameters and their specific uses. Rule parameters are defined in the Rule Definition screen, which is shown in Figure 94, the main screen of the Rule Definition facility.

Figure 94 Rule Definition Screen

RL: $HASP100   LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = $HASP100
     JNAME PROD*    JTYPE J       SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER SYS3     GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION JES2 JOB ON RDR MESSAGE SUPPRESSION
  DESCRIPTION
  ===========================================================================
  /* SUPPRESS THE MESSAGE
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
  SYSTEM
  =========================================================================== 
                            D O   O P T I O N S                               
   Askoper  - Ask operator             COMmand  - Issue operator command      
   CONd     - Add/delete IOA condition CTD req  - O/F CONTROl-D mission       
   CTOPcmsg - Message to CONTROL-O/PC  DISplay  - Message / Command control   
   DOm      - Delete operator messag   FOrcejob - Force job under CONTROL-M   
   Ksl      - Activate a KOA script    RESource - Change IOA resources        
   RUle     - Call another RULE        SEt      - Set CONTROL-O/IOA variable  
   SHEll    - Run a z/OS shell script  SHout    - Notification facility       
   SMSClass - Set a new SMS class      SMSMsg   - Issue message by SMS ACS    
   SNmp     - Send SNMP Trap message   STopjob  - Stop next job steps         
   SYsreq   - System request           Tso      - Activate TSO command        
   WAit     - Completion of events     >        - Open a new DO line          
   /* -PF16 - Add comment line         />       - Comment/Uncomment "DO"      
   If / ELse / ENDIf / ENDMsg / WHile / ENDWhile - Logical instructions       
   EXit / RETurn / TERminat                      - End Process Instructions   
  =========================================================================== 
  DAYS                                                          DCAL
 AND/OR
  WDAYS   ALL                                                   WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ===========================================================================
  IN
  TIME FROM      UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y
======= >>>>>>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<<<<<< =====
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  06.44.34

BMC recommends that all Control-O users read the description of the Online Rule Definition facility in Rule Definition Facility before reading this chapter.

All parameter definitions are stored as members in standard user libraries. The Control-O term for a member of this type is "table." Each table is composed of parameters for a number of different rules, all of which usually relate to the same subject. Maintenance of tables in the library and management of rules in each table is performed using the Online Rule Definition facility.

Rule definition parameters fall into the following basic categories:

• Message/Event Selection Parameters – selection conditions (see the ON MESSAGE parameter in Figure 94 Rule Definition Screen). Mandatory.

• General Parameters – general information (see the parameters from OWNER through DESCRIPTION in Figure 94 Rule Definition Screen). Optional.

• Automated Console Action Parameters – actions to be performed (see DO OPTIONS in Figure 94 Rule Definition Screen). Mandatory.

• Basic Scheduling Parameters – dates to activate Control-O environment and rules (see the parameters from DAYS through ENVIRONMENT in Figure 94 Rule Definition Screen. Optional.

• Runtime Scheduling Parameters – runtime conditions (see the IN and TIME parameters in Figure 94 Rule Definition Screen). Optional.

The following pages contain a quick summary of the parameters in each of these categories. Following this summary is a series of sample rules that demonstrate how basic tasks are accomplished.

The last (and largest) portion of this chapter contains detailed descriptions of all rule definition parameters (in alphabetical order).

Message/Event Selection Parameters – Summary

Message/Event Selection parameters (ON parameters) specify conditions under which actions are to be performed by Control-O. Valid ON parameters are shown in Table 112.

Table 111 Message/Event Selection Parameters (ON Parameters)

When you specify an ON parameter and press Enter, the subparameters for this ON parameter are displayed. The combination of an ON parameter and its subparameters is called an ON statement.

Multiple ON statements can be specified in a rule. The And/Or/Not conjunctional parameter is used to link two or more ON statements.

For a general explanation of message and event selection parameters, see ON Statement: Message/Event Selection Parameter.

General Parameters – Summary

General parameters are used to provide general information about the rule and to determine the mode in which the rule is processed.

Table 112 General Parameters

Automated Console Action Parameters – Summary

Automated Console Action parameters specify actions to be performed by Control-O. These actions are performed only after conditions specified in the Message/Event Selection parameters have been fulfilled. Note that the Boolean "IF" logic capabilities are provided using the DO IF, DO ELSE, or DO ENDIF statements. Repetition logic is provided using the DO WHILE or DO ENDWHILE statements.

The Automated Console Action parameters are shown in Table 113.

Table 113 Automated Console Action Parameters

For a general explanation of automated console action parameters, see DO statement: Automated Console Action Parameter.

Basic Scheduling Parameters – Summary

Control-O Basic Scheduling parameters specify on what dates a rule is to be ordered.

When a rule is ordered, it is placed in the active Rule list. Once ordered, a rule is activated only when its Runtime Scheduling criteria are fulfilled.

There are several different Basic Scheduling parameters (and subparameters), each allowing a different method of specifying a schedule for a rule. Each rule definition can use any one or several of these parameters, depending on scheduling requirements.

The Basic Scheduling parameters are shown in Table 114.

Table 114 Basic Scheduling Parameters

Each Basic Scheduling parameter is described in detail later in this chapter. The interrelationships between some of these parameters are described briefly below.

DAYS/DCAL WDAYS/WCAL

These parameters are all optional.

The DAYS parameter identifies the days of the month when the rule should be scheduled. For example, the first day of the month, third working day of the month, and so on. Several formats are available for specifying DAYS values.

The WDAYS parameter identifies days of the week when the rule should be scheduled. For example, the first day of the week, the second day of each week, and so on. Several formats are available for specifying WDAYS values.

A calendar name can be specified in the DCAL and/or WCAL fields. A calendar specifies days of the year on which a rule can be scheduled, known as working days. For more information on calendars and the IOA Calendar Facility, see IOA Calendar Facility.

When both the DAYS and DCAL parameters are specified, a date must satisfy both parameter specifications, to result in rule scheduling.

Similarly, when both WDAYS and WCAL are specified, a date must satisfy both parameter specifications, to result in rule scheduling.

When values for both DAYS (/DCAL) and WDAYS (/WCAL) are specified in the same rule definition, the resulting schedule is determined by the value specified in field AND/OR.

CONFCAL/SHIFT

A calendar specified in CONFCAL is not used for rule scheduling, but is used instead for validating a schedule date. Only rules that have satisfied all other specified basic scheduling criteria are checked against the CONFCAL calendar. If the day is a working day in the CONFCAL calendar, the rule is scheduled on that day. Otherwise, the rule is either shifted to (scheduled on) another day according to the value specified in the SHIFT parameter, or the rule is not scheduled (if no SHIFT value has been specified).

CONFCAL calendars are especially useful for handling holidays and other scheduling exceptions.

Defining a Schedule – Internal Scheduling Logic

When defining rule tables, it is useful to understand the IOA Scheduling facility logic that determines whether or not to order a rule on a specific day. This logic is described below.

1. SYSTEM and SMFID criteria (specified in the ENVIRONMENT statement) are checked. If these criteria are satisfied, the check continues with next step. If these criteria are not satisfied, the rule is not scheduled in the current system.

2. DAYS and DCAL parameters are checked independently and a first tentative scheduling date is chosen.

3. WDAYS and WCAL parameters are checked independently and a second tentative scheduling date is chosen.

4. A third tentative scheduling date is chosen based on the above two dates and the AND/OR value linking them.

   If DAYS/DCAL are not specified, this third temporary scheduling date is identical to the WDAYS/WCAL scheduling date. If WDAYS/WCAL are not specified, this third scheduling date is identical to the first scheduling date.

5. If CONFCAL/SHIFT are specified, this third scheduling date is adjusted according to the CONFCAL/SHIFT criteria.

6. The third scheduling decision (as adjusted, if necessary) becomes the final scheduling decision. The rule is scheduled if the final scheduling decision is compatible with the current working date.

ENVIRONMENT SMFID and SYSTEM

The SMFID and SYSTEM parameters determine the environments in which the rule can be scheduled. If no value is specified for either of these parameters, the rule can be scheduled on any system.

If values are specified for both SMFID and SYSTEM parameters these values have an OR relationship.

Runtime Scheduling Parameters – Summary

Control-O Runtime Scheduling parameters determine when a rule in the active Rule list is activated. When a rule is activated, that is, when its Runtime Scheduling parameters are satisfied, Control-O scans the environment for the occurrence of the messages or events specified in the ON statements of the rule. When the message and event criteria are satisfied, the rule is triggered, and the DO statements in the rule are performed. Only an activated rule can be a candidate for triggering.

Runtime Scheduling parameters are also used to specify rule operation mode, rule priority, and optionally, a group of rules to which the rule belongs. The Runtime Scheduling parameters are shown in Table 115.

Table 115 Runtime Scheduling Parameters

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.

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.

   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

     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.

Regular Allocation and Deallocation

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

• IEF283I

• IEF285I

• IEF287I

SMS Support

In the case of SMS-managed data sets, Control-O 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, Control-O treats the file as not new.

Generation Data Sets (GDG)

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

• IGD105I

• IGD107I

• IGD108I

• IGD17101

Control-O Support for FTP

Control-O actions can be triggered by the transfer of files by FTP products.

In order to enable Control-O 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 Control-O 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 Control-O 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.

Control-O 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, Control-O cannot react to that message. However, you can use Control-O rules to react to FTP product messages.

Control-O 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 Control-O DSNEVENT support for IBM FTP, the following occurs:

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

   CTO782I SUBSYSTEM REGISTERED WITH OPENEDITION INTERFACE

   CTO783I INITIALIZATION OF OPENEDITION ENVIRONMENT ENDED SUCCESSFULLY

   When Control-O initialization is complete, the CTO147I message is displayed. After this, Control-O 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 Control-O 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 Control-O rule must know at that stage which user will issue an FTP request.

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

Recovering lost dataset events from SMF

In case of a Control-O outage, BMC 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, and all other DO actions are commented in CTMEVRT with (*) Unsupported action - not executed.

In addition, certain rule statements, scheduling criteria, or missing IN conditions could prevent the execution of DO actions that CTMEVRT retrieves. The user should consider these factors while editing the CTMEVRT output. Such actions are commented as follows:

• Actions for rules that have scheduling criteria and/or IN conditions are commented with (!) Sched / IN conditions in the rule.

• Actions that have a preceding IF, WHILE, or TERMINAT statement are commented with (?) Conditional-IF/WHILE/TERM precedes.

The CTMEVRT utility uses SMF records written by z/OS and z/OS Communications Server to identify events that occurred during the Control-O outage. The user must specify the start and end times that define the approximate duration of the Control-O 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 Control-O 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

On January 30, at 11:36 A.M., after applying some maintenance on LPAR SYSA, Control-O stopped working. By 12:10 P.M. the problem was resolved and Control-O was brought back up.

Since the site has many incoming FTP datasets during the day, it was necessary to recover those events that are usually caught by Control-O (using DSNEVENT rules), but were lost during the Control-O outage.

Since batch work and FTP transfers were a little delayed around the outage time (11:36 A.M.), as they mostly run in a discretionary Service Class and the LPAR was highly utilized, the site estimated that jobs were denied CPU for no more than 2 minutes, and therefore set the delay duration to 2 minutes.

To make sure they recovered all the lost DSNEVENTs, the site did the following:

1. Issued a Switch SMF command in SYSA.

   The switch ensured that the SMF records from the outage period were written to a sequential dataset (probably a new generation of a GDG).

2. Submitted sample job CTMEVRT with the following input (making sure that both the INCLTIME SYSIN parameter and the DASMF DD allocations for the SMF generations cover the delay duration (2 minutes prior to the Control-O outage, 11:34 – 11:36) and the outage duration (11:36 – 12:10):

   Copy

   //DASMF    DD   DISP=SHR,DSN=SMF.SYSA(0)
   //              DISP=SHR,DSN=SMF.SYSA(-1)
   //              DISP=SHR,DSN=SMF.SYSA(-2)
   //SYSIN    DD   *                                                       
   INCLTIME=2016/01/30,11:34-2016/01/30,12:10                              
   SYSID=SYSA

After CTMEVRT successfully executed, the site reviewed the following DAEVENTS file output, the events list dataset CTMEVRT.EVENTS (DAEVENTS DD) containing the list of extracted DSNEVENTs:

*Date      Time     SIDC Data Set Name        JobName Disp RuleName       Actions
2016/01/30 11:34:14 MVS3 N FTP.FILE.INCOMING1 FTPUSER C    0001-PROD:FTP* DO COND FILE_INCOMING1 ODAT +
2016/01/30 11:34:14 MVS3 N FTP.FILE.INCOMING1 FTPUSER C    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.INCOMING2 FTPUSER C    0001-PROD:FTP* DO COND FILE_INCOMING2 ODAT +
2016/01/30 11:39:22 MVS3 Y FTP.FILE.INCOMING2 FTPUSER C    0001-PROD:FTP* DO FORCEJOB TABLE FTP JOB FTPA UFLOW N DATE ODAT LIBRARY PROD.JCL
2016/01/30 11:40:08 MVS3 Y FTP.FILE.INCOMING3 FTPUSER C    0001-PROD:FTP*?DO FORCEJOB TABLE FTP JOB FTPC UFLOW N DATE ODAT LIBRARY PROD.JCL  (?) Conditional - IF/WHILE/TERM precedes
2016/01/30 11:40:08 MVS3 Y FTP.FILE.INCOMING3 FTPUSER C    0001-PROD:FTP**DO RES      RESOURCE1           0004+                       (*) Unsupported action - not executed

By cross-referencing the extracted DSNEVENTs with the IOA Log, the site realized that the event from 11:34 A.M. (the cataloging of data set FTP.FILE.INCOMING1) was actually already fully handled by Control-O. Therefore, it was excluded from further processing by commenting it out.

Also, analyzing the IF statement in the rule referred to by 0001-PROD:FTP* in the RuleName column of CTMEVRT.EVENTS, the site came to the conclusion that the conditional action should be excluded from the run, as well.

The last line, with (*) Unsupported action - not executed informs the site that a DO RESOURCE action was missed, and the site should take care of this action beyond the limits of the CTMEVRT-CTMEVEX process. The line is removed.

This is how CTMEVRT.EVENTS looked after the change:

*Date      Time      SID  C Data Set Name      JobName Disp RuleName       Actions
*2016/01/30 11:34:14 MVS3 N FTP.FILE.INCOMING1 FTPUSER C    0001-PROD:FTP* DO COND FILE_INCOMING1 ODAT +
*2016/01/30 11:34:14 MVS3 N FTP.FILE.INCOMING1 FTPUSER C    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.INCOMING2 FTPUSER C    0001-PROD:FTP* DO COND FILE_INCOMING2 ODAT +
 2016/01/30 11:39:22 MVS3 Y FTP.FILE.INCOMING2 FTPUSER C    0001-PROD:FTP* DO FORCEJOB TABLE FTP JOB FTPA UFLOW N DATE ODAT LIBRARY PROD.JCL
*2016/01/30 11:40:08 MVS3 Y FTP.FILE.INCOMING3 FTPUSER C    0001-PROD:FTP* DO FORCEJOB TABLE FTP JOB FTPC UFLOW N DATE ODAT LIBRARY PROD.JCL  (?) Conditional - IF/WHILE/TERM precedes

After the site decided that the edited DAEVENTS file was appropriate, the site submitted the sample job CTMEVEX. The CTMEVEX utility converted the CTMEVRT.EVENTS (DAEVENTS DD) DO actions to commands, and because the user set the SIMULATE parameter to NO, executed them using IOACND and CTMJOB.

By reviewing DAPRINT for IOACND and SYSPRINT for CTMJOB the site ensured that all the DO actions (DO FORCEJOB or DO COND) were executed successfully. On successful completion, the DSNEVENTs that Control-O had missed during its outage had been recovered and their actions executed.

Working With Control-O Rules

This section provides a series of sample rules that demonstrate how you can use Control-O to automate tasks at your site. The rule definition parameters used in these rules are described in detail and are listed in alphabetical order following the sample rules.

The sample rules in this section are located in the TUTORIAL member of the Control-O RULES library.

Message Suppression

The example in Figure 95 demonstrates suppression of an MVS message.

Figure 95 Example of Message Suppression

ON MESSAGE  = IEA848I   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION SUPPRESSING A SIMPLE MESSAGE
DESCRIPTION Z/OS ABEND - NO DUMP PRODUCED FOR ABEND - SUPPRESSED
DESCRIPTION
===========================================================================
DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
SYSTEM

Explanation

ON MESSAGE  = IEA848I

specifies the message that will trigger this rule

DESCRIPTION

a free text description of the operation performed by the rule

DO DISPLAY = SUPPRESS Y

This DO statement indicates that the message that triggered the rule should be suppressed.

Suppressing a Multi-line Message

The example in Figure 96 demonstrates suppression of a multi-line message. For more information about multi-line messages, see ON MESSAGE: Message/Event Selection Parameter.

Figure 96 Example of a Multi-Line Message

ON MESSAGE  = IEA995I   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                           MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION SUPPRESSING A MULTI-LINE MESSAGE
DESCRIPTION Z/OS ABEND - SYMPTOM DUMP OUTPUT - SUPPRESSED
===========================================================================
DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
SYSTEM
ENDMSG

Explanation

The ENDMSG parameter indicates that all DO statements that precede it should be executed for each line of the multi-line message.

The ENDMSG parameter is necessary even if no DO statements follow it. If the ENDMSG parameter is not included in this rule, only the last line of the multi-line message is suppressed.

Reacting to Specific Message Content

The example in Figure 97 demonstrates how a rule can be designed to react to a specific message with specific content.

Figure 97 Example of Reacting to Specific Message Content

ON MESSAGE  = IST093I   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not A
ON STRING   = TSOM                                            COL 009 - 012
   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                          MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION REACTING TO A SIMPLE MESSAGE
DESCRIPTION TSO VTAM NODE ACTIVE - START TSO
===========================================================================
DO COMMAND = S TSO
WAIT          CONSOLEID    CONSOLE          SYSTEM
WAITMODE     N

Explanation

This rule combines two ON statements to determine when the rule is triggered: The IST093I message is detected and the string "TSOM" is found in the text of the message.

And/Or/Not A

indicates that the rule will only be triggered when both ON statements are true. When the IST093I message is detected and the string "TSOM" is found in the text of the message, it indicates that the VTAM TSO node has been activated, and TSO can be started.

DO COMMAND=S TSO

This DO statement performs the command necessary to start TSO.

Replying to a WTOR Message

The example in Figure 98 demonstrates how a rule can be designed to respond to a WTOR (write to operator with reply) message.

Figure 98 Example of Replying to a WTOR Message

ON MESSAGE  = IEF235D   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION REPLYING TO A WTOR MESSAGE
DESCRIPTION JOBNAME COPY WAITING FOR VOLUMES
===========================================================================
DO COMMAND  = R %%$REPLY,NOHOLD
   WAIT        CONSOLEID    CONSOLE          SYSTEM
   WAITMODE   N

Explanation

The DO COMMAND statement is used to respond to a WTOR message. The following is specified in the DO COMMAND statement:

R %%$REPLY,NOHOLD

In this statement

• R is an indication that this is a reply to a WTOR message.

• %%$REPLY is the system variable containing the reply number for the WTOR message that triggered the rule.

• NOHOLD is the text of the reply to the WTOR message.

Storing a Reply Number for Later Use

The example in Figure 99 demonstrates how the reply number for a WTOR message can be saved for use at a later time (for example, by another rule).

Figure 99 Example of Storing a Reply Number for Later Use

ON MESSAGE  = DFS996I   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                          MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION KEEPING THE REPLY NUMBER IN A GLOBAL AUTOEDIT VARIABLE
===========================================================================
DO SET      = %%IMS-REPLY = %%$REPLY                              GLOBAL  Y

Explanation

The %%$REPLY system variable contains the reply number of the WTOR message that triggered the rule. In this rule, the %%IMS-REPLY user-defined variable is used to store the reply number (by way of the DO SET statement) for use at a later time.

Notifying the System Programmer of a Problem

The example in Figure 100 demonstrates how Control-O can be used to notify appropriate individuals that a specific type of problem was detected.

Figure 100 Example of Notifying the System Programmer of a Problem

ON MESSAGE  = IEE365I   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION NOTIFYING THE SYSTEM PROGRAMMER OF A PROBLEM
DESCRIPTION SMF DATASET OR SYS1.PARMLIB COULD NOT BE OPENED
DESCRIPTION INFORM THE SYSPROG TSO USER AND CTO-PC
DESCRIPTION
===========================================================================
DO SHOUT    = TO TSO-SYSPROG       URGENCY R SYSTEM           CTO282I
   MESSAGE %%$MSG
DO CTOPCMSG = PAGE %%$MSG

Explanation

When the IEE365I message, which indicates that the SMF data set or SYS1.PARMLIB could not be opened, is detected, this rule is triggered:

DO SHOUT=TO TSO-SYSPROG

This statement sends a message to the specified destination. In this example the message that triggered the rule, indicated by the %%$MSG AutoEdit System variable, is forwarded to the system programmer.

TSO-SYSPROG can refer to one or more destinations, depending on the definition of this destination in the IOA Dynamic Destination Table. For more information, see the description of the IOA dynamic destination table in the IOA administration chapter of the INCONTROL for z/OS Administrator Guide.

DO CTOPCMSG=PAGE %%$MSG

The message that triggered this rule is also forwarded to Control-M/Links for Windows NT. Control-M/Links for Windows NT can then forward the message to the system programmer, for example, by using a paging device.

Issue a Command at Regular Intervals

The example in Figure 101 demonstrates how a specified command can be issued at regular intervals within a specified time period.

Figure 101 Example of Issuing a Command at Regular Intervals

ON EVENT    = HOURLYOWNER IOAADMIN GROUP                         MODE LOG     RUNTSEC
THRESHOLD
DESCRIPTION ISSUE A COMMAND ONCE EACH HOUR (BETWEEN 8.00-17.00)
===========================================================================
DO COMMAND  = D A,ALL
   WAIT        CONSOLEID    CONSOLE          SYSTEM
   WAITMODE   N
===========================================================================
IN
TIME FROM 0800 UNTIL 1700      INTERVAL 060  PRIORITY     CONTINUE SEARCH Y

Explanation

The Runtime scheduling criteria include the following statement, which limits execution of this rule to a specific time period, from 8am to 5pm.

TIME FROM 0800 UNTIL 1700      INTERVAL 060

The value specified for the INTERVAL subparameter indicates that this rule is triggered every sixty minutes during the time specified in the TIME parameter.

Execute a REXX Procedure in Response to a Job Abend

The example in Figure 102 demonstrates how a Control-O rule can respond to a detected message by activating a REXX procedure.

Figure 102 Example of Executing a REXX Procedure in Response to a Job Abend

ON MESSAGE  = IEF450I   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION JOB ABENDED - EXECUTE A REXX PROCEDURE
DESCRIPTION PASS THE JOBNAME AS A PARAMETER TO IT
===========================================================================
DO TSO      = MYREXX %%$JOBNAME
   WAITMODE   Y                                      TIMEOUT         STOP Y
   INITPROC                 SHARELOC N               IMMEDIATE N
IF       %%$TSORC NE 0
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE PROBLEMS WHILE EXECUTING REXX PROCEDURE MYREXX
ENDIF

Explanation

The appearance of the IEF450I message activates this rule that in turn activates the REXX procedure. This procedure can be used, for example, to open a ticket in a problem management product (such as NETMAN or INFOMAN).

The %%$JOBNAME system variable contains the name of the job that issued the message that triggered the rule.

DO TSO=MYREXX %%$JOBNAME

This statement activates the MYREXX REXX procedure and passes the value of the %%$JOBNAME system variable as an argument.

An IF statement checks the %%$TSORC system variable, which contains the return code of the REXX procedure.

If the return code is not 0, meaning that the procedure did not end OK, the operator is informed by a SHOUT message.

Thresholds for Repetitive Messages

Some messages appear frequently and only indicate a problem if they appear with more than the usual frequency. The example in Figure 103 demonstrates the handling of a message for which the number of occurrences exceeds a specified threshold.

Figure 103 Example of Thresholds for Repetitive Messages

ON MESSAGE  = $HASP263   JNAME PROD*    JTYPE J       SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED 006   TIMES IN 0003 MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION HANDLING A MESSAGE APPEARING REPETITIVELY
DESCRIPTION JES CHECKPOINT CONTENTION PROBLEM HANDLING
===========================================================================
DO SHOUT    = TO OPER2             URGENCY R SYSTEM           CTO282I
   MESSAGE JES CHECKPOINT CONTENTION PROBLEM - PLEASE CHECK

Explanation

The following threshold is specified in the ON MESSAGE statement:

APPEARED 006 TIMES IN 0003 MINUTES

This specification causes the rule to be triggered only when the specified message ($HASP263) is issued at least six times within a three minute time span.

The THRESHOLD parameter in the CTOPARM member also limits the number of times that a rule can be triggered in one interval.

If the THRESHOLD parameter of a rule is set to a value different from that set in the THRESHOLD parameter in the CTOPARM member, the value in the rule overrides the value set in CTOPARM.

If no value, or a value of 0, is set in the THRESHOLD parameter of a rule or the THRESHOLD parameter in CTOPARM, Control-O does not limit the number of times that the rule can be triggered.

Designing a While Loop

The example in Figure 104 demonstrates the structure of a WHILE loop in a Control-O rule.

Figure 104 WHILE Loop Structure

ON RULE     = LOOPRULEOWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION SAMPLE LOOP STRUCTURE USING WHILE/ENDWHILE
===========================================================================
DO SET      = %%A = 0                                             GLOBAL  N
WHILE    %%A LE# 10
DO SET      = %%A = %%A %%$PLUS 1                                 GLOBAL  N
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE DURING LOOP NUMBER: %%A
ENDWHILE

Explanation

The loop in this rule is for demonstration purposes only. A DO SET statement is used to set a user-defined variable to zero.

WHILE    %%A LE# 10

This WHILE statement indicates that if the %%A user-defined variable is less than (LE#) 10, the following statements should be performed.

DO SET=%%A=%%A %%$PLUS 1

The %%A user-defined variable is incremented by one.

DO SHOUT=TO=OPER 
MESSAGE DURING LOOP NUMBER: %%A

A SHOUT message notifies the operator as to what loop number the rule is now executing.

ENDWHILE

marks the end of the WHILE loop

Track CICS Region Statuses Using Prerequisite Conditions

The example in Figure 105 demonstrates how Control-O accesses a list of prerequisite conditions (stored in the IOA Conditions file) to indicate the status of various components, such as jobs, or started tasks, in the working environment.

Figure 105 Example of Tracking CICS Region Statuses Using Prerequisite Conditions

ON MESSAGE  = DFH1500   JNAME CICS*    JTYPE J       SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not A
ON STRING   = CONTROL IS BEING GIVEN TO CICS                  COL 022 - 051
   JNAME CICS*    JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED     TIMES IN      MINUTES                          And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION KEEP TRACK OF CICS REGIONS STATUSES VIA AN IOA CONDITION
===========================================================================
DO COND     = CTO-%%$JOBNAME-UP    STAT +

Explanation

When the DFH1500 message is detected and contains the string specified in the ON STRING statement (CONTROL IS BEING GIVEN TO CICS), this rule is triggered.

The JNAME field is used to specify the name of the job or started task that issued the message. In this case the value specified in the JNAME fields in both ON statements (CICS*) indicates that the rule is triggered whenever the specified message is issued from a CICS job or started task (region).

The DO COND statement is used to set a condition indicating whether or not the CICS region is up. The %%$JOBNAME system variable resolves to the name of the CICS region that issued the message. If, for example, the CICS region name is CICSTEST, the condition set in the DO COND statement is as follows:

DO COND=CTO-CICSTEST-UP    STAT +

As a result of this DO COND statement, the CTO-CICSTEST-UP condition is added to the IOA Conditions file.

Using this rule (and other rules that remove conditions that are no longer true) Control-O can track the status of different CICS regions, and IOA components (such as Control-O rules and Control-M jobs) can be activated based on whether a specific region is up or down.

Start Five Initiators and Inform Control-M

The example in Figure 106 is designed to start a specified number of initiators at a specified time, and to add the appropriate number of initiators to the corresponding Quantitative resource in the Control-M Resources file so that the initiators can be tracked by Control-M.

Figure 106 Example of Starting Five Initiators and Informing Control-M

ON EVENT    = INITSOWNER IOAADMIN GROUP                         MODE LOG    RUNTSEC
THRESHOLD
DESCRIPTION START 5 INITIATORS AND INFORM CONTROL-M
===========================================================================
DO COMMAND  = $SI16-20
   WAIT        CONSOLEID    CONSOLE          SYSTEM
   WAITMODE   N
DO RESOURCE = INITIATORS           0005 +
===========================================================================
IN
TIME FROM 1800 UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y

Explanation

TIME FROM 1800

This statement indicates a specific time when the rule is triggered (6 pm).

DO COMMAND=$SI16-20

starts the new initiators (numbered from 16 through 20).

The DO RESOURCE statement is used to update the quantity of the specified resource (initiators) listed in the Control-M Resources file. Control-M monitors this file and is therefore informed of the new available initiators.

Forcing a Control-M Job

The example in Figure 107 demonstrates how a Control-M job can be run in response to the detection of a specific message.

Figure 107 Example of Forcing a Control-M Job

ON MESSAGE  = $HASP050   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION FORCE A CONTROL-M JOB IN RESPONSE TO A MESSAGE
DESCRIPTION JES2 - RESOURCE SHORTAGE
===========================================================================
DO FORCEJOB = TABLE   JES2JOBS JOB SYSJES1   UFLOW N    DATE ODAT
              LIBRARY CTM.SCHEDULE

Explanation

When the $HASP050 message is detected this rule is triggered.

The DO FORCEJOB parameter forces Control-M to run the specified job as a response to this message. The table where the job is found, the job name, and the library where the job is found are indicated in the subparameters of this statement. DO FORCEJOB can only be used if Control-M is installed at your site.

Force a Control-M Job and Pass a Variable to It

The example in Figure 108 demonstrates how a Control-M job is forced and information is passed to the job using Global AutoEdit variables.

Figure 108 Example of Forcing a Control-M Job and Passing a Variable to It

ON MESSAGE  = $HASP050   JNAME          JTYPE         SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION FORCE A CONTROL-M JOB WHILE PASSING IT A VARIABLE
DESCRIPTION THE VARIABLE IS ACCESSED BY CONTROL-M BY USING THE
DESCRIPTION %%LIBSYM AND %%MEMSYM CONTROL-M AutoEdit STATEMENTS
===========================================================================
/* GET INFORMATION TO BE PASSED TO THE JOB
DO SET      = %%MYPARM = %%$SMFID                                 GLOBAL  Y
/* WRITE THE CONTENTS OF THE VARIABLE TO A MEMBER FOR LATER ACCESS BY
/* CONTROL-M. WAIT UNTIL MESSAGE CTO163I APPEARS
DO COMMAND  = F %%$CONTROLO,WRITEGLOBAL
   WAIT        CONSOLEID    CONSOLE          SYSTEM
   WAITMODE   Y             WAITRESP Y            TIMEOUT 0300 0001
   RESPMSG CTO163I
/* IF CTO163I APPEARS IN THE SPECIFIED TIME FRAME (5 MINUTES) FORCE A JOB
/* THE VARIABLE CAN BE ACCESSED BY CONTROL-M.
IF       %%$MSGID EQ CTO163I
DO FORCEJOB = TABLE   JES2JOBS JOB SYSJES1   UFLOW N    DATE ODAT
              LIBRARY CTM.SCHEDULE
ENDIF

Explanation

DO SET=%%MYPARM=%%$SMFID                        GLOBAL Y

This statement stores the SMFID of the CPU that issued this message in the %%MYPARM user variable. A value of Y (Yes) in the GLOBAL field indicates that this variable is stored as a Control-O Global variable.

DO COMMAND=F %%$CONTROLO,WRITEGLOBAL
 WAIT        CONSOLEID    CONSOLE          SYSTEM
 WAITMODE   Y WAITRESP Y TIMEOUT 0300 0001
 RESPMSG CTO163I

This operator command must be issued to ensure that the new Global variable is written in the Global member and is therefore accessible by Control-M.

Y is specified in the WAITMODE field to indicate that execution of the rule should be postponed for the number of seconds specified in the TIMEOUT field or until the message specified in the RESPMSG field is detected.

The CTO163I message indicates a successful execution of a WRITEGLOBAL command. When this message is detected, the Control-M job is able to access the Global variable defined in this rule (%%MYPARM).

IF       %%$MSGID EQ CTO163I
DO FORCEJOB=TABLE   JES2JOBS   JOB SYSJES1   UFLOW N    DATE ODAT
 LIBRARY CTM.SCHEDULE

The %%$MSGID system variable contains the ID of the message most recently detected. If the ID stored in this variable indicates that the above command was successfully performed, the Control-M job is forced.

Extracting Information From a Multi-line Message

The example in Figure 109 demonstrates extraction of information from a multi-line message using System variables set during multi-line message processing. SHOUT statements are used to display information about the multi-line message that triggered the rule.

Figure 109 Example of Extracting Information from a Multi-Line Message

ON MESSAGE  = IEA995I   JNAME CICS*    JTYPE J       SMFID        SYSTEM
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION GETTING INFORMATION FROM A MULTI-LINE MESSAGE
DESCRIPTION Z/OS ABEND - SYMPTOM DUMP OUTPUT MESSAGE
===========================================================================
/* ALL STATEMENTS PRECEEDING THE 'ENDMSG' ARE EXECUTED FOR EACH LINE
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE PROCESSING LINE NUMBER %%$LINES
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE THE LINE BEING PROCESSED IS %%$M*
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE THE FIRST WORD OF THE LINE BEING PROCESSED IS %%$W1 %%$M*
ENDMSG
/* ALL STATEMENTS AFTER THE 'ENDMSG' ARE EXECUTED AFTER ALL THE LINES
/* OF THE MULTI-LINE MESSAGE ARE PROCESSED
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE ALL THE LINES OF THE MESSAGE HAVE BEEN RECEIVED
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE THE TOTAL NUMBER OF SECONDARY LINES IS %%$LINES
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE THE MAJOR LINE IS %%$M0
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE THE FIRST WORD OF THE MAJOR LINE IS %%$W1 %%$M0
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE THE FIRST SECONDARY LINE IS %%$M1
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF              17.02.57

Explanation

It is unlikely that you would need to specify the number of SHOUT statements included in this rule. This rule is designed for demonstration purposes. Each SHOUT statement in this rule conveys different information about the multi-line message that triggered the rule.

Statements (in this case SHOUT statements) appearing before the ENDMSG parameter are performed for each line of the multi-line message. Statements appearing after (below) the ENDMSG parameter are performed only once, after all lines of the message have been processed.

System variables are used in this rule to refer to different parts of the message text (for example, %%W1 %%$M0), and to the position of a given line in the message (%%$LINES). For more information on the different System variables see System Variables.

Prevent the Starting of CICS When It Is Already Active

The example in Figure 110 demonstrates how a command can be suppressed when a specified condition is true.

Figure 110 Example of Preventing the Starting CICS when is it already Active

ON COMMAND  = START CICS   JNAME          JTYPE         SMFID        SYSTEM       USERID
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED     TIMES IN      MINUTES                          And/Or/Not
OWNER IOAADMIN GROUP                         MODE LOG     RUNTSEC
THRESHOLD
DESCRIPTION CICS IS ACTIVE - PREVENT STARTING IT
===========================================================================
DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
   SYSTEM
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE CICS IS ACTIVE - START SUPPRESSED
============================================================================
IN        CICS-UP              STAT
TIME FROM      UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y

Explanation

IN       CICS-UP

When the CICS-UP condition is present in the IOA Conditions file, the rule is activated, or ready to be triggered. This rule is triggered when the START CICS command is requested by the operator.

The following statement is used to suppress the requested command:

DO DISPLAY=SUPPRESS Y

The operator is then informed that the command was suppressed and is given the reason for suppression.

User-Defined Commands and Confirmation of a Command Request

The example in Figure 111 demonstrates how a rule is used to create user-defined operator commands. This example also demonstrates how a rule can ask for confirmation of a specified command.

Figure 111 Example of User-Defined Commands and Confirmation of a Command Request

ON COMMAND  = SHUTSYS   JNAME          JTYPE         SMFID        SYSTEM       USERID
   ROUTE          DESC          CONSOLEID    CONSOLE
   APPEARED     TIMES IN      MINUTES                          And/Or/Not
OWNER IOAADMIN GROUP                         MODE LOG     RUNTSEC
THRESHOLD
DESCRIPTION REQUESTING OPERATOR CONFIRMATION
===========================================================================
DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
   SYSTEM
DO ASKOPER  = ENTER "YES" TO CONFIRM SHUTSYS REQUEST, OTHER TO CANCEL
ROUTE       CONSOLEID    CONSOLE                          TIMEOUT 9999
IF       %%$RPLYTXT EQ YES
DO COND     = CTO-SHUTSYS-ISSUED   STAT +
ELSE
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE SHUTSYS REQUEST WAS CANCELED BY OPERATOR REQUEST
ENDIF

Explanation

ON COMMAND=SHUTSYS

This statement can be used to define new operator commands. When the operator requests the command specified in an ON COMMAND statement (in our example: SHUTSYS), the rule is triggered.

DO ASKOPER=...

The operator is asked to confirm (or reject) the command using a WTOR message.

The %%$RPLYTXT System variable contains the operator’s response to the DO ASKOPER message.

An IF condition is used to select the appropriate action dependent on the operator response (%%$RPLYTXT).

• If the operator confirmed the specified command, a condition is set (CTO-SHUTSYS-ISSUED). The addition of this condition then triggers another rule (through an IN CTO-SHUTSYS-ISSUED statement) or a set of rules that perform the relevant actions (such as, in this example, a system shutdown).

• If the operator rejected the command, a message is issued (using DO SHOUT) indicating that the command request was canceled.

Issue a Command and Analyze the Response

The example in Figure 112 demonstrates how a rule can issue a command and analyze the results of the command request.

Figure 112 Example of Issuing a Command and Analyzing the Response

ON EVENT    = EVERY10OWNER IOAADMIN GROUP                         MODE LOG     RUNTSEC
THRESHOLD
DESCRIPTION ISSUE A COMMAND AND GET ITS RESPONSE
===========================================================================
DO SET      = %%MYSTC = CICSTEST                                  GLOBAL  N
DO SET      = %%JSTAT = INACTIVE                                  GLOBAL  N
/* ALL STATEMENTS UP TO THE 'ENDMSG' ARE EXECUTED FOR EACH LINE
/* OF THE COMMAND'S RESPONSE
DO COMMAND  = D A,%%MYSTC
   WAIT        CONSOLEID    CONSOLE          SYSTEM
   WAITMODE   Y             WAITRESP Y            TIMEOUT
   RESPMSG
IF       %%$W2 %%$M* EQ %%MYSTC
DO SET      = %%JSTAT = ACTIVE                                    GLOBAL  N
ENDIF
DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
   SYSTEM
ENDMSG
/* ALL STATEMENTS AFTER THE 'ENDMSG' ARE EXECUTED AFTER ALL THE
/* LINES OF THE COMMAND RESPONSE WERE PROCESSED
IF       %%JSTAT NE ACTIVE
DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I
   MESSAGE %%MYSTC IS NOT ACTIVE - CHECK WHY
ENDIF
===========================================================================
DAYS                                                          DCAL
                                                   AND/OR
WDAYS   ALL                                                   WCAL
MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
DATES
CONFCAL          SHIFT
ENVIRONMENT SMFID      SYSTEM
===========================================================================
IN
TIME FROM      UNTIL           INTERVAL 010  PRIORITY     CONTINUE SEARCH Y
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF              17.02.57

Explanation

This rule checks the status of a specified job (CICSTEST) every ten minutes. If the job is not active, a message is sent to notify the operator of the problem. The rule works as follows:

ON EVENT...

Since ON EVENT is specified for the rule, the rule is triggered immediately when runtime criteria are met. The specified runtime criteria, a value of 010 specified for the INTERVAL parameter, indicates that the rule is triggered every ten minutes.

DO SET=%%MYSTC = CICSTEST
DO SET=%%JSTAT = INACTIVE

Two local variables are set using the above statements at the beginning of this rule:

• %%MYSTC – name of the job to be checked by this rule (CICSTEST)

• %%JSTAT – variable used to indicate job status
  Initially set to INACTIVE.

DO COMMAND=D A,%%MYSTC

The rule issues this command to obtain information on the job specified in the %%MYSTC variable (CICSTEST). If the name of the job is contained in the response to the command, it indicates that the specified job is active.

IF   %%$W2 %%$M* EQ %%MYSTC
DO SET=%%JSTAT = ACTIVE

This IF statement checks if the second word (%%$W2) in the current command response line (%%$M*) is the job name (%%MYSTC). If the second word in the current command response line is the job name (CICSTEST), the %%JSTAT variable is set to ACTIVE. Since the response to this command is usually more than one line, the ENDMSG parameter is specified to ensure that the IF statement is applied to each line of the command response.

IF   %%JSTAT NE ACTIVE
DO SHOUT =   = TO OPER              URGENCY R SYSTEM           CTO282I
 MESSAGE %%MYSTC IS NOT ACTIVE - CHECK WHY

When the last line of the command response is detected, this IF statement checks if the %%JSTAT user-defined variable now contains the value ACTIVE. If %%JSTAT does not contain the value ACTIVE, this indicates that the job name was not located in the command response and the operator is notified that the job is inactive.

Execute a KOA Script in a Special Server

The example in Figure 113 shows how a KOA script is run in a Special server and used to check whether or not CICS is responding.

Figure 113 Example of Executing a KOA Script in a Special Server

RL: CHCKCICS   LIB CTO.PROD.RULES                               TABLE: CICS
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
ON EVENT    = CHCKCICS
OWNER IOAADMIN  GROUP                         MODE LOG     RUNTSEC
THRESHOLD
DESCRIPTION EXECUTE A KOA SCRIPT TO CHECK WHETHER CICS IS RESPONDING
===========================================================================
DO KSL      = CICSKOA
   WAITMODE   Y                                      TIMEOUT         STOP Y
   INITPROC   CICSP1        SHARELOC N               IMMEDIATE N
IF       %%$KSLRC NE 0
DO SHOUT    = TO OPER              URGENCY R SYSTEM            CTO282I
   MESSAGE CICS PROD IS IN TROUBLE - PLEASE CHECK
ENDIF
============================================================================
DAYS                                                          DCAL
 AND/OR
WDAYS   ALL                                                   WCAL
MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
DATES
CONFCAL          SHIFT
ENVIRONMENT SMFID      SYSTEM
===========================================================================
IN
TIME FROM 0700 UNTIL 1800      INTERVAL 002  PRIORITY     CONTINUE SEARCH Y
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  06.44.34

Explanation

If it is important to you to know if CICS is responding at your site, a rule such as this one can help you track CICS response. This EVENT rule is triggered every two minutes (specified by the value set in the INTERVAL parameter) between the hours of 7 a.m. and 6 p.m. (specified by the FROM and TO parameters).

A KOA script is used to check whether or not CICS is responding:

DO KSL=CICSKOA

This statement activates the specified KOA script (CICSKOA).

INITPROC   CICP1

The INITPROC subparameter is used to specify a Special server where the KOA script should be run. Use of a Special server can reduce possible delays in script execution.

For more information about Control-O servers, see Control-O Servers.

An IF statement checks the %%$KSLRC System variable, which contains the return code of the KOA script.

If the return code is not 0 (meaning that the script did not end OK), the operator is informed by a SHOUT message.

Reacting to an Event in a Sysplex Environment

Messages are often sent to all members (systems) in the Sysplex environment. Control-O can react to a message originating in any system in the Sysplex environment.

To trigger a rule that responds to a message that originated in another system (or an event that sends out a corresponding message), specify a SYSTEM value in the ON statement (valid for ON JOBARRIV, ON JOBEND, ON MESSAGE, and ON STRING).

Figure 114 Example of Reacting to an Event in a Sysplex Environment

ON JOBEND   = CICS    JTYPE S   SMFID      SYSTEM MVS1  And/Or/Not
OWNER N25     GROUP                        MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION
===========================================================================
IF       %%$REISSUED  EQ  N
DO SHOUT    = TO OPER              URGENCY R SYSTEM         CTO282I
   MESSAGE CICS ON %%$SYSTEMNM IS DOWN
ELSE
DO COMMAND  = S CICS
   WAIT        SYSTEM             CONSOLE          CONSOLEID
   WAITMODE   N
   ENDIF

Explanation

The above rule is triggered when the CICS job is ended in the MVS1 system.

The %%$REISSUED System variable is used to determine whether or not the CICS job ended in the current system.

• If the job was ended on the current system, a message is sent to the operator indicating that CICS was ended.

• If CICS was ended in another system, CICS is started in the current system.

Performing an Action on Another System

Control-O DO statements that support communication can be sent to Control-O on other systems. A Control-O rule on one system can request that an action be performed by Control-O on a remote system.

If both Control-Os are active in the same Sysplex environment, the Sysplex communication function is used. If the Control-Os are active on systems connected by VTAM or TCP, Control-O will use IOAGATE for communication. For more information about IOAGATE, see the Control-O Communication step in the Control-O chapter of the INCONTROL for z/OS Installation Guide.

The target remote system can be specified as follows:

• For any DO statement that supports communication, the target remote system can be specified using the %%$COMMSYS reserved user-defined variable in a preceding DO SET statement.

• The following DO statements support communication (that is, this method applies to the following DO statements):

  • DO COMMAND

  • DO COND

  • DO DISPLAY

  • DO FORCEJOB

  • DO RESOURCE

  • DO RULE

  • DO SHOUT

• Several of the above DO statements have a SYSTEM subparameter. The target remote system can alternatively be specified in this subparameter. If a remote system is specified both through %%$COMMSYS in a preceding DO SET statement and through the SYSTEM subparameter, the specification in the SYSTEM subparameter takes precedence.

The following DO statements support communication by either %%$COMMSYS or the SYSTEM subparameter:

• DO COMMAND

• DO DISPLAY

• DO SHOUT

For information regarding %%$COMMSYS, see the description of the variable in Reserved User-Defined Variables.

ON JOBEND    = CICS       JTYPE S SMFID        SYSTEM                And/Or/Not
OWNER  N25      GROUP                             MODE PROD     RUNTSEC
THRESHOLD
DESCRIPTION
===========================================================================
DO COMMAND  = S CICS
   WAIT        CONSOLEID    CONSOLE          SYSTEM MVS1
   WAITMODE   Y             WAITRESP Y            TIMEOUT
   RESPMSG DFH*

DO COMMAND=S CICS 
WAIT        CONSOLEID    CONSOLE         SYSTEM MVS1

 WAITMODE   Y              WAITRESP Y           TIMEOUT
 RESPMSG DFH*

ON JOBEND   = CICS     JTYPE S SMFID      SYSTEM               And/Or/Not   
OWNER CICSADMN GROUP                         MODE PROD    RUNTSEC
   THRESHOLD
   DESCRIPTION WHEN CICS ENDS - FORCEJOB ON THE CONTROL-M ON THE
   DESCRIPTION ALTERNATE SYSTEM TO START CICS.
   DESCRIPTION
   ===========================================================================
   DO SET      = %%$COMMSYS=SYSBKUP                              GLOBAL  N
   DO FORCEJOB = TABLE   CICS     JOB CICSALT   UFLOW N    DATE ODAT
                 LIBRARY CTM.PROD.SHEDULE
   DO
   ===========================================================================

ON JOBEND=CICS

DO SET=%%$COMMSYS=SYSBKUP                              GLOBAL  N

DO FORCEJOB=TABLE   CICS       JOB CICSALT   UFLOW N    DATE ODAT
 LIBRARY CTM.PROD.SHEDULE

ON JOBEND    = CICS       JTYPE S SMFID        SYSTEM    And/Or/Not
   OWNER  CICSADMN      GROUP            MODE PROD     RUNTSEC
   THRESHOLD
   DESCRIPTION
   ===========================================================================
   DO SET      = %%$COMMSYS=%%SYSBKUP                              GLOBAL  N
   DO COMMAND  = S CICS
      WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT
      RESPMSG DFH*

ON JOBEND=CICS

DO SET=%%$COMMSYS=%%SYSBKUP                            GLOBAL  N

DO COMMAND=S CICS
 WAIT        CONSOLEID    CONSOLE         SYSTEM

WAITMODE   N              WAITRESP             TIMEOUT

Displaying the Contents of an AutoEdit Variable Database

The example in Figure 118 shows how the TUTSHOUT rule displays the contents of the TUTORIAL AutoEdit variable database.

Figure 118 Displaying the Contents of an AutoEdit Variable Database

 ON EVENT    = TUTSHOUT OWNER M88A     GROUP                         MODE LOG     RUNTSEC
   THRESHOLD                                                     
 DESCRIPTION RULE TO SHOUT THE TUTORIAL DATABASE                 
 DESCRIPTION                                                     
===================================================================
 DO SHOUT    = TO OPER            URGENCY R SYSTEM          CTO282I
 MESSAGE TUTSHOUT BEGUN                                           
 /*            *---------------------------------------------------
 /*            SET TUTORIAL AS THE DEFAULT DATABASE ACCESSED      
 /*            *---------------------------------------------------
 DO SET   = %%$GLOBAL = TUTORIAL                         GLOBAL  N
 /*          *----------------------------------------------------
 /*          SHOUT THE DATABASE                                   
 /*          *----------------------------------------------------
 DO SET   = %%I = 0                                      GLOBAL  N
 DO SET    = %%X = %%$DBCOUNT                            GLOBAL  N
 WHILE    %%I LT# %%X                                             
 DO SET   = %%I = %%I %%$PLUS 1                          GLOBAL  N
 DO SET   = %%$DBROW = %%I                               GLOBAL  N
 DO SHOUT = TO OPER              URGENCY R SYSTEM          CTO282I
 MESSAGE %%NAME %%TSOUSER %%TELEXT                                
 ENDWHILE                                                         
 DO                                                               

Explanation

Initialize a counter to the number of records in the TUTORIAL database:

DO SET=%%I = 0
DO SET=%%X = %%$DBCOUNT

For each record, use the DO SHOUT command to display the contents of each database column. The variable names in the MESSAGE line must match the database column names in the TUTORIAL database:

WHILE    %%I LT# %%X
.
.
DO SHOUT=TO OPER              URGENCY R SYSTEM          CTO282I
 MESSAGE %%NAME %%TSOUSER %%TELEXT
ENDWHILE

Parameter Descriptions

The following pages contain detailed descriptions of all parameters available in the Control-O 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 Control-O screen

• general information explaining the parameter and its usage

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

For more information on the Rule Definition facility, see Rule Definition Facility.

CONFCAL: Basic Scheduling Parameter

Specifies the name of a calendar that is used to confirm whether a rule, which should be scheduled on a specific day (according to other scheduling criteria), is scheduled on that day, shifted to another day, or not scheduled at all.

For more information, see also DAYS: Basic Scheduling Parameter, and WDAYS: Basic Scheduling Parameter.

Figure 119 CONFCAL Parameter Format

Optional. The CONFCAL subparameters are described in Table 116.   

Table 116 CONFCAL Subparameters

General Information

CONFCAL calendars are useful for handling holidays and other scheduling exceptions.

CONFCAL is optional. If not specified, rules are scheduled according to other basic scheduling criteria without confirmation.

CONFCAL should not contain the name of a periodic calendar. If it does, no day will pass the confirmation.

SHIFT cannot be specified unless CONFCAL is specified, and when CONFCAL is specified, SHIFT is optional (that is, a blank defaults to no shifting).

DAYS    - 1,7,15
AND/OR  - AND
WDAYS   - 6
CONFCAL - WORKDAYS
SHIFT   - >

CONTINUE SEARCH: Runtime Scheduling Parameter

Determines whether a search for additional rules that meet the selection criteria will continue.

Figure 121 CONTINUE SEARCH Parameter Format

Mandatory. Valid values are shown in Table 117.  

Table 117 CONTINUE SEARCH Values

RL: $HASP373   LIB CTO.PROD.RULES                               TABLE: SAMPLE
COMMAND ===>                                                    SCROLL===> CRSR
 -------------------------------------------------------------------------------
  ON MESSAGE  = $HASP373
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IAOADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION SUPPRESS JOB STARTED MESSAGE. CONTINUE SEARCH = Y
  DESCRIPTION ENABLES CONTROL-O TO SCAN OTHER RULES THAT MATCHE
  DESCRIPTION THE MESSAGE
  DESCRIPTION
============================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO
============================================================================
  DAYS                                                          DCAL
 AND/OR
  WDAYS   ALL                                                   WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
============================================================================
  IN
  TIME FROM      UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y
FILL IN RULE DEFINITION. CMDS: EDIT , SHPF , SCHED , OPT               10.55.26

DATES: Basic Scheduling Parameter

Specifies dates, by month and day, when the rule is ordered.

Figure 123 DATES Parameter Format

Optional. The DATES parameter specifies a valid 4-character date, in either mmdd or ddmm format, depending on site format.

A maximum of 12 dates can be specified.

General Information

The rule is ordered only on the dates specified in the dates list.

This parameter cannot be used with the MONTHS, DAYS and DCAL parameters.

To specify more than 12 dates for one rule, the dates should be defined in a calendar (not in the DATES parameter) and the calendar should be specified in the DCAL or WCAL parameter.

RL: START JO   LIB CTOW.WORKO.RULES                             TABLE: DATES
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = START JOB01*
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION SUPPRESS SOME COMMANDS ON SPECIAL DAYS
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE COMMAND %%$CMD CANNOT BE EXECUTED TODAY
  DO
  ===========================================================================
  DAYS                                                          DCAL
 AND/OR
  WDAYS                                                         WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES   0101 3112
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ===========================================================================
  IN
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  17.02.57

DAYS: Basic Scheduling Parameter

Specifies the days of the month when the rule should be scheduled for execution.

For more information, see WDAYS: Basic Scheduling Parameter, and CONFCAL: Basic Scheduling Parameter.

Figure 125 DAYS Parameter Format

Optional. The DAYS parameter specifies days of the month when the rule should be scheduled, provided other basic scheduling criteria are met. Values for DAYS can be specified by themselves, or they can be specified together with a calendar specified in the DCAL subparameter. DAYS and DCAL can also be specified together with WDAYS and WCAL, which are described under WDAYS: Basic Scheduling Parameter.

DAYS subparameters are shown in Table 118.

Table 118 DAYS Subparameters

Assuming all other basic scheduling criteria are met

• When DAYS are specified without DCAL, the rule is scheduled on the specified days (in the specified months).

• When DCAL is specified without DAYS, the rule is scheduled on all working days marked in the DCAL calendar.

• When DAYS and DCAL are both specified, scheduling depends on the how the working days defined in the calendar and the values and format of the DAYS parameter combine (described below).

• When both DAYS and WDAYS criteria are specified, scheduling depends on the AND/OR subparameter connecting them.

Valid Formats for DAYS

Valid formats for the DAYS parameter, and how they relate to DCAL, are described in the following paragraphs.

Non-periodic Scheduling Formats

In the non-periodic scheduling formats listed in Table 119

• n is an integer from 1 through 31

• multiple values can be specified (separated by commas) in any order

• a calendar name specified for DCAL should not designate a periodic calendar

Table 119 Non-Periodic Scheduling Formats

Periodic Scheduling Formats ctoug3004

In the periodic scheduling formats listed in Table 120

• an * can be specified as the i value to represent all periods

• an * can be specified as the n value in format DnPi to represent all days
  * is not a valid n value in formats –DnPi, LnPi, and –LnPi.

• a period can span any number of days, but by default, no more than 33 days can elapse after the appearance of one identifier in a period until the appearance of the next matching identifier in the same period
  Once a gap of 33 days has been reached, the period automatically closes. The INCONTROL administrator can change the 33-day default.

The name of a periodic calendar must be specified in DCAL.

Table 120 Periodic Scheduling Formats

General Information

Negative values take precedence over positive values when determining whether or not a rule should be scheduled on a certain date. If a negative value (that is, format –n, –Dn, –Ln, –DnPi, or –LnPi) in either the DAYS or WDAYS field prevents a rule from being scheduled on a date, the rule will not be scheduled on that date even if a positive value (for example, Ln) would otherwise result in the rule being scheduled on that date.

A maximum of eight periodic values of the DnPi, –DnPi, LnPi, and –LnPi types can be designated in any desired order.

If periodic and non-periodic values are mixed when specifying the DAYS parameter, processing will depend on the calendar type specified in the DCAL parameter.

• If a non-periodic calendar is specified in the DCAL parameter, only non-periodic values in the DAYS parameter are processed; periodic values are ignored. In this case, negative periodic values (that is, –DnPi, –LnPi) are also ignored, and do not supersede other values.

• If a periodic calendar is specified in the DCAL parameter, all periodic values and the negative non-periodic value -n in the DAYS parameter are processed; all other non-periodic values are ignored.

The MONTHS parameter is ignored when periodic values are specified in the DAYS parameter.

The DAYS parameter cannot be used with the DATES parameter.

Examples

The examples for this parameter are based on the following assumptions:

• The current month is December 2001.

• Working days are defined in the WORKDAYS calendar, which contains the following working days (indicated by Y) for December 2001.

  Copy

  ---S-------------S-------------S-------------S-------------S--- 
  1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1
       Y Y Y Y Y     Y Y Y Y Y     Y Y Y Y Y     Y   Y Y Y     Y

• WDAYS are defined as working days beginning on Monday.

• The PERIDAYS periodic calendar contains the following periodic definition for December 2001. These examples assume that all other days of this calendar are blank.

  Copy

  ---S-------------S-------------S-------------S-------------S--- 
  1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1
       B C A A B     B C A A B     B C A A B     B C A A B     B

• Start of the week is defined as Monday. Weeks start on the following dates in December 2001: 3rd, 10th, 17th, 24th, and 31st.

At the end of each example, asterisks in a December 2001 calendar indicate the days when the rule is scheduled.

DAYS    - 17,L01

DAYS    - +1,-
6DCAL    - WORKDAYS

DAYS    - -D1,-17,-L1
DCAL    - WORKDAYS

DAYS    - <8
DCAL    - WORKDAYS

DAYS    - -5,D1PA,-D2PB
DCAL    - PERIDAYS

DAYS    - 1
AND/OR  - OR
WDAYS   - 1

DAYS    - 3
AND/OR  - AND
WDAYS   - 1

DAYS    - L1,L2,L3,L4,L5,L6,L7
AND/OR  - AND
WDAYS   - 1

DAYS    - 1,7,15
AND/OR  - AND
WDAYS   - 6
CONFCAL - WORKDAYS
SHIFT   - >

DAYS     16,17,18,19,20,21,22
AND/OR   AND
WDAYS    5

DESCRIPTION: General Parameter

Description of the rule definition (in free text).

Figure 136 DESCRIPTION Parameter Format

Optional. This parameter may consist of one or more lines of free text. After you have filled in one line, a new blank line is automatically displayed.

General Information

The DESCRIPTION parameter does not operate as a selection parameter. It serves as internal documentation to aid in the identification and description of individual rules.

The first line of the rule description appears as the description of the rule in the Rule List screen, and the first 20 characters of the description are displayed in the Rule Status screen. It is therefore advisable to place the most important information at the beginning of the rule description.

Text for the DESCRIPTION parameter can be specified in any language.

RL: SHUTSYS    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = SHUTSYS
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION A NEW COMMAND TO SHUTDOWN THE SYSTEM
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO COMMAND  = $PI
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  DO COMMAND  = $PPRT
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  DO SHOUT    = TO OPER2             URGENCY R SYSTEM           CTO282I
     MESSAGE SYSTEM IS BEING SHUT DOWN
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF               18.46.46

DO statement: Automated Console Action Parameter

Actions taken when ON message or event criteria are satisfied.

Figure 138 DO Parameter Format

Optional. Specify DO statements as follows:

• Type the action keyword (for example, COND) in the DO field and press Enter.

• In many cases, subparameter fields are displayed. Fill in the subparameters and press Enter again.

After entering a DO statement, another DO line is automatically displayed. Multiple DO statements can be specified.

Table 121 shows valid DO actions. Each is discussed individually later in this chapter.

Table 121 DO Actions

General Information

DO statements specify actions to be performed when the rule is triggered.

DO statements can be performed repetitively, or conditionally, or both repetitively and conditionally, for example, by using DO IF or DO WHILE statements, which are described in DO IF / DO ELSE / DO ENDIF: Automated Console Action Parameter and DO WHILE / DO ENDWHILE: Automated Console Action Parameter respectively.

Whenever a DO statement is specified, an empty DO statement is added after it. This allows specification of an unlimited number of DO statements.

To add an empty DO statement between two existing DO statements, type the > character over the first letter in the DO field of the earlier DO statement, and press Enter.

DO >OMMAND

DO ASKOPER: Automated Console Action Parameter

Issues a WTOR (Write to Operator With Reply) message, and waits for the operator’s reply.

Figure 139 DO ASKOPER Parameter Format

Optional. Type ASKOPER in the DO field and press Enter. The subparameters shown in Table 122 are displayed.

Table 122 DO ASKOPER Subparameters

General Information

When the rule resumes execution after DO ASKOPER, the %%$ASKRC AutoEdit System variable indicates which event caused the end of the wait. Possible values for %%$ASKRC are shown in Table 123.

Table 123 Values passed to %%$ASKRC by DO ASKOPER Parameter

RL: SHUTTSO    LIB CTO.PROD.RULES                               TABLE: TEST1
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = SHUTTSO
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE TSO IS BEING SHUT DOWN. SHIFT SUPERVISOR MUST BE NOTIFIED.
  DO SET      = %%RC = 4                                            GLOBAL  N
  WHILE    %%RC NE# 0
  DO ASKOPER  = HAVE YOU NOTIFIED SHIFT SUPERVISOR ? REPLY 'YES' OR 'CANCEL'
       ROUTE      CONSOLEID    CONSOLE                          TIMEOUT 0030
  IF       (%%$ASKRC EQ# 4) AND ((%%$RPLYTXT EQ YES) OR (%%$RPLYTXT EQ CANCEL))
  DO SET      = %%RC = 0                                            GLOBAL  N
  ENDIF
  ENDWHILE
  IF       %%$RPLYTXT EQ YES
  DO COMMAND  = P TSO
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  18.46.46

DO COMMAND: Automated Console Action Parameter

Specifies an operator command to be issued.

Figure 141 DO COMMAND Parameter Format

Optional. Type COMMAND in the DO field and press Enter. The subparameters shown in Table 124 are displayed:

Table 124 DO COMMAND Subparameters

General Information

This parameter issues operator commands, and VM/CP commands if z/OS is operating under VM.

Control-O AutoEdit variables embedded in the DO COMMAND parameter are automatically resolved (replaced) at time of rule activation. For more information about the AutoEdit facility, see AutoEdit Facility.

After the AutoEdit variables are resolved, the Control-O DO COMMAND issues the command as is (with the resolved values of the AutoEdit). The z/OS SYMBOLS are passed as is and are resolved by the system directly. Control-O is not involved in this process, and the values are passed as received. The Control-O DO COMMAND supports z/OS SYMBOLS, SYSTEM SYMBOLS, and user-defined SYMBOLS.

Issuing a Command

The manner in which a command is issued depends on the values of the RUNTSEC runtime scheduling parameter or the WAIT DO COMMAND subparameter.

If runtime security is active for a rule (the RUNTSEC subparameter set to OWNER or TRIGGER), the operator commands issued by a DO COMMAND will always be issued by the Control-O monitor and not under the same address space of the command that triggered the rule.

If a WAIT value is not specified, the command is issued immediately under the same address space of the message or command that triggered the rule. If a WAIT value is specified, even a value of 0, the command is issued by the Control-O monitor after the specified interval. However, the WAIT subparameter applies only to its DO COMMAND parameter, and any subsequent DO statements are performed immediately without regard to the WAIT value.

Command-Response Mode

A rule containing a DO COMMAND statement can be executed in command-response mode. In this mode, messages issued in response to an operator command can be intercepted by Control-O in the same rule that issued the command, and additional actions can be taken depending on these messages.

Control-O can intercept these messages by one or more of the following methods:

• using the z/OS subsystem console mechanism

• using the extended MCS console mechanism

• looking for specific message IDs

When the rule resumes execution after DO COMMAND, the %%$WAITRC system variable indicates the type of event that caused the end of the wait. Valid values for %%$WAITRC are shown in Table 125.

Table 125 Values passed to %%$WAITRC by DO COMMAND Parameter

Specifying Command-Response Mode

A rule is placed in command-response mode by typing Y (Yes) in the WAITMODE field. The following subparameters determine the methods used by Control-O to intercept messages:

• WAITRESP
  When Y (Yes) is specified, this parameter instructs Control-O to utilize the z/OS subsystem console mechanism. Control-O issues the command on a subsystem console and retrieves all messages issued to the same console in response. Since some products issue response messages without regard to the originating console, this parameter should be used only when the response messages are sent to the originating console. This parameter should not be used if there are no subsystem consoles defined to Control-O.

  The CONSOLEID parameter of the DO COMMAND is ignored when using this method because Control-O selects the console internally.

• RESPMSG msgid1msgid2...msgid5
  This parameter instructs Control-O to intercept only messages having the specified messageIDs. Up to five messageIDs can be specified.

  This parameter should be used without setting WAITRESP toY if the response messages could be issued to a console other than the originating console, or if no subsystem consoles have been defined to Control-O.

  This parameter should be specified together with WAITRESP set toY when all response messages are issued to the originating console and it is desirable to limit message interception to a few (up to five) specified message IDs.

The WAITRESP and RESPMSG parameters can also be specified for VM/CP commands, if z/OS is operating under VM.

The TIMEOUT parameter indicates how long to wait for responses before continuing to the next DO statements. TIMEOUT values are optional.

Processing the Command Response

When a rule is executing in command-response mode, that is, when WAITMODE is set to Y in a DO COMMAND statement, Control-O suspends rule execution until either the specified time-out is reached, or a last line (the last line of a multi-line message) is detected.

A command response can consist of several different combinations of messages:

• multiple regular, that is, not multi-line, messages
  No last line is supplied, and command-response mode will remain in effect until the specified time-out is reached.

  When Wish O10261 is enabled, a regular message is treated as a last line. Command-response mode is terminated when the first regular message is detected.

• a single multi-line message
  The last line supplied in the command response is the actual last line of the response. Command-response mode is terminated when this last line is detected.

• multiple multi-line messages
  The command response will contain more than one last line. Command-response mode is terminated when the first last line is detected. To avoid termination of command-response mode, use a %%$MLLEND control statement to disable the search for the last line. For more information on the %%$MLLEND control statement, see AutoEdit Facility.

Performing DO Statements in Command-Response Mode

It may be desirable to perform a set of DO statements each time an individual response message is intercepted. It may be desirable to accumulate all intercepted response messages and then perform a set of DO statements once. The exact way DO statements are performed is determined by their position relative to the DO ENDMSG statement:

• All DO statements preceding the ENDMSG statement are performed each time an individual message is intercepted. It should also be noted that within these DO statements, the current message can be referenced using the %%M* System variable.

• All DO statements following the ENDMSG statement are performed only once – after accumulation of all intercepted messages. It should also be noted that within these DO statements, individual messages within the accumulation can be referenced using the %%Mn System variable.

• To avoid recursion, Control-O does not intercept commands issued by a DO COMMAND statement unless the WAIT DO COMMAND subparameter is specified (that is, as long as it is not blank), or OWNER or TRIGGER has been specified for the RUNTSEC subparameter.

• When a command issued by Control-O should trigger another ON COMMAND rule, a WAIT value should be specified for the DO COMMAND so that Control-O can intercept the command. Even a value of0 enables interception of the DO COMMAND by Control-O.

RL: $HASP479   LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = $HASP479
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not A
  ON STRING   = REPLY                                           COL 065 - 090
     JNAME CICS*    JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION REPLY TO MSG 'UNABLE TO OBTAIN CKPT LOCK'
  DESCRIPTION
  ===========================================================================
  DO COMMAND  = R %%REPLY,Y
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  14.35.47

RL: IST020I    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = IST020I
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION VTAM INITIALIZATION COMPLETE
  DESCRIPTION START TSO AND CICS REGIONS AFTER VTAM WAS INITIALIZED
  DESCRIPTION
  ===========================================================================
  DO COMMAND  = S TSO
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  DO COMMAND  = S CICSPROD
     WAIT        CONSOLEID    CONSOLE          SYSTEM
      WAITMODE   N
  DO COMMAND  = S CICSTEST
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  14.38.00

RL: SPOOLCHK   LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON EVENT    = SPOOLCHK
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION CHECK SPOOL UTILIZATION
  DESCRIPTION
  ===========================================================================
  DO COMMAND  = $DSPL
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT
     RESPMSG
  ENDMSG
  DO SET      = %%A = %%$W2 %%$M1                                     GLOBAL  N
  IF       %%A GT# 60
  DO COND     = SPOOL-OVERLOADED     STAT +
  ELSE
  DO COND     = SPOOL-OVERLOADED     STAT -
  ENDIF
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  15.17.16

RL: CHKACT*    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = CHKACT*
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION CHECK IF A SPECIFIC JOB IS ACTIVE
  DESCRIPTION
  ===========================================================================
  DO SET      = %%JSTAT = INACTIVE                                  GLOBAL  N
  DO COMMAND  = D A,%%V2
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT
     RESPMSG
  IF       %%$W2 %%$M* EQ %%$V2
  DO SET      = %%JSTAT = ACTIVE                                    GLOBAL  N
  ENDIF
  DO DISPLAY  = SUPPRESS A ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
      NEWTEXT
  ENDMSG
  DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I
     MESSAGE JOB %%$V2 IS %%JSTAT
  DO
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  15.26.53

RL: CHECK      LIB CTO.PROD.RULES                               TABLE: TEST1
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON EVENT    = CHECK
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION ISSUE A MODIFY COMMAND to CICS. ISSUE WARNING IF NO RESPONSE.
  DESCRIPTION
  ===========================================================================
  DO COMMAND  = F CICS,CEMT I
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT 0240 0010
    RESPMSG MESSAGE1
  IF       %%$LINES EQ# 0
  DO SHOUT    = TO TSO-SYSMGR        URGENCY R SYSTEM                     CTO282I
     MESSAGE CICS DOES NOT REPLY TO COMMANDS
  ENDIF
  DO
===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  15.17.16

DO COND: Automated Console Action Parameter

Specifies prerequisite conditions to be added or deleted.

Figure 142 DO COND Parameter Format

Optional. Type COND in the DO field and press Enter. The subparameters shown in Table 126 are displayed.

Table 126 DO COND Subparameters

General Information

When a DO COND statement is specified and the rule is activated, the designated prerequisite conditions are added or deleted from the IOA Conditions file according to the option specified.

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

IMS-ACTIVE
WEEKEND
SALARY-OK

Prerequisite conditions created or deleted using a DO COND statement can trigger (or stop) the activation of other rules, or the execution of processes in Control-M, Control-D and other environments.

Control-O AutoEdit variables embedded in DO COND subparameters are resolved (replaced) at the time of rule activation. For more information about the AutoEdit facility, see AutoEdit Facility.

RL: IEF403I    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = IEF403I
     JNAME IMS1     JTYPE S       SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION NOTIFY CONTROL-M THAT IMS IS NOT DOWN
  DESCRIPTION
  ===========================================================================
  DO COND     = IMS1-IS-DOWN         STAT -
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

RL: DFS810A    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = DFS810A
     JNAME IMS1     JTYPE S       SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
  APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION INDICATE IMS1 IS ACTIVE (KEEP REPLY NUMBER + SIGNAL CONTROL-M)
  DESCRIPTION
  ==========================================================================
  DO COND     = IMS1-IS-ACTIVE       STAT +
  DO SET      = %%IMS1_REPLY = %%REPLY                              GLOBAL  Y
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

RL: IEF494I    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = IEF494I
     JNAME IMS1     JTYPE S       SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION NOTIFY CONTROL-M THAT IMS IS DOWN
  DESCRIPTION
  ===========================================================================
  DO COND     = IMS1-IS-DOWN         STAT  IMS1-IS-ACTIVE         STAT -
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

RL: IEF494I    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
 +-----------------------------------------------------------------------------+
 ON MESSAGE  = IEF494I
 JNAME IMS1     JTYPE S       SMFID        SYSTEM
 ROUTE          DESC          CONSOLEID    CONSOLE
 APPEARED       TIMES IN      MINUTES                        And/Or/Not
 OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
 DESCRIPTION NOTIFY CONTROL-M THAT IMS IS DOWN
 DESCRIPTION
 ===========================================================================
 DO COND     = IMS1-IS-DOWN         STAT ?
 DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I
 MESSAGE CONDSTAT = %%$CONDSTAT
 DO
 ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

DO CTD REQ: Automated Console Action Parameter

Orders or forces all types of Control-D missions.

Figure 143 DO CTD REQ Parameter Format

Optional. Type CTD REQ in the DO field and press Enter. The subparameters shown in Table 127 are displayed.

Table 127 DO CTD REQ Subparameters

General Information

Control-O AutoEdit variables embedded in the TABLE, CAT, DATE, and LIBRARY subparameters are automatically resolved (replaced) at the time of rule activation. For more information about the AutoEdit Facility, see AutoEdit Facility.

DO CTD REQ can schedule a report under Control-D even if the date is not specified as a scheduling date in the mission’s Basic Scheduling parameters. It is similar to the FORCE option in the Control-D Job List screen and Category List screen.

• If the Control-D monitor is active, the DO CTD REQ statement is executed by the Control-D monitor.

• If the Control-D monitor is not active, the DO CTD REQ statement is queued and is performed when the Control-D monitor becomes active.

• If Control-D is not installed, ordering a rule containing a DO CTD REQ statement fails with an error message.

A DO CTD REQ statement can be distributed to Control-O on a remote system that is identified by the %%$COMMSYS reserved user-defined variable in a preceding DO SET statement. For more information, see the description of %%$COMMSYS in Reserved User-Defined Variables, and Performing an Action on Another System.

RL: JOBEND     LIB CTO.PROD.RULES                             TABLE: JOB
COMMAND ===>                                                  SCROLL===>
ON JOBEND   = CICS*    JTYPE   SMFID      SYSTEM               And/Or/Not
OWNER N18B     GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION
===========================================================================
DO CTD REQ  = MISSION MIS1     CAT                      DATE ODAT   FORCE Y
              LIBRARY
DO CTD REQ  = MISSION MIS2     CAT                      DATE ODAT   FORCE N
             LIBRARY CTD.MISSIONS
DO
===========================================================================
DAYS                                                          DCAL
                                                                    AND/OR
WDAYS   ALL                                                   WCAL
MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
DATES
CONFCAL          SHIFT
ENVIRONMENT SMFID      SYSTEM
===========================================================================
IN
TIME FROM      UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y
===== >>>>>>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<<<<<< ===
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

DO CTOPCMSG: Automated Console Action Parameter

Specifies a message to be sent to Control-M/Links for Windows NT.

Figure 145 DO CTOPCMSG Parameter Format

Optional. Type CTOPCMSG in the DO field and press Enter. Type in the message text to be sent to Control-M/Links for Windows NT to the right of the = prompt.

General Information

The message text specified in a DO CTOPCMSG statement is sent to Control-M/Links for Windows NT. Syntax conventions of the message text are site-defined. The same syntax conventions should be used for both specifying the message in Control-O, and interpreting the message in Control-M/Links for Windows NT.

Control-O AutoEdit variables embedded in the specified message text are automatically resolved at time of rule activation. For more information about the AutoEdit facility, see AutoEdit Facility

RL: IEA000I    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = IEA000I
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION NON-CORRECTABLE I/O ERROR ON MVSRES (UNIT=230)
  DESCRIPTION PAGE THE SYSTEM PROGRAMMER FOR ASSISTANCE
  DESCRIPTION
  ===========================================================================
  IF       %%$V2
  DO SHOUT    = TO OPER2             URGENCY R SYSTEM          CTO282I
     MESSAGE NON-CORRECTABLE I/O ERR ON MVSRES (UNIT=230). PAGE TECH-SUPPORT
  DO CTOPCMSG = PAGE  SYSPROG  DATA-CHECK ON MVSRES (UNIT 230)
  ENDIF
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  15.45.09

DO DISPLAY: Automated Console Action Parameter

Controls the display of the message on the console or suppresses commands issued from the console.

Figure 147 DO DISPLAY Parameter Format

Optional. Type DISPLAY in the DO field and press Enter. The subparameters shown in Table 128 are displayed.

Table 128 DO DISPLAY Subparameters

General Information

The SUPPRESS subparameter allows suppression of messages that do not require operator intervention from the console and from the SYSLOG. This subparameter can also be used for operator command security – authorizing certain commands for certain environments.

Descriptor codes determine message display characteristics such as deletion, scrolling, highlighting or color. For additional information regarding routing and descriptor codes, refer to the IBM publication Routing and Descriptor Codes, GC38-1102.

The NEWTEXT subparameter permits modification of the text of a message, or command syntax, before it appears on the console. It is used, for example, to make a message more meaningful, to standardize installation messages, or to translate messages from English to another language. NEWTEXT also supports Control-O AutoEdit variables. AutoEdit symbols embedded in NEWTEXT are dynamically edited at time of rule activation. This permits, for example, inclusion of data contained in the nth word of a message, or the job ID of the job issuing the message, or the reply ID from a reply question. For more information about the AutoEdit facility, see AutoEdit Facility.

The ROUTE subparameter permits rerouting of messages to any number of consoles, using multiple DO DISPLAY statements.

Suppressing a command's execution.

In addition to suppressing the command's echo message (the message that logs the command) the command will be suppressed from execution if the following conditions are true:

1. For JES2 commands, the PARAMETER JCMDSSN in CTOPARM is not NO.

2. For other subsystems that can receive operator commands, the IOA subsystem must be defined in the subsystem list (IEFSSNxx) before the receiving subsystem is defined in the subsystem list.

RL: $HASP309   LIB CTO.PROD.RULES                             TABLE: JOB
COMMAND ===>                                                  SCROLL===> CRSR
+--------------------------------------------------------------------------+
  ON MESSAGE  = $HASP309
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION SUPPRESS JES2 'INITIATOR INACTIVE' MESSAGE
  DESCRIPTION
  ==========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO
  ==========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                12.33.38

RL: *          LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = *
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID 10 CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not N
  ON COMMAND  = $D*
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID 10 CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not N
  ON COMMAND  = D*
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID 10 CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION ON WEEKENDS, CONSOLEID 10 IS ONLY ALLOWED TO ISSUE DISPLAY
  DESCRIPTION COMMANDS.
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO SHOUT    = TO OPER2-10          URGENCY U SYSTEM          CTO282I
     MESSAGE CONTROL-O - UNAUTHORIZED COMMAND - %%CMD
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

RL: IEC501A    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = IEC501A
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION CHANGE TAPE MOUNT MESSAGE
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS N ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
     NEWTEXT >>>>>>>> MOUNT ON   %%V3     VOLSER  %%V4   <<<<<<<<<<
  DO DISPLAY  = SUPPRESS N ROUTE     DESC 00 CONSOLEID 10 CONSOLE
     SYSTEM
     NEWTEXT %%MSG
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                   12.33.38

DO DOM: Automated Console Action Parameter

Specifies a message to be deleted from the display screen of the operator console. The DOM parameter can be used to delete Highlighted, Unrollable operator messages, or WTOR (Write to Operator with Reply) messages for which a response is no longer required. DOM is an abbreviation for "Delete Operator Message."

Figure 148 DO DOM Parameter Format

Optional. Type DOM in the DO field and press Enter. In the field to the right of the = prompt, specify a message identification number (DOM ID), either using one of the AutoEdit System variables described below, or an AutoEdit variable that resolves to a message identification number. The format is:

DO DOM=message_identification_number

The following AutoEdit System variables can be used to specify the desired message identification number:

• %%$MDOMID – the message identification number (DOM ID) of the message that triggered the rule

• %%$LDOMID – the message identification number (DOM ID) of the last message issued or intercepted by Control-O

General Information

Using the DO DOM statement, the Control-O monitor can delete from the console Highlighted, Unrollable or WTOR messages issued by Control-O or issued by other tasks in the system.

Each message is assigned a unique message identification number (DOM ID) that must be specified when deleting the message from the console. These message identifiers are made available to the rule through the %%$MDOMID and %%$LDOMID AutoEdit System variables.

DO statements that issue or intercept messages, such as DO SHOUT or DO COMMAND, result in the update of the %%$LDOMID variable. User-defined AutoEdit variables, specified in a DO SET statement, can be used to retain specific values of the %%$LDOMID variable for later use.

RL: IEF233A    LIB CTO.PROD.RULES                             TABLE: JOB
COMMAND ===>                                                  SCROLL===> CRSR
+--------------------------------------------------------------------------+
  ON MESSAGE  = IEF233A
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION TAPE MOUNT
  DESCRIPTION REPLACE IEF233A MSG WITH A MORE USER FRIENDLY MSG
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS N ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
     NEWTEXT PLEASE MOUNT TAPE %%$V4 ON UNIT %%$V3
  DO SET      = %%NEWDOMID=%%$LDOMID                                GLOBAL  N
  DO WAIT     = REPLY                DOM Y             TIMEOUT 9999
     MESSAGE
  DO DOM      = %%NEWDOMID
  DO
  ==========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                16.47.17

DO ENDMSG: Automated Console Action Parameter

Delimits the DO statements processed when multi-line messages, or messages intercepted in command-response mode, are handled.

Figure 150 DO ENDMSG Parameter Format

Optional. Type ENDMSG in the DO field and press Enter. The word DO disappears from the screen, and only the word ENDMSG remains displayed on the line.

General Information

DO ENDMSG delimits the DO statements processed when multi-line messages, or messages intercepted in command-response mode, are handled.

When multi-line messages or responses are intercepted, the rule is triggered by each intercepted line. However, unless otherwise specified, through a DO ENDMSG statement, DO statements in the rule are not performed until the rule is triggered by the last line of the message or response.

When specific DO statements should be performed each time the rule is triggered by a line of the message or response, insert a DO ENDMSG statement as follows:

• DO statements that should be performed each time the rule is triggered by a line of the message or response should appear before the DO ENDMSG statement. The current message or response can be referenced using the %%$M* System variable.

• DO statements that should be performed only when the rule is triggered by the last line of the message or response should appear after the DO ENDMSG statement. Individual messages or responses within the accumulation can be referenced using the %%$Mn System variable.

For more information, see DO COMMAND: Automated Console Action Parameter.

RL: CHKACT*    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = CHKACT*
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION CHECK IF SPECIFIC JOB IS ACTIVE
  DESCRIPTION
  ===========================================================================
  DO SET      = %%JNAME = %%$V2                                     GLOBAL  N
  DO SET      = %%JSTAT = INACTIVE                                  GLOBAL  N
  DO COMMAND  = D A,%%JNAME
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT
     RESPMSG
  IF       %%$W2 %%$M* EQ %%JNAME
  DO SET      = %%JSTAT = ACTIVE                                    GLOBAL  N
  ENDIF
  DO DISPLAY  = SUPPRESS A ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  ENDMSG
  DO SHOUT    = TO OPER              URGENCY R SYSTEM            CTO282I
     MESSAGE JOB %%JNAME IS %%JSTAT
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  15.43.42

DO EXIT: Automated Console Action Parameter

Exits from a multi-line message block or from a DO WHILE block.

Figure 152 DO EXIT Parameter Format

Optional. Type EXIT (or its abbreviation EX) in the DO field and press Enter. Type one of the values shown in Table 129 to the right of the = prompt.

Table 129 DO EXIT Values

General Information

DO EXIT facilitates exiting from a multi-line message block and from a DO WHILE block.

When DO EXIT is specified for a message, the remaining lines of the message are not processed. Instead, Control-O passes to the first line following the ENDMSG.

When DO EXIT is specified for a DO WHILE block, processing of the DO WHILE block is ended and the rule will continue after the ENDWHILE.

ON EVENT    = IDLEOWNER N18      GROUP                         MODE LOG     RUNTSEC
THRESHOLD
DESCRIPTION
===========================================================================
DO SET      = %%$MLLEND=NO                                        GLOBAL  N
DO COMMAND  = $DA
   WAIT        CONSOLEID    CONSOLE          SYSTEM
   WAITMODE   Y             WAITRESP Y            TIMEOUT
   RESPMSG $HASP890     $HASP612
IF       %%$MSGID EQ $HASP612
DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
   MESSAGE SYSTEM IS IDLE
EXIT     MESSAGE
DO
ENDIF
ENDMSG
DO
===========================================================================

DO FORCEJOB: Automated Console Action Parameter

Forces jobs under Control-M.

Figure 154 DO FORCEJOB Parameter Format

Optional. Type FORCEJOB in the DO field and press Enter. The subparameters shown in Table 130 are displayed:

Table 130 DOFORCEJOB Subparameters

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

Table 130a AutoEdit System Variables

General Information

Control-O AutoEdit variables embedded in the TABLE, JOB, DATE, and LIBRARY subparameters are automatically resolved (replaced) at time of rule activation. For more information about the AutoEdit Facility, see AutoEdit Facility

DO FORCEJOB schedules a job under Control-M even if the date is not specified as a scheduling date in the Basic Scheduling parameters of the job. It is similar to the FORCE option in the Control-M Table List screen.

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

If the Control-M monitor is active, the DO FORCEJOB statement is executed by the Control-M monitor.

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

If Control-M is not installed, ordering a rule containing a DO FORCEJOB statement fails with an error message.

DO FORCEJOB can also function similarly to the Control-M CMEM facility. The purpose of the CMEM option in Control-M is to permit Control-M to control jobs that are not submitted by Control-M, or to order new Control-M tables, based on the appearance of a job on spool. The Control-O DO FORCEJOB statement permits ordering of such jobs into Control-M based on the appearance of a message.

Control-O handles DO FORCEJOB statements differently for JOBARRIVAL events and messages, JOBEND events and messages, and all other messages. The differences in handling are explained below. For more information, see the discussion of ON SPOOL jobs in the CMEM chapter of the Control-M for z/OS User Guide.

A DO FORCEJOB statement can be distributed to Control-O on a remote system that is identified through the %%$COMMSYS reserved user-defined variable in a preceding DO SET statement. For more information, see the description of %%$COMMSYS in Reserved User-Defined Variables, and Performing an Action on Another System

The DATE field

When either ?, DATE?, or ODAT? are used in the DATE field to check the status of the job, the values returned can be accessed by using the following variables:

• %%$CTMJGROUP

• %%$CTMJHLDSTAT

• %%$CTMJJOBID

• %%$CTMJJOBNAME

• %%$CTMJLIBRARY

• %%$CTMJMEMNAME

• %%$CTMJODATE

• %%$CTMJORDERID

• %%$CTMJOWNER

• %%$CTMJRBA

• %%$CTMJSTATUS

• %%$CTMJTABLE

• %%$CTMJTYPE

• %%$CTMLINE#

• %%$CTMLINES

• %%$CTMRC

For more information on these variables, see AutoEdit Facility.

JOBEND Rules or $HASP395/IEF404I Messages

DO FORCEJOB actions specified in a JOBEND Event rule or in a Message rule triggered by $HASP395 (under JES2) or IEF404I (under JES3) are executed only if the terminating job is not under Control-M control. The JOBEND Event rule in this case will not cause a job to be put in WAIT SCHEDULE ON SPOOL state.

JOBARRIVAL Rules or $HASP100 or IAT6101 Messages

$HASP100 or IAT6101 messages indicate the appearance of a job on spool. The process for these messages is the same as the process for Control-M CMEM JOBARRIVAL event. When $HASP100 or IAT6101 is indicated in the ON MESSAGE statement in a rule definition, Control-O intercepts such messages as follows:

1. If the message was issued for a job submitted by Control-M, the DO FORCEJOB is ignored.

2. If the message was not issued for a job submitted by Control-M, Control-M orders the requested table or job. Control-M scans the ordered jobs looking for the job with a MEMNAME that matches the name of the job that triggered the ordering (the job name in the scheduling table can be a job name mask). If one is found, it will appear on the Status screen in WAIT SCHEDULE ON SPOOL state, and is assigned the jobID of the job that triggered the message. If a matching job name is not found, or if more than one job was ordered, the remaining jobs will appear in WAIT SCHEDULE state and Control-M will process these jobs normally.

3. When all Runtime Scheduling criteria of the On Spool job are met, the job is released for execution (from JES held status) by an operator command issued from Control-M. If the job is already running, Control-M will start tracking it. Control-M then controls the job as any other job. It reads the SYSOUT of the job when the job terminates, and analyzes execution results, adds and deletes conditions, performs SHOUTs, and so on. However, there are certain restrictions: Any attempt to rerun the job, either 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 its MEMLIB parameter of the job order.

Other Messages and Events

Messages other than those produced by JOBEND and JOBARRIVAL rules are handled by Control-O as follows:

• If the message was issued by a job submitted by Control-M, or no jobID and job name appear in the message, the job (or table) is handled as usual, meaning, it is ordered and placed on the Active Jobs file.

• If the message was not issued by a job submitted by Control-M, and the message contains a jobID and job name, the job or table is handled similarly to non-Control-M jobs for $HASP100 messages (paragraph #2 above).

• For DSNEVENT or STEP events, the job or table is handled as usual, that is, it is ordered and placed on the Active Jobs file.

RL: IEE361I    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = IEE361I
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION SCHEDULE CLEAN SMF JOB UNDER CONTROL-M
  DESCRIPTION WHEN AN SMF FILE IS FULL
  DESCRIPTION
  ===========================================================================
  DO FORCEJOB = TABLE   SMF      JOB CLEANSMF  UFLOW N    DATE ODAT
                LIBRARY CTM.PROD.SCHEDULE
  DO
  ===========================================================================
  DAYS                                                          DCAL
 AND/OR
  WDAYS   ALL                                                   WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ===========================================================================
  IN
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

RL: $HASP100 LIB   CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = $HASP100
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER SYS3      GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION FORCE ORDERING OF ON SPOOL BACKUP JOBS
  DESCRIPTION
  ===========================================================================
  DO FORCEJOB = TABLE   BACKUP   JOB BKPJOB    UFLOW Y    DATE ODAT
                LIBRARY CTM.PROD.SCHEDULE
  DO
  ===========================================================================
  DAYS                                                          DCAL
                                                AND/OR
  WDAYS   ALL                                                   WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ===========================================================================
  IN
  TIME FROM     UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

DO IF / DO ELSE / DO ENDIF: Automated Console Action Parameter

DO IF, DO ELSE, and DO ENDIF statements provide Control-O with Boolean "IF" logic capability. These statements permit branching based on different criteria. The examples at the end of this section demonstrate combination of these statements.

Figure 155 DO IF/DO ELSE/DO ENDIF Statements Format

Type IF in the DO field and press Enter. The word DO is replaced by the word IF on the screen. The same will occur when specifying ELSE and ENDIF in the DO fields.

Figure 156 shows the basic format of the IF/ ELSE/ ENDIF control statements.

Figure 156 IF/ ELSE/ ENDIF Statements Format

IF conditional-expresssion1 [{AND|OR} conditional-expression2]
 DO action
 DO action
     .
     .
     .
     .
  DO action
ELSE
  DO action
  DO action
     .
     .
     .
     .
ENDIF

The IF conditional expression has the following format:

IF operand operator operand

Valid logical operators are shown in Table 131.

Table 131 Logical Operators for IF Statement

Valid Boolean operators are shown in Table 132.

Table 132 Boolean Operators for IF Statement

Operators that end with the pound sign (#) are used for numerical comparisons, as opposed to string comparisons.

An operand can be any character string. It can also be composed of AutoEdit symbols. In such cases, it is resolved into a character string before the conditional expression is analyzed at execution time.

Whenever non-numeric comparison operators are specified, operands are compared as character strings from left to right. For example, in the expression

IF 91 GT 1000

91 is greater than 1000 (because 9 is greater than 1).

An operand cannot be resolved into nulls (as in CLISTs). If it is possible that an operand will resolve into nulls, place a character before the first and second operands.

In the following example, the character B is placed before the two operands:

IF B%%A GT B%%C

An IF expression must be terminated with an ENDIF statement. The ELSE statement is optional.

General Information

When the IF expression is true, commands between the IF expression and its ELSE statement, or its matching ENDIF statement when no ELSE statement is present, are resolved by Control-O.

When the IF expression is not true, and an ELSE statement exists, only the statements after the ELSE statement are executed. If the ELSE clause does not exist, Control-O stops processing the IF expression and continues executing the rule.

IF expressions can be nested, providing that the above rules are observed. Up to 100 nested IF statements are permitted.

When the rule is saved, logical checks are performed to verify the validity of the rule statements. For example, ENDMSG is not allowed in the IF-ENDIF block. If an error is deleted, an error message is issued upon exiting the rule, and the rule cannot be saved until the syntax is corrected.

SHOWNEST Command

To see the nesting levels of DO statements, relative to the nesting level of IF statements, type SHOWNEST (or SH) in the COMMAND field. Nesting levels are displayed to the left of each DO statement.

Issue the SHOWNEST command again to suppress the display of the nesting levels.

RL: IEF450I    LIB CTO.PROD.RULES                        TABLE: JOB
COMMAND ===>                                         SCROLL===> CRSR
+-----------------------------------------------------------------+
  ON MESSAGE  = IEF450I                                           
     JNAME JOBM43   JTYPE         SMFID        SYSTEM             
     ROUTE          DESC          CONSOLEID    CONSOLE            
     APPEARED       TIMES IN      MINUTES                And/Or/Not
  OWNER IOAADMIN GROUP                        MODE PROD    RUNTSEC
  THRESHOLD                                                       
  DESCRIPTION JOB 'JOM43' ABENDED                                 
  DESCRIPTION                                                     
  =================================================================
  IF       %%A EQ# 0                                              
  DO COND     = JOBM43-ABENDED       ODAT +                       
  ENDIF                                                           
  DO SET    = %%A = %%A %%$PLUS 1                         GLOBAL  Y
  DO                                                              
  =================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF      12.33.38

RL: IEF450I    LIB CTO.PROD.RULES                        TABLE: JOB
COMMAND ===>                                        SCROLL===> CRSR
+------------------------------------------------------------------+
  ON MESSAGE  = IEF450I
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                And/Or/Not
  OWNER IOAADMIN  GROUP                        MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION JOB ABENDED - NOTIFY OWNER AND INCREASE ABENDS COUNTER
  DESCRIPTION
  =================================================================
  DO SET    = %%PREF = %%SUBSTR %%$JOBNAME 1 3            GLOBAL  N
  IF       %%OWNERID_%%PREF NE %%UNDEF
  DO SET    = %%OWNER = %%OWNERID_%%PREF                  GLOBAL  N
  DO SHOUT    = TO TSO-%%OWNER       URGENCY R SYSTEM       CTO282I
     MESSAGE %%MSG
  IF       %%ABENDS_%%OWNER NE %%$UNDEF
  DO SET   = %%ABENDS_%%OWNER = %%ABENDS_%%OWNER %%$PLUS 1 GLOBAL Y
  ELSE
  DO SET    = %%ABENDS_%%OWNER = 1                         GLOBAL  Y
  ENDIF
  ENDIF
  DO
  =================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF      18.50.28

RL: IEF450I    LIB CTO.PROD.RULES                               TABLE: SAMPLE
COMMAND ===>                                                    SCROLL===> CRSR
-----------------------------------------------------------------------------
  ON MESSAGE  = IEF450I
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION INFORM THE CICS MANAGER IF CICSTEST ABENDED IN CPU1
  DESCRIPTION
  ===========================================================================
  IF       %%$SMFID EQ CPU1 AND %%$JOBNAME EQ CICSTEST
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE CICSTEST ABENDED IN CPU1
  ENDIF
  DO
  ===========================================================================
  DAYS                                                          DCAL
  AND/OR
  WDAYS   ALL                                                   WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT , SHPF , SCHED , OPT               14.19.04

DO KSL: Automated Console Action Parameter

Specifies a KeyStroke OpenAccess (KOA) script to be executed.

Figure 157 DO KSL Parameter Format

Optional. Type KSL in the DO field and press Enter. The subparameters shown in Table 133 are displayed.

Table 133 DO KSL Subparameters

For information regarding KeyStroke OpenAccess (KOA) scripts, refer to the KeyStroke Language (KSL) User Guide.

General Information

Control-O AutoEdit variables embedded in the DO KSL statement are automatically resolved (replaced) at time of rule activation. For more information on the AutoEdit facility, see AutoEdit Facility

Wait Completion Mode

Execution of the DO statements following a DO KSL statement can be delayed until the KeyStroke OpenAccess (KOA) script has finished executing, thereby enabling checking of the completion code. This delay is achieved by specifying Y (Yes) for the WAITMODE subparameter, which places the rule in Wait (Completion) mode. The TIMEOUT subparameter can be used to specify how long (in seconds) to wait for completion of the script.

When rule execution is resumed, AutoEdit System variable %%KSLRC will contain either the completion code of the script, or the value 522, which means that the TIMEOUT limit was reached before completion of the script.

Wait mode can also be specified for a KSL script execution by specifying a DO SET=%%WAITKSL = Y statement before the DO KSL statement. Using this method, a TIMEOUT period can be specified through a DO SET %%TIMEOUT = value statement. This method is supported for historical reasons.

Using a Preset Environment

DO KSL statements are executed by Control-O servers. Servers are started tasks that are managed automatically by Control-O. You can define Immediate, Special, and General servers. These server types are discussed in detail in Chapter 5, "Control-O Servers." However, when defining a DO KSL statement, bear in mind the following information:

• Immediate servers

  Immediate servers are useful for either

  • KOA scripts that need to be executed immediately, for example, those that need to bypass the wait queue of the server

  • KOA scripts that should not be executed by a Special or General server, for example, long running scripts that delay the running of other scripts waiting to be executed

  To request an Immediate server, type Y (Yes) in the IMMEDIATE subparameter.

• Special servers

  Special servers are useful when the same environment is used frequently for KOA scripts. This generally occurs when different KOA scripts (in the same or different rules) use the same VTAM application. Use of the same VTAM session by all these scripts improves performance considerably.

  To request a Special server, do the following:

  1. Type N (No) in the IMMEDIATE subparameter, or leave it blank.

  2. Enter the name of the KOA script that handles the preset environment in the INITPROC subparameter.

  3. Ensure that a Special server with the name specified in the INITPROC subparameter has been defined to Control-O.

• General servers

  General servers are useful when scripts infrequently use a specific environment and/or do not use a preset environment.

  To request a General server, do the following:

  1. Type N (No) in the IMMEDIATE subparameter, or leave it blank.

  2. Ensure that the necessary environment is established by either the script specified in the DO KSL statement or by the script specified in the INITPROC subparameter.

  3. Ensure that there is no Special server defined to Control-O with the same name as the script specified in the INITPROC subparameter (if one was specified).

  Whenever INITPROC is specified, Control-O ensures that the indicated script is automatically invoked to maintain the preset environment, for example, to perform logon, reset and logoff actions.

  Ensure that the script specified in the DO KSL statement does not perform any of the functions performed by the KOA script specified in INITPROC.

  Examples of how to use DO KSL and INITPROC scripts are provided in the Keystroke Language (KSL) User Guide.

  For information on how to define servers, see the INCONTROL for z/OS Installation Guide.

RL: DFH1500    LIB CTO.PROD.RULES                             TABLE: JOB
COMMAND ===>                                                  SCROLL===> CRSR
+--------------------------------------------------------------------------+
  ON MESSAGE  = DFH1500
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                       And/Or/Not A
  ON STRING   = CONTROL IS BEING GIVEN TO CICS                  COL     -
     JNAME CICS*    JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION USE KOA SCRIPT TO PERFORM INITIAL TASKS AFTER CICS STARTUP
  DESCRIPTION
  ==========================================================================
  DO SET      = %%APPLID = %%$V2                                    GLOBAL  N
  DO KSL      = CICSINIT %%%V2
     WAITMODE   Y                                      TIMEOUT 9999    STOP Y
     INITPROC        SHARELOC Y                        IMMEDIATE Y
  IF       %%$KSLRC EQ# 0
  DO COND     = %%APPLID-RUNNING     STAT +
  ELSE
  DO SHOUT    = TO TSO-SYSMNGR       URGENCY R SYSTEM           CTO282I
     MESSAGE INITIALIZATION OF %%APPLID FAILED
  ENDIF
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                 18.06.33

DO RESOURCE: Automated Console Action Parameter

Changes the quantity of a Quantitative resource.

Figure 159 DO RESOURCE Parameter Format

Optional. Type RESOURCE in the DO field and press Enter. The subparameters shown in Table 134 are displayed.

Table 134 DO RESOURCE Subparameters

General Information

This parameter is used to control the use of resources in the installation, such as tape drives, CPU, DB access. Upon rule activation, Control-O can change the quantity of a Quantitative resource.

Control-O AutoEdit variables embedded in the DO RESOURCE name subparameter are automatically resolved (replaced) at the time of rule activation. For more information about the AutoEdit facility, see AutoEdit Facility.

• If the Control-M monitor is active, the DO RESOURCE statement is executed by the Control-M monitor.

• If the Control-M monitor is not active, the DO RESOURCE statement is queued and is performed when the Control-M monitor becomes active.

• If Control-M is not installed, ordering a rule containing a DO RESOURCE statement fails with an error message.

• If the message that triggered the rule was issued from a job submitted by Control-M, the request is passed to Control-M. Control-M performs checks to determine whether or not it has already allocated the resource to the job. If it has been allocated, the DO RESOURCE statement is ignored. This behavior allows Control-O to work in synchronization with the Control-M resource allocation algorithm, while at the same time adjusting the Quantitative resource (that is, the MAX RESOURCE counter) to external changes.

A DO RESOURCE statement can be distributed to Control-O on a remote system that is identified by the %%$COMMSYS reserved user-defined variable in a preceding DO SET statement. For more information, see the description of %%$COMMSYS in Reserved User-Defined Variables, and Performing an Action on Another System.

RL: IEC501I*   LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
 +-----------------------------------------------------------------------------+
 ON MESSAGE  = IEC501I*
 JNAME          JTYPE         SMFID        SYSTEM
 ROUTE          DESC          CONSOLEID    CONSOLE
 APPEARED       TIMES IN      MINUTES                        And/Or/Not
 OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
 DESCRIPTION UPDATE RESOURCE QUANTITITES (MOUNT MESSAGE)
 DESCRIPTION
 ===========================================================================
 DO RESOURCE = TAPE               0001 -
 DO
 ==========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  09.18.53

Query the status of a resource in Control-M.
RL: IEC501I*   LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
__ ON MESSAGE  = CHECKRES
__    JNAME          JTYPE      SMFID        SYSTEM          USERID
__    ROUTE          DESC       CONSOLEID    CONSOLE
__    APPEARED       TIMES IN      MINUTES                        And/Or/Not
__ OWNER M88B     GROUP                         MODE LOG     RUNTSEC
__ THRESHOLD
__ DESCRIPTION CHECKS CONTROL-M FOR A RESOURCE
__ DESCRIPTION
__ ===========================================================================
__ DO RESOURCE = MAURIKANTER          0008 ?
__ IF       %%$CTMRC EQ# 0
__ DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I
__    MESSAGE RESOURCE FOUND
__ DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I
__    MESSAGE %%$CTMRESMAX %%$CTMRESCURR %%$CTMRESPRI
__ ENDIF
__ IF       %%$CTMRC EQ# 4
__ DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I
__    MESSAGE RESOURCE NOT FOUND
__ ENDIF
__ IF       %%$CTMRC GT# 4
__ DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I
__    MESSAGE ERROR USING CONTROL-M INTERFACE - %%$CTMRC
__ ENDIF
__ DO
__ ===========================================================================.
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  09.18.53

DO RETURN: Automated Console Action Parameter

Exit from the rule and return (up one level) to the caller, which is either a calling rule or Control-O.

Figure 160 DO RETURN Parameter Format

Optional. Type RETURN (or its abbreviation RET) in the DO field, and press Enter.

General Information

DO RETURN is used to end the processing of the current rule. When the current rule was called from another ON RULE type, control is returned to the calling rule. Otherwise, control is returned to Control-O, which continues searching for additional rules.

RL: DFH1500    LIB CTO.PROD.RULES                               TABLE: JOB  
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
ON MESSAGE  = DSI530I
   JNAME          JTYPE      SMFID        SYSTEM          USERID
   ROUTE          DESC       CONSOLEID    CONSOLE
   APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER IOADMIN  GROUP                         MODE LOG     RUNTSEC
THRESHOLD
DESCRIPTION NLDM/NPDA IS ACTIVE
===========================================================================
IF       %%$V2 EQ  ''AAUTCNMI''
DO SET      = %%STATUS_NLDM = UP                                  GLOBAL  Y
RETURN
ENDIF
IF       %%$V2 EQ  ''BNJDSERV''
DO SET      = %%STATUS_NPDA = UP                                  GLOBAL  Y
ENDIF
DO
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  09.18.53

DO RULE: Automated Console Action Parameter

Invokes another rule from within the current rule.

Figure 162 DO RULE Parameter Format

Optional. Type RULE (or its abbreviation RU) in the DO field and press Enter. The subparameters shown in Table 135 are displayed.

Table 135 DO RULE Subparameters

General Information

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 rule is searched for among the rules in the active environment 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.

While a called rule is active, both the called rule and the calling rule share the same AutoEdit System variable and Local variable environment. The calling rule can pass an argument string as input to the called rule. This argument string may contain AutoEdit expressions that are resolved at time of rule execution. The argument string may be accessed by the called rule through the %%$ARGS System variable. If a called rule calls another rule, the %%$ARGS values passed in the earlier call is overwritten by the %%$ARGS values passed by the later call. For more information about the AutoEdit facility, see AutoEdit Facility.

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

A called rule can invoke other rules through the DO RULE parameters. Nesting of DO RULE calls (for example, rule 1 calls rule 2, which calls rule 3, and so on), up to 20 deep, is supported. A rule can be called recursively.

A DO RULE statement can be distributed to Control-O on a remote system that is identified by the %%$COMMSYS reserved user-defined variable in a preceding DO SET statement. For more information, see the description of %%$COMMSYS in Reserved User-Defined Variables, and Performing an Action on Another System.

When a DO RULE statement requests execution of a remote rule, Control-O transfers the system AutoEdit variables. Local AUTOEDIT variables are not transferred to the remote Control-O.

To exit a called rule, specify either DO RETURN or DO TERMINAT, as follows:

• To return up one level to the calling rule, specify DO RETURN.

• To exit all calling rules at all levels and return directly to Control-O, specify DO TERMINAT.

RL: SHUTSYS    LIB CTO.PROD.RULES                        TABLE: JOB
COMMAND ===>                                                     SCROLL===> CRSR
+---------------------------------------------------------------------------
  ON COMMAND  = SHUTSYS
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                                 MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION SHUTDOWN - STOP A LIST OF STARTED TASKS (DO RULE EXAMPLE)
  DESCRIPTION THIS RULE ASSUMES THAT A LIST OF STARTED TASKS TO BE STOPPED
  DESCRIPTION IS DEFINED VIA GLOBAL VARIABLES %%STC_1, %%STC_N, AND THAT
  DESCRIPTION THE NUMBER OF STARTED TASKS IS DEFINED IN %%STC_NUMBER
  DESCRIPTION
  ===========================================================================
  /*
  /* FOR EACH STARTED TASK IN THE LIST, INVOKE RULE STOPSTC.
  /* PARAMETERS PASSED ARE THE STC NAME AND THE TIMEOUT VALUE.
  /*
  DO SET      = %%I = 1                                             GLOBAL  N
  WHILE    %%I LE# %%STC_NUMBER
  DO RULE     = STOPSTC %%STC_%%I 30                          OWNER  IOAADMIN
     TABLE               LIBRARY
  DO SET      = %%I = %%I %%%$PLUS 1                                GLOBAL  N
  ENDWHILE
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                 13.18.04

DO SET: Automated Console Action Parameter

Assigns a value to an AutoEdit variable (or performs AutoEdit functions).

Figure 164 DO SET Parameter Format

Optional. Type SET in the DO field and press Enter. The subparameters shown in Table 136 are displayed.

Table 136 DO SET Subparameters

General Information

To take full advantage of this parameter, a familiarity with Control-O AutoEdit variables is essential. A complete description of the AutoEdit facility is contained in AutoEdit Facility, especially in the Using the DO SET Statement section.

The DO SET parameter permits setting of values to variables (or symbols). These variables can then be referenced in other DO statements in the rule definition during rule activation.

Setting GLOBAL to N, the default, indicates that the DO SET variable assignment is applicable for local purposes only – that is, for the current activation of the rule.

Setting GLOBAL to Y saves the value for global use by other Control-O rules, by subsequent activations of the same rule, and optionally for use by the Control-M AutoEdit facility. Setting GLOBAL to Y is also used in an XAE database, which is discussed in the following topic.

Using XAE AutoEdit Variable Databases

XAE variable databases are Sysplex-wide AutoEdit variable databases). Like other AutoEdit variable databases, these are defined using the Variable Database Definition facility. The variables are resolved by AutoEdit expressions. Once variables are loaded by Control-O into memory, the variables can be changed using DO SET, in exactly the same way as for standard databases. Global AutoEdit variables in an XAE database can be accessed by other rules across a Sysplex. For more information about the XAE variables, see Using an XAE AutoEdit Variable Database.

Using Global Variable Members

A primary usage of the Global variables is to set globally accessed flags, or counters, for example, the current IMS reply number.

When Control-O is started, members of the Global AutoEdit library and AutoEdit variable databases where Global variables reside are loaded into memory. Any updates or additions to Global variables (by rules or KOA scripts) are kept in memory by Control-O and are available to all other rules. For more information, see the Control-O chapter in the INCONTROL for z/OS Administrator Guide.

By default, a Global AutoEdit variable is assigned to the $GLOBAL member. However, a Global AutoEdit variable can be assigned to a specific member by one of the methods described in the following paragraphs.

A Global AutoEdit variable can be assigned to a specific member by the statement

DO SET=%%member\variable GLOBAL = Y

A Global AutoEdit variable, or a set of Global AutoEdit variables, can be assigned to a specific member or variable database by first specifying the member or database by the statement

DO SET=%%$GLOBAL = member

followed by specification of a statement for each variable, in the format

DO SET=%%variable = value GLOBAL=Y

Each set variable with GLOBAL set to Y is assigned to the specified Global member.

When referencing a variable in the default Global member (usually $GLOBAL, if not specified otherwise), the member specification can be omitted and the variable is referenced as

%%variable

Using AutoEdit Variable Databases

Databases of Global variables can be defined using the Online Variable Database Definition facility. These databases are loaded together with the conventional Global variable members during startup of Control-O.

To change the value of a variable in a variable database:

1. Specify the database as the current Global variable pool. For example

   Copy

   DO SET=%%$GLOBAL = DBNAME GLOBAL  N

2. Specify the row in the database where the variable is located. For example

   Copy

   DO SET=%%$DBROW = 3 GLOBAL  N

3. Specify the column in the specified row and the value for the variable in that column. For example

   Copy

   DO SET=%%COLNAME = 57 GLOBAL  Y

The %%$DBCOUNT AutoEdit System variable, which indicates the number of rows in the current variable database, can be used to loop through the variables in a given column.

For more information on the Variable Database Definition facility, see IOA Variables Database Facility.

Control-O Variable databases can be checkpointed using the WRITEGLOBAL operator command. For more information on this command, see the Control-O chapter of the INCONTROL for z/OS Administrator Guide.

DO SET=%%PRODABEND = %%PRODABEND %%$PLUS 1 GLOBAL Y

DO SHOUT=%%PRODABEND PRODUCTION ABENDS HAVE OCCURRED

DO SET=%%IMS\STATUS=UP               GLOBAL Y

DO SET=%%$GLOBAL = IMS
DO SET=%%STATUS = UP                 GLOBAL Y

DO SHOUT TO OPER TEXT IMS IS %%IMS\STATUS

RL: DFS810A    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = DFS810A
     JNAME IMS1     JTYPE S       SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION IDENTIFY IMS IS READY (KEEP REPLY NUMBER + SIGNAL CONTROL-M)
  DESCRIPTION
  ===========================================================================
  DO COND     = IMS1-IS-ACTIVE       STAT +
  DO SET      = %%IMS1_REPLY = %%REPLY                              GLOBAL  Y
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

RL: DFSxxxx    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = DFSxxxx
     JNAME IMS1     JTYPE S       SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION
  ===========================================================================
  DO COMMAND  = %%IMS1_REPLY  /STA DBD
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  DO
  ===========================================================================

FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

RL: TESTDB01   LIB CTO.PROD.RULES                               TABLE: VARULES
COMMAND ===>                                                    SCROLL===> CRSR
-----------------------------------------------------------------------------
  ON EVENT    = TESTDB01
  OWNER M88A     GROUP                         MODE LOG     RUNTSEC
  THRESHOLD
  DESCRIPTION SPECIFY VARIABLES IN AN AUTOEDIT VARIABLE DATABASE
  DESCRIPTION
  ===========================================================================
  /* SET THE DEFAULT POOL TO THE DATABASE POOL
  DO SET      = %%$GLOBAL = MYDBPOOL                                GLOBAL  N
  /* RESET ROW COUNTER
  DO SET      = %%ROW = 0                                           GLOBAL  N
  /* INFORM WE WANT TO ACCESS ROW 1
  DO SET      = %%ROW = %%ROW %%$PLUS 1                             GLOBAL  N
  DO SET      = %%$DBROW  = %%ROW                                   GLOBAL  N
  /* SET ROW 1 VALUES AS DESIRED
  DO SET      = %%FIELD01 = ANYVALUE11                              GLOBAL  Y
  DO SET      = %%FIELD02 = ANYVALUE12                              GLOBAL  Y
  /* INFORM WE WANT TO ACCESS ROW 2
  DO SET     = %%ROW = %%ROW %%$PLUS 1                              GLOBAL  N
  DO SET     = %%$DBROW  = %%ROW                                    GLOBAL  N
  /* SET ROW 2 VALUES AS DESIRED
  DO SET     = %%FIELD01 = ANYVALUE21                               GLOBAL  Y
  DO SET      = %%FIELD02 = ANYVALUE22                              GLOBAL  Y
  FILL IN RULE DEFINITION. CMDS: EDIT , SHPF , SCHED , OPT               14.23.00

RL: TESTDB02   LIB CTO.PROD.RULES                             TABLE: VARULES
COMMAND ===>                                                  SCROLL===> CRSR
----------------------------------------------------------------------------
  ON EVENT    = TESTDB02
  OWNER M88B     GROUP                          MODE PROD     RUNTSEC
  THRESHOLD
  DESCRIPTION PROCESS ROWS FROM ONE DATABASE POOL
  DESCRIPTION
  ===========================================================================
  DO SET      = %%$GLOBAL  = MYDB                                   GLOBAL  N
  DO SET      = %%COS_IROW = 0                                      GLOBAL  N
  WHILE    %%COS_IROW LT# %%$DBCOUNT
  DO SET      = %%COS_IROW = %%COS_IROW %%$PLUS 1                   GLOBAL  N
  DO SET      = %%$DBROW = %%COS_IROW                               GLOBAL  N
  DO SHOUT    = TO OPER              URGENCY R SYSTEM            CTO282I
     MESSAGE %%FIELD01 %%FIELD02
  ENDWHILE
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT , SHPF , SCHED , OPT               14.23.00

DO SHELL: Automated Console Action Parameter

Specifies a z/OS shell script or REXX program to run under z/OS UNIX.

Figure 164a DO SHELL Parameter Format

---------------------------------------------------------------------------------
DESCRIPTION
===========================================================================
DO SHELL    =                                                
   WAITMODE                                         TIMEOUT         STOP
   SHARELOC                                         IMMEDIATE            
DO                                                                        
---------------------------------------------------------------------------------

Optional. Type SHELL in the DO field and press Enter. The subparameters described in Table 136a are displayed.

Table 136a DO SHELL Subparameters

General Information

A DO SHELL statement can be used to initiate any z/OS shell script or REXX program to run under z/OS UNIX. The z/OS shell scripts or REXX programs that are initiated by the DO SHELL statement are run by the BPXBATCH utility that runs under TSO/E.

Control-O AutoEdit variables embedded in a DO SHELL statement are automatically resolved (replaced) at time of rule activation. For more information about the AutoEdit facility, see AutoEdit Facility.

Wait Completion Mode

Execution of the DO statements that follow a DO SHELL statement can be delayed until the z/OS shell script or REXX program has finished executing, thereby enabling checking of the completion code. This delay is achieved by specifying Y (Yes) for the WAITMODE subparameter, which places the rule in Wait (Completion) mode. The TIMEOUT subparameter can be used to specify how long (in seconds) to wait for completion of the z/OS shell script or REXX program.

When rule execution is resumed, the %%SHELLRC AutoEdit system variable will contain either the completion code of the BPXBATCH utility, or the value 522, which means that the TIMEOUT limit was reached before completion of the z/OS shell script or REXX program.

Server Types

DO SHELL statements are executed by Control-O servers. Servers are started tasks that are managed automatically by Control-O. You can use Immediate or General servers. These server types are discussed in detail in Control-O Servers. However, when defining a DO SHELL statement, bear in mind the following information:

• Immediate servers

  Immediate servers are useful for either

  • z/OS shell scripts or REXX programs that run under z/OS UNIX and need to be executed immediately, for example, those that need to bypass the wait queue of the server

  • z/OS shell scripts or REXX programs that run under z/OS UNIX and, if run by a General server, might delay other scripts, for example, long running scripts

  To request an Immediate server, type Y (Yes) in the IMMEDIATE subparameter.

• General servers

  • General servers are useful for those requests that do not need to be run by an Immediate server. Running requests by a General server consumes less resources than by an Immediate server.

  • To request a General server, type N (No) in the IMMEDIATE subparameter, or leave it blank.

For information on how to define servers, see the INCONTROL for z/OS Installation Guide.

RL: BAT*       LIB IOAA.PROD.CTO.OPR.RULES                      TABLE: DSNS
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
ON DSNEVENT = BAT*     JTYPE   SMFID      SYSTEM                           
   DSN      PROD.NEW.OUTPUT.FILE                         DISP CATLG        
   PROCSTEP            PGMSTEP            STEPRC               And/Or/Not  
OWNER IOADMIN    GROUP                       MODE PROD    RUNTSEC 
THRESHOLD                                                                   
DESCRIPTION Order a Control-M MFT job to transfer this data set to a partner
DESCRIPTION when created using the Control-M AAPI CLI
===========================================================================
DO SHELL    = /usr/local/scripts/order_ctm_mft.sh %%$DSN
   WAITMODE   Y                                      TIMEOUT 9999    STOP Y
   SHARELOC   Y                                      IMMEDIATE Y
DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I       
   MESSAGE CTM ORDER OF MFT JOB ENDED WITH RC=%%SHELLRC
DO                                                                          
========================================================================== 

DO SHOUT: Automated Console Action Parameter

Specifies a message to be sent ("shouted") to a specific destination.

Figure 165 DO SHOUT Parameter Format

Optional. Type SHOUT in the DO field and press Enter. The subparameters shown in Table 137 are displayed.

Table 137 DO SHOUT Subparameters

General Information

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 more information, contact your INCONTROL administrator.

The TO Subparameter

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

Specify TO=OPER[dd]-{rrr,-ccc,+nnnnnnnn} to send the message to all operator consoles, or to operator consoles selected according to route code (rrr), console ID number (-ccc), or console name (+nnnnnnnn). The descriptor code (dd) determines the type of message displayed. The dd, rrr, -ccc, and +nnnnnnnn parameters are optional and can be assigned any valid value. rrr, -ccc, and +nnnnnnnn are mutually exclusive.

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

Examples

Table 138 shows examples of the DO SHOUT OPER subparameter.

Table 138 DO SHOUT OPER Subparameter Examples

Specify 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 entry’s content 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 the Dynamic Destination Table in the IOA chapter of 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, specify JES command $LSYS.

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 AutoEdit Facility.

RL: IEF450I    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = IEF450I
     JNAME DB2MSTR   JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION WARN DBA THAT DB2 MASTER ABENDED
  DESCRIPTION
  ===========================================================================
  DO SHOUT    = TO TSO-DBA           URGENCY U SYSTEM          CTO282I
  MESSAGE DB2 MASTER ABENDED - PLEASE CHECK!
  DO
  ===========================================================================







  FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

DO SMSCLASS: Automated Console Action Parameter

Assigns an SMS (Storage Management System) class name to a new data set.

Figure 167 DO SMSCLASS Parameter Format

Optional. Type SMSCLASS in the DO field and press Enter. The subparameters shown in Table 139 are displayed.

Table 139 DO SMSCLASS Subparameters

General Information

DO SMSCLASS overrides the SMS class that an ACS (Automatic Class Selection) routine assigns to a new data set.

DO SMSCLASS can be used only in an ON SMS rule. The ON SMS rule ACS CALL parameter determines which type of SMS class (DATA, MANAGEMENT, or STORAGE) is assigned by DO SMSCLASS.

For example, an ON SMS rule that contains ACS CALL=DATA executes a DO SMSCLASS command that contains CLASS=X. Control-O sets the Data class of selected data sets to X.

An ON SMS rule that contains ACS CALL=MANAGEMENT executes a DO SMSCLASS command that contains CLASS=Y. Control-O sets the Management class of selected data sets to Y.

An ON SMS rule that contains ACS CALL=STORAGE executes a DO SMSCLASS command that contains CLASS=Z. Control-O sets the Storage class of selected data sets to Z.

RL: TESTDB02   LIB CTO.PROD.RULES                               TABLE: VARULES
COMMAND ===>                                                SCROLL===> CRSR
+-----------------------------------------------------------------------------+
ON SMS      = DSN.SMS.FILE
   ACS CALL ALL      JNAME MYJOBNAM JTYPE   SMFID      SYSTEM
   DDNAME  DDNAME    DSORG PDS      UNIT UNIT          DS-TYPE TEMP
   PGM               USER  GTUSER                              And/Or/Not
OWNER N18A     GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION
===========================================================================
DO SMSCLASS = ID 01 CLASS NEWCLASS
DO SMSMSG   = ID 1  MESSAGE OVERRIDE ALL  ACS ROUTINES
DO
===========================================================================
DAYS                                                          DCAL
                                                                    AND/OR
WDAYS                                                         WCAL
MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
DATES
CONFCAL          SHIFT
ENVIRONMENT SMFID      SYSTEM
===========================================================================
IN
TIME FROM      UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y
======= >>>>>>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<<<<<< =====

DO SMSMSG: Automated Console Action Parameter

Defines and generates a message to be displayed in the job log of a new data set.

Figure 169 DO SMSMSG Parameter Format

Optional. Type SMSMSG in the DO field and press Enter. The subparameters shown in Table 140 are displayed:

Table 140 DO SMSMSG Subparameters

General Information

DO SMSMSG can be used only in ON SMS rules.

The message specified in the MESSAGE subparameter, can be used to provide informative text regarding data set allocation. Up to six sequential lines of SMS message text can be written. Specify the sequential number of the line of message text in the ID field. Information about the data set allocation can then be viewed and saved.

The messages appear on the TSO screen, or in the job log under the following message IDs:

• IGD1004I, for Data class selection

• IGD1005I, for Storage class selection

• IGD1006I, for Management class selection

COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
ON SMS      = DSN.SMS.FILE
   ACS CALL ALL      JNAME MYJOBNAM JTYPE   SMFID      SYSTEM
   DDNAME  DDNAME    DSORG PDS      UNIT UNIT          DS-TYPE TEMP
   PGM               USER  GTUSER                              And/Or/Not
OWNER N18A     GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION
===========================================================================
DO SMSCLASS = ID 01 CLASS NEWCLASS
DO SMSMSG   = ID 1  MESSAGE OVERRIDE ALL ACS ROUTINES
DO SMSMSG   = ID 2  MESSAGE USER DEFINED VALUES USED
DO
===========================================================================
DAYS                                                          DCAL
                                                                   AND/OR
WDAYS                                                         WCAL
MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
DATES
CONFCAL          SHIFT
ENVIRONMENT SMFID      SYSTEM
===========================================================================
IN
TIME FROM      UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y
======= >>>>>>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<<<<<< =====

DO SNMP: Automated Console Action Parameter

Sends an SNMP trap message to specified recipients.

Figure 171 DO SNMP Parameter Format

Optional. Type SNMP in the DO field and press Enter. The subparameters shown in Table 141 are displayed.

Table 141 DO SNMP Subparameters

General Information

A message is sent to the required SNMP trap message destination when the accompanying ON statement criteria are satisfied.

TO Subparameter

To send an SNMP trap message, set this subparameter to the full SNMP name or name and address. The SNMP facility first searches the IOASNMP Dynamic Destination table for the specified destination. If the table contains an entry that matches the value set in the TO subparameter, the content of the entry is used as the target for the SNMP trap message. The entire TO field is used.

If the IOASNMP Dynamic Destination table does not contain a matching entry, the SNMP facility uses the specified value. It then creates a destination message and passes it to the SNMP server, which in turn sends the message to that destination.

For more information about the SNMP Dynamic Destination Table, see the IOA administration chapter in the INCONTROL for z/OS Administrator Guide.

URGENCY Subparameter

The value of the URGENCY subparameter indicates the urgency level of the message. In addition, you can control which messages are displayed when the IOA Log file is accessed, according to urgency. Urgent and very urgent messages are highlighted on the screen. For more details, see IOA Log Facility.

RL: IEF450I    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
-------------------------------------------------------------------------------
ON MESSAGE  = IEF450I
 JNAME          JTYPE      SMFID        SYSTEM          USERID
 ROUTE          DESC       CONSOLEID    CONSOLE
 APPEARED       TIMES IN      MINUTES                        And/Or/Not
OWNER N18B     GROUP                         MODE PROD    RUNTSEC
THRESHOLD
DESCRIPTION INFORM PATROL AGENT WIEN CICS ABENDED
DESCRIPTION
=============================================================================
DO SNMP     = TO PATROL.AGENT.SNMP     PORT       URGENCY V SYSTEM
 MESSAGE %%JOBNAME ENDED S%%$SABEND U%%$UABEND RC%%$STEPCC
DO
=============================================================================







FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  12.33.38

DO STOPJOB: Automated Console Action Parameter

Stops execution of the job under which the rule is executing, after the current step is completed.

Figure 173 DO STOPJOB Parameter Format

Optional. Type STOPJOB in the DO field and press Enter. A DO STOPJOB statement has no subparameters.

General Information

Control-O rules are triggered by messages, commands and events under the address space that issued the message or command. When the rule executes a statement that causes it to enter Wait mode, such as

• DO COMMAND

• DO KSL

• DO SHELL with WAITMODE set to Y

• DO TSO with WAITMODE set toY

• DO WAIT

• DO ASKOPER

the rule may resume execution in an address space different from the one under which it was originally triggered. Therefore, when specifying DO STOPJOB statements, special care should be taken to ensure that the correct job is terminated by the statement.

RL: CHK0007E   LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = CHK0007E
     JNAME PROD*    JTYPE J       SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION STOPJOB EXAMPLE
  DESCRIPTION   PREVENT EXECUTION OF THE NEXT STEPS OF A JOB WHENEVER
  DESCRIPTION   ERROR MESSAGE CHK0007E OCCURS.
  DESCRIPTION
  ===========================================================================
  /* STOP THE JOB
  DO STOPJOB
  /* WRITE A MESSAGE TO THE IOA LOG
  DO SHOUT    = TO U-IOAADMIN        URGENCY R SYSTEM          CTO282I
     MESSAGE JOB %%$JOBNAME WAS STOPPED, REASON : %%$MSGID
  DO
  ===========================================================================

FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  10.06.36

DO SYSREQ: Automated Console Action Parameter

Executes a variety of system related functions and queries. The ENQINFO function (a request to Extract Enqueue information) is currently implemented.

Figure 175 DO SYSREQ Parameter Format

Optional. Type SYSREQ in the DO field and press Enter. The subparameters shown in Table 142 are displayed.

Table 142 DO SYSREQ Subparameters

General Information

The DO SYSREQ=ENQINFO execution call sets the following AutoEdit system variables:

• %%$SYSRC
  Completion code: 0 for successful completion

  All other return codes indicate an internal error and should be reported to BMC Customer Support.

• %%$SYSLINES
  Number of lines selected in the ENQ request. A value of0 means that no ENQ entry matches the selection criteria.

• %%$SYSLINEn
  Information about a specific ENQ entry, contained in line numbern.

  A %%$SYSLINEn is saved for each ENQ entry. However, lines that did not match the selection criteria, such as OWNER lines, when only WAITER lines were specified, are not included in the %%$SYSLINES AutoEdit variable that contains the count of ENQ entries that matched the selection criteria.

Data in the %%$SYSLINEn variables can be extracted as a whole string, or the data string can be broken up into words, using the %%$PARSE function with templates. For more information, see %%$PARSE in %%$PARSE. A built-in template, %%$EITEMPLATE, is provided, to assist in writing the rule and reduce the amount of code in the rules. The layout of the %%$SYSLINEn and %%$EITEMPLATE AutoEdit variables corresponding to the DO SYSREQ=ENQINFO option is detailed below.

Table 143 Layout of AutoEdit Variable %%SYSLINEn

Table 144 Layout of AutoEdit Variable %%$EITEMPLATE

The variables listed in the template layout above contain, after parsing, the value of the various fields described in the layout of the %%$SYSLINEn variable. These variables can be accessed by prefixing them with %%.

RL: WHOHAS     LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
  +-----------------------------------------------------------------------------+
  ON RULE     = WHOHAS
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION FIND WHO OWNS A DATASET.
  DESCRIPTION   THIS RULE RECEIVES AS PARAMETER A DATASET NAME,
  DESCRIPTION   FINDS WHAT DATASETS ARE HOLDING THE JOB AND RETURNS
  DESCRIPTION   THE JOBNAME OF THE FIRST OWNER IN VARIABLE %%DS_NAME.
  DESCRIPTION   WHEN THE DATASET IS NOT HELD BY ANY JOB, THE VALUE IS
  DESCRIPTION   SET TO 'NONE'.
  DESCRIPTION
  ===========================================================================
  /* GET DATASET NAME PASSED AS PARAMETER
  DO SET      = %%DSNAME = %%$ARGS                                  GLOBAL  N
  /* GET ALL THE OWNERS OF THE DATASET
  DO SYSREQ   = ENQINFO    STATUS OWNER      SCOPE ALL       JOBNAME
     QNAME      SYSDSN     RNAME %%DSNAME
  /* GET THE FIRST OWNER
  IF       %%$SYSLINES GE# 1
  DO SET      = %%$PARSE %%$SYSLINE1 %%$EITEMPLATE                  GLOBAL  N
  DO SET      = %%DS_OWNER = %%EIJOBN                               GLOBAL  N
  ELSE
  /* NO JOB IS OWNING THE DATASET: SET OWNER TO 'NONE'
  DO SET      = %%DS_OWNER = NONE                                   GLOBAL  N
  ENDIF
  /* WRITE A LOG ENTRY TO THE IOA LOG
  DO SHOUT    = TO OPER              URGENCY R SYSTEM             CTO282I
     MESSAGE DATASET %%DATASET IS HELD BY %%DS_OWNER
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  10.58.07

DO TERMINAT: Automated Console Action Parameter

Terminates the process of the triggering rule, and all called rules if any, and continue to next rule.

Figure 177 DO TERMINAT Parameter Format

Optional. Type TERMINAT (or its abbreviation TE) in the DO field and press Enter.

General Information

DO TERMINAT terminates processing of the rule and all calling rules, if any. Control is returned directly to Control-O to search for more rules, without going back to the calling rules. DO TERMINIT can be specified in any rule.

RL: WHOHAS     LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = CTORMTCMD *
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOADMIN  GROUP                         MODE LOG     RUNTSEC
  THRESHOLD
  DESCRIPTION RECEIVE CROSS SYSTEM COMMAND            (INTERNAL)
  ===========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO SET      = %%T= . SYS RID PARMS 'CMD=' C                       GLOBAL  N
  DO SET      = %%$PARSE %%$CMD %%T                                 GLOBAL  N
  /* VALIDITY CHECKS
  IF       %%SYS EQ %%$NULL OR %%RID EQ %%$NULL
  DO SHOUT    = TO OPER              URGENCY R SYSTEM          CTO282I
     MESSAGE REMOTE COMMAND REQUEST WITH INSUFFICIENT PARAMETERS - IGNORED
  TERMINAT
  ENDIF
  FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  10.58.07

DO TSO: Automated Console Action Parameter

Specifies a TSO command, CLIST or REXX procedure to be activated.

Figure 179 DO TSO Parameter Format

Optional. Type TSO in the DO field and press Enter. The subparameters described in Table 145 are displayed.

Table 145 DO TSO Subparameters

General Information

A DO TSO statement can be used to initiate any TSO command, CLIST or REXX procedure that does not require terminal input (that is, one that is executable from READY mode without prompting for additional information).

Use of the TSO option can be resource-consuming (because of the nature of TSO). For performance reasons, whenever possible, use regular Control-O functions or Control-M activated tasks.

Control-O AutoEdit variables embedded in a DO TSO statement are automatically resolved (replaced) at time of rule activation. For more information about the AutoEdit facility, see AutoEdit Facility.

Wait Completion Mode

Execution of the DO statements that follow a DO TSO statement can be delayed until the TSO command, CLIST, or REXX procedure has finished executing, thereby enabling checking of the completion code. This delay is achieved by specifying Y (Yes) for the WAITMODE subparameter, which places the rule in Wait (Completion) mode. The TIMEOUT subparameter can be used to specify how long (in seconds) to wait for completion of the TSO command, CLIST, or REXX procedure.

When rule execution is resumed, the %%TSORC AutoEdit system variable will contain either the completion code of the TSO command, CLIST, or REXX procedure, or the value 522, which means that the TIMEOUT limit was reached before completion of the TSO command, CLIST, or REXX procedure.

Wait mode can also be specified for a TSO command, CLIST, or REXX procedure execution by specifying a DO SET=%%WAITTSO = Y statement before the DO TSO statement. Using this method, a TIMEOUT period may be specified through a DO SET %%TIMEOUT=value statement. This method is supported for historical reasons.

Using a Preset Environment

DO TSO statements are executed by Control-O servers. Servers are started tasks that are managed automatically by Control-O. You can define Immediate, Special, and General servers. These server types are discussed in detail in Chapter 5, "Control-O Servers." However, when defining a DO TSO statement, bear in mind the following information:

• Immediate servers

  Immediate servers are useful for either

  • TSO commands, CLIST, or REXX procedures that need to be executed immediately, for example, those that need to bypass the wait queue of the server

  • TSO commands, CLIST, or REXX procedures that should not be executed by a Special or General server, for example, long running scripts that delay the running of other scripts waiting to be executed

  To request an Immediate server, type Y (Yes) in the IMMEDIATE subparameter.

• Special servers

  Special servers are useful when the same environment is used frequently for TSO requests. This generally occurs when different TSO commands, CLIST, or REXX procedures (in the same or different rules) use the same environment. Use of the same environment by many TSO requests improves performance considerably.

  To request a Special server, do the following:

  1. Type N (No) in the IMMEDIATE subparameter, or leave it blank.

  2. Enter the name of the TSO command, CLIST, or REXX procedure that handles the preset environment in the INITPROC subparameter.

  3. Ensure that a Special server with the name specified in the INITPROC subparameter has been defined to Control-O.

• General servers

  General servers are useful when scripts infrequently use a specific environment and/or do not use a preset environment.

  To request a General server, do the following:

  1. Type N (No) in the IMMEDIATE subparameter, or leave it blank.

  2. Ensure that the necessary environment is established by either the script specified in the DO TSO statement or by the TSO command, CLIST, or REXX procedure specified in the INITPROC subparameter.

  3. Ensure that there is no Special server defined to Control-O with the same name as the TSO command, CLIST, or REXX procedure specified in the INITPROC subparameter (if one was specified).

  Whenever INITPROC is specified, Control-O ensures that the indicated TSO command, CLIST or REXX procedure is automatically invoked to maintain the preset environment.

  Ensure that the procedure specified in the DO TSO statement does not perform any of the functions performed by the procedure specified in INITPROC.

  For information on how to define servers, see the INCONTROL for z/OS Installation Guide.

RL: REXX*      LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = REXX*
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION OPERATOR COMMAND TO EXECUTE ANY GIVEN REXX
  DESCRIPTION
  ===========================================================================
  DO TSO      = %%$V2
     WAITMODE   Y                                      TIMEOUT 9999    STOP Y
     INITPROC        SHARELOC Y                        IMMEDIATE Y
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE REXX %%$V2 ENDED WITH RC=%%TSORC
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  18.11.14

DO WAIT: Automated Console Action Parameter

Delays subsequent action until one of the specified events is detected.

Figure 181 DO WAIT Parameter Format

Optional. Type WAIT in the DO field and press Enter. The subparameters described in Table 146 are displayed. A value must be specified for at least one of these subparameters.

Table 146 DO WAIT Subparameters

General Information

DO WAIT subparameters specify when to resume processing (with the next DO statement).

If multiple DO WAIT subparameters are defined, the Wait is terminated (and the next statement is processed) as soon as one of the specified conditions is satisfied.

When the rule resumes execution after DO WAIT, the %%$WAITRC System variable indicates the event caused the end of the wait. Possible values for %%$WAITRC are shown in Table 147.

Table 147 Possible Values for %%$WAITRC

RL: IEF238D    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON MESSAGE  = IEF238D
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION AUTOMATIC HANDLING OF MSG IEF238D
  DESCRIPTION ENSURE THAT THE IEF238D MESSAGE IS REPLIED TO WITHIN 3 MIN.
  DESCRIPTION
  ===========================================================================
  DO WAIT     = REPLY Y              DOM N             TIMEOUT 0180
     MESSAGE
  IF       %%$WAITRC EQ# 522
  DO COMMAND  = R %%$REPLY,CANCEL
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  ENDIF
  DO
===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  15.03.04

DO WHILE / DO ENDWHILE: Automated Console Action Parameter

DO WHILE, and DO ENDWHILE statements enable use of repetition (loop) logic in a Control-O rule. These statements can be used to repeatedly perform other DO actions for as long as a specified condition is met.

Figure 182 DO WHILE/DO ENDWHILE Parameter Format

Type WHILE in the DO field and press Enter. The word DO is replaced by WHILE on the screen. The same will occur when you type ENDWHILE in a DO field.

The basic format of WHILE and ENDWHILE statements is:

Figure 183 Format of WHILE and ENDWHILE Statements

WHILE conditional_expresssion1 [{AND|OR} conditional_expression2] 
DO action
     .
     .
     .
  DO action
ENDWHILE

The WHILE conditional expression has the following format:

WHILE operand operator operand

Valid logical operators are shown in Table 148.

Table 148 DO WHILE and ENDWHILE Logical Operators

Valid Boolean operators are shown in Table 149.

Table 149 DO WHILE and ENDWHILE Boolean Operators

Operators that end with the pound sign (#) are used for numeric comparisons, as opposed to string comparisons.

An operand can be any character string. It can also be composed of AutoEdit symbols. In such cases, it is resolved into a character string before the conditional expression is analyzed at execution time.

Whenever non-numeric comparison operators are specified, operands are compared as character strings from left to right.

An operand cannot be resolved into nulls (as in CLISTs). If it is possible that an operand will resolve into nulls, place a character before the first and second operands.

In the following example, the character B is placed before the two operands:

WHILE B%%A GT B%%C

Each WHILE statement must be terminated with an ENDWHILE statement.

General Information

As long as the WHILE expression is true, commands between the WHILE expression and its matching ENDWHILE statement are repeatedly processed by Control-O.

WHILE statements can be nested providing that each WHILE statement has a corresponding ENDWHILE statement.

WHILE and IF statements can be nested within each other provided that all nesting rules are maintained. A combination of up to 100 nested WHILE and IF statements are permitted.

Control-O detects "infinite loops" that are caused by problematic DO WHILE statements (for example, DO WHILE 1 EQ 1), and stops rule execution.

When DO EXIT for a DO WHILE block is specified, processing of the DO WHILE is ended and rule processing continues after the ENDWHILE statement.

The SHOWNEST Command

To see the nesting levels of DO statements, relative to the nesting level of DO IF and DO WHILE statements, type SHOWNEST (or SH) in the COMMAND field. The nesting levels are displayed to the left of each DO parameter.

Issue the SHOWNEST command again to suppress display of the nesting levels.

RL: FINDVOL*   LIB CTO.PROD.RULES                               TABLE: TEST1
COMMAND ===>                                                    SCROLL===> CRSR
+--------------------------------------------------------------------------+
  ON COMMAND  = FINDVOL*
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION
  ==========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE ISSUING COMMAND D U,DASD,ONLINE
  DO COMMAND  = D U,DASD,ONLINE
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT
     RESPMSG
  DO SET      = %%FLAG = 0                                          GLOBAL  N
  DO SET      = %%I = 1                                             GLOBAL  N
  WHILE    %%I LE# %%$LINES
  DO SET      = %%J = 1                                             GLOBAL  N
  WHILE    %%J LE# %%$WORDS %%$M%%I
  DO SET      = %%T =  %%$W%%J %%$M%%I                              GLOBAL  N
  IF       %%T EQ %%$V2
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE AFFIRMATIVE - %%$V2 IS MOUNTED
  DO SET      = %%FLAG = 1                                          GLOBAL  N
  DO SET      = %%I = 9999                                          GLOBAL  N
  ENDIF
  DO SET      = %%J = %%J %%$PLUS 1                                 GLOBAL  N
  ENDWHILE
  DO SET      = %%I = %%I %%$PLUS 1                                 GLOBAL  N
  ENDWHILE
  IF       %%FLAG EQ# 0
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE NEGATIVE -  %%$V2 IS NOT MOUNTED
  ENDIF
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                18.44.01

RL: SHUTTSO    LIB CTO.PROD.RULES                               TABLE: TEST1
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = SHUTTSO
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE TSO IS BEING SHUT DOWN. SHIFT SUPERVISOR MUST BE NOTIFIED.
  DO SET      = %%RC = 4                                            GLOBAL  N
  WHILE    %%RC NE# 0
  DO ASKOPER  = HAVE YOU NOTIFIED SHIFT SUPERVISOR ? REPLY 'YES' OR 'CANCEL'
  ROUTE       CONSOLEID    CONSOLE                          TIMEOUT 0030
  IF       (%%$ASKRC EQ# 4) AND ((%%$RPLYTXT EQ YES) OR (%%$RPLYTXT EQ CANCEL))
  DO SET      = %%RC = 0                                            GLOBAL  N
  ENDIF
  ENDWHILE
  IF       %%$RPLYTXT EQ YES
  DO COMMAND  = P TSO
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  18.46.46

ENVIRONMENT: Basic Scheduling Parameter

Environment where the current rule should be scheduled for execution.

Figure 184 ENVIRONMENT Parameter Format

Optional. The subparameters described in Table 150 can be specified.

Table 150 ENVIRONMENT Subparameters

General Information

This parameter is especially relevant for sites with more than one system, specifically, more than one Control-O. The values specified for SMF ID and SYSTEM indicate systems where the current rule can be loaded.

If values are specified for both the SMF ID and SYSTEM parameters, these values have an OR relationship. Mask characters can be used to indicate that the rule should be loaded on more than one system.

If no value is specified for either subparameter, the rule is loaded in all systems.

RL: INITMVS1   LIB CTOP.PROD.RULES                              TABLE: ENVIRO
COMMAND ===>                                                    SCROLL===> CRSR
  ON EVENT    = INITMVS1
  OWNER IOAADIM  GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION INITIALIZATION OF CONTROL-O ON MVS1
  DESCRIPTION
  ===========================================================================
  DO RULE     = INIT %%$CONTROLO                              OWNER
     TABLE               LIBRARY
  DO
  ===========================================================================
  DAYS                                                          DCAL
                                                                       AND/OR
  WDAYS   ALL                                                   WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM MVS1
  ===========================================================================
  IN
  TIME FROM      UNTIL           INTERVAL      PRIORITY     CONTINUE SEARCH Y

FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  18.46.46

GROUP: General Parameter

The group name of the rule. It is used to supply a common descriptive name to a group of rules.

Figure 186 GROUP Parameter Format

Optional. This parameter specifies a group name of from 1 through 20 characters (embedded blanks are not permitted).

General Information

The GROUP parameter is used for more convenient rule handling. It enables information retrieval on a the rules of a specific group, usually through the Rule Status screen or the Reporting facility.

The group name appears in all important IOA Log messages relating to the rules of the group.

RL: SPOOL      LIB CTOW.WORKO.RULES                             TABLE: DATES
COMMAND ===>                                                    SCROLL===> CRSR
-------------------------------------------------------------------------------
  ON EVENT    = SPOOL
  OWNER IOAADMIN GROUP JES2                    MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION WARN OPERATOR IF SPOOL IS FULL.
  DESCRIPTION THIS RULE IS ACTIVATED EVERY 30 MINUTES, FROM 0700 TO 1900
  DESCRIPTION WHEN THE PREREQUISITE CONDITION CTO-MONITOR-SPOOL IS ACTIVE
  DESCRIPTION
  ===========================================================================
  DO COMMAND  = $DPSL
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT
     RESPMSG $HASP646
  IF       %%$V2 GE# 70
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE SPOOL IS %%$V2 FULL - PURGE JOBS
  ENDIF
  ENDMSG
  DO
  ===========================================================================
  DAYS                                                          DCAL
 AND/OR
  WDAYS                                                         WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ===========================================================================
  IN        CTO-MONITOR-SPOOL    0101
  TIME FROM 0700 UNTIL 1900      INTERVAL 030  PRIORITY     CONTINUE SEARCH Y
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  17.25.16

IN: Runtime Scheduling Parameter

Specifies prerequisite conditions for rule activation. The rule is activated only if the specified prerequisite conditions exist.

Figure 188 IN Parameter Format

Optional. A prerequisite condition is a descriptive name of from 1 through 20 characters. A date reference is associated with each condition.

prerequisite condition with the NOT symbol (the Ø or ! character) indicates that the activation of the rule is dependent on the inverse of the condition, that is, the nonexistence of the prerequisite condition.

Prefixing prerequisite conditions with the OR symbol ("|") indicates that only one of those "OR" conditions (and all "non-OR" conditions) must exist to trigger the rule.

The date reference for each IN condition is four characters long and is optional. It can be a specific date, in either mmdd or ddmm format, depending on the site standard, or it can have one of the values shown in Table 151.

Table 151 IN Condition DATE Values

General Information

The rule is activated only if all the prerequisite conditions specified in the IN statement exist. If any of the conditions are not satisfied, the rule does not participate in the message or event event scan.

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

IMS-ACTIVE
WEEKEND
JOB-EJGH12-FINISHED
SALARY-OK
BRANCH_TRANSMISSION

Inverse Conditions

In order to activate a rule if the inverse condition is met, specify the NOT symbol Ø (or the ! character) as a prefix to the condition name.

Example

\-Ø CICS-DOWN
\-Ø IMS-ACTIVE

The rule will then be activated only if the prerequisite condition is not present.

Or Relations

If a prerequisite condition starts with the character "|" (hexadecimal 4F), it means that it should be checked, with an OR relation, together with other prerequisite conditions of the same rule, which are also marked with "|."

IN  A  |B
    |C |D
    E

RL: START NE   LIB CTOW.WORKO.RULES                             TABLE: DATES
COMMAND ===>                                                    SCROLL===> CRSR
------------------------------------------------------------------------------
  ON COMMAND  = START NETVIEW
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP NETVIEW                 MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION PREVENT START-UP OF NETVIEW IF IT IS ALREADY ACTIVE
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE START COMMAND SUPPRESSED. NETVIEW IS ALREADY ACTIVE
  DO
  ===========================================================================
  DAYS                                                          DCAL
                                                                         AND/OR
  WDAYS                                                         WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ==========================================================================
  IN        CTO-NETVIEW-ACTIVE   STAT
  TIME FROM      UNTIL           INTERVAL      PRIORITY 99  CONTINUE SEARCH N
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  17.24.07

INTERVAL: Runtime Scheduling Parameter

Specifies the number of minutes to wait between reactivations of the rule.

Figure 190 INTERVAL Parameter Format

Optional. The INTERVAL parameter specifies a 3-digit number. The default is 0 (zero).

General Information

When a rule is activated, Control-O waits at least INTERVAL minutes before it attempts the next activation of the rule. During the interval, the rule is "dormant."

After the interval has passed, Control-O starts to use the rule again during message and event scan.

The specified interval does not indicate an exact duration during which the rule is inactive. Therefore, an interval of 1 minute means that once the rule is triggered, it will be inactivated during the current clock minute. For example, if the rule was triggered at 10:34:55, then by 10:35:00 it is eligible to be triggered again, although only 5 seconds have actually passed since the previous triggering.

The reactivation of the rule does not occur exactly at the minute boundary because Control-O monitor is dormant most of the time and it "wakes up" every period specified by the INTERLVO parameter. When it wakes up, it checks which rules are to be reactivated. So if INTERLVO is 4 seconds, Control-O might wake up at 10:34:58 and then again at 10:35:02, so that the rule is activated only at 10:35:02.

Non-cyclic events

When specifying a non-cyclic rule, the following concepts apply:

• Activating a rule means that its state is set to ACTIVE (eligible for triggering).

• An INACTIVE rule cannot be triggered.

• Rules can be ACTIVE only between the times specified by the TIME FROM and UNTIL parameters.

• The TIME FROM, UNTIL, and INTERVAL parameters can be used to place the rule in an ACTIVE or INACTIVE state, based on the time-related parameters.

INTERVAL can be used to further limit rule activation as follows:

• If the rule is ordered not during the TIME FROM –> UNTIL period, the rule is set to ACTIVE at TIME FROM.

• At UNTIL, the rule is set to INACTIVE. It will be activated again at TIME FROM, unless the number of minutes passed between the last activation and TIME FROM is less than INTERVAL minutes. In this case, it will be activated at the last activation time + INTERVAL.

• If the rule was ordered between TIME FROM and UNTIL, it is activated immediately.

• If the rule is triggered, its state is set to INACTIVE.

• The rule is activated again INTERVAL minutes after the last time it was activated, as long as the time of day is between TIME FROM and UNTIL.

Cyclic Events

When specifying a cyclic rule, the TIME FROM parameter is used to determine the start time of the cycle. The INTERVAL parameter then determines how many minutes should lapse, that is, how many minutes Control-O should wait, before the next activation of the rule.

If the rule is ordered after the specified TIME FROM, the rule is activated immediately. In this case, the interval is based on the time of rule ordering. The cycle will occur at fixed intervals, but not at a specifically designated time.

To run a cyclic event rule at designated times, for example, at exactly 2:00, 3:00, and so on, the EVENT name prefix FIXT must be specified. Even if the rule is ordered after the specified TIME FROM, the rule will not be executed until the next interval as calculated from the starting time.

RL: SPOOL      LIB CTOW.WORKO.RULES                             TABLE: DATES
COMMAND ===>                                                    SCROLL===> CRSR
-------------------------------------------------------------------------------
  ON EVENT    = SPOOL
  OWNER IOAADMIN GROUP JES2                    MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION WARN OPERATOR IF SPOOL IS FULL.
  DESCRIPTION THIS RULE IS ACTIVATED EVERY 30 MINUTES, FROM 0700 TO 1900
  DESCRIPTION WHEN THE PREREQUISITE CONDITION CTO-MONITOR-SPOOL IS ACTIVE
  DESCRIPTION
  ===========================================================================
  DO COMMAND  = $DPSL
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT
     RESPMSG $HASP646
  IF       %%$V2 GE# 70
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE SPOOL IS %%$V2 FULL - PURGE JOBS
  ENDIF
  ENDMSG
  DO
  ===========================================================================
  DAYS                                                          DCAL
                                                                        AND/OR
  WDAYS                                                         WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ===========================================================================
  IN        CTO-MONITOR-SPOOL    STAT
  TIME FROM 0700 UNTIL 1900      INTERVAL 030  PRIORITY     CONTINUE SEARCH Y
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  17.25.16

MODE: General Parameter

Specifies rule operation mode.

Figure 192 MODE Parameter Format

The MODE parameter is mandatory. Valid values are shown in Table 152.

Table 152 MODE Parameter Valid Values

General Information

TEST mode enables you to test the effects of a rule definition without actually performing the DO console actions. Assignment of Global variables is performed.

LOG mode performs the same as PROD mode but also logs events and actions to the test journal for test tracking purposes.

If the Control-O Automation Log facility is active, events and actions are recorded in the Automation Log. If the Automation Log facility is not active, this information is written to the Control-O monitor SYSOUT referenced by the DAACTLOG DD statement. For more information, see the description of controlling the automation log facility in the Control-O chapter of the INCONTROL for z/OS Administrator Guide.

The operation mode of a rule can be changed temporarily after a rule is ordered:

• The operation mode for specific rules can be changed by the M (Mode) option in the Rule Status screen. For more information, see Options of the Rule List Screen.

• The operation mode can be changed globally for all active rules through the following operator command:

  Copy

  F CONTROLO,LOG=ALL|DEFAULT|TRIGGER

For more information, see the description of controlling rule operation mode in the Control-O chapter of the INCONTROL for z/OS Administrator Guide.

RL: SPOOL      LIB CTOW.WORKO.RULES                             TABLE: DATES
COMMAND ===>                                                    SCROLL===> CRSR
-------------------------------------------------------------------------------
  ON EVENT    = SPOOL
  OWNER IOAADMIN GROUP JES2                    MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION WARN OPERATOR IF SPOOL IS FULL.
  DESCRIPTION THIS RULE IS ACTIVATED EVERY 30 MINUTES, FROM 0700 TO 1900
  DESCRIPTION WHEN THE PREREQUISITE CONDITION CTO-MONITOR-SPOOL IS ACTIVE
  DESCRIPTION
  ===========================================================================
  DO COMMAND  = $DPSL
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   Y             WAITRESP Y            TIMEOUT
     RESPMSG $HASP646
  IF       %%$V2 GE# 70
  DO SHOUT    = TO OPER              URGENCY R SYSTEM           CTO282I
     MESSAGE SPOOL IS %%$V2 FULL - PURGE JOBS
  ENDIF
  ENDMSG
  DO
  ===========================================================================
  DAYS                                                          DCAL
                                                                       AND/OR
  WDAYS                                                         WCAL
  MONTHS  1- Y 2- Y 3- Y 4- Y 5- Y 6- Y 7- Y 8- Y 9- Y 10- Y 11- Y 12- Y
  DATES
  CONFCAL          SHIFT
  ENVIRONMENT SMFID      SYSTEM
  ===========================================================================
  IN        CTO-MONITOR-SPOOL    STAT
  TIME FROM 0700 UNTIL 1900      INTERVAL 030  PRIORITY     CONTINUE SEARCH Y
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  17.25.16

MONTHS: Basic Scheduling Parameter

Months of the year when the rule should be scheduled for execution.

Figure 194 MONTHS Parameter Format

Optional. Each month in the year is identified separately (represented by numbers 1 through 12) and a value can be specified for each month. Valid values are:

• Y (Yes) – Schedule the rule in that month. Default.

• N (No) – Do not schedule the rule in that month.

General Information

The rule is scheduled for execution only during the months when a value of Y (Yes) is specified.

When the MONTHS parameter is used, at least one of the following must be specified:

• DAYS

• DCAL

• WDAYS

• WCAL

When specified with one of these parameters, the MONTHS parameter works as a filter to limit when the rule can be activated.

The MONTHS parameter is ignored when periodic values are specified in the DAYS or WDAYS parameter.

MONTHS 1-N 2-N 3-Y 4-N 5-N 6-N 7-N 8-N 9-Y 10-N 11-N 12-N

ON Statement: Message/Event Selection Parameter

Specifies conditions under which the rule is performed. If the conditions are satisfied, Control-O performs the specified DO actions.

Figure 195 ON Statement Format

Type one of the options in the ON field and press Enter.

Valid options are described briefly in Table 153.

Table 153 ON Statement Options

General Information

When you specify an ON parameter and press Enter, additional fields (subparameters) that are relevant to the parameter 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 specified using the And/Or/Not option, except if an ON EVENT or ON RULE statement is specified. No other ON statements can be specified with an ON EVENT or ON RULE statement.

The first ten characters of the message ID, string, command, or event name will appear as the name of the rule in the Rule List and Rule Status screens.

AutoEdit Variables

Control-O AutoEdit System or Global variables that are embedded in the message ID, string or command name are automatically resolved (replaced) at the time of rule ordering (not rule activation). For more information about AutoEdit variables, see AutoEdit Facility.

And/Or/Not Subparameter

This subparameter enables the specification of multiple ON statements.

The And/Or/Not subparameter uses standard Boolean logic, as described in Table 154.

Table 154 And/Or/Not Subparameter Operators

And and Not are applied before Or.

Not means And Not as follows:

• 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 reduces the amount of redundant data in the Control-O Rules library and improves rule management.

ON MESSAGE… 
AND 
ON COMMAND

ON DSNEVENT JOBA STEPA 
AND 
ON DSNEVENT JOBA STEPB

Character Masking

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 MESSAGE …AND
ON COMMAND
ON DSNEVENT  JOBA  STEPA
AND
ON DSNEVENT  JOBA  STEPB

ON AOREQ: Message/Event Selection Parameter

Indicates that this rule is triggered by MAINVIEW AutoOPERATOR only, as designated in its Runtime Scheduling parameters.

Figure 196 ON AOREQ Parameter Format

Optional. Type AOREQ (or its abbreviation AO) in the ON field and press Enter.Specify the following subparameter to the right of the = prompt:

Table 155 ON COMMAND Subparameters

General Information

The AOREQ identifier is a name assigned to the request characterized in the SET IOA variable sentence in the AutoOPERATOR rule for scheduling parameters (such as prerequisite conditions or time considerations).

This option is particularly useful for customers who have both AutoOPERATOR and Control-O or Control-M with CMEM and need to perform actions supported by Control-M, Control-O, or CMEM.

AOREQ rules are supplied as part of AutoOPERATOR version 6.5 and later.

ON COMMAND: Message/Event Selection Parameter

Specifies a command whose appearance triggers execution of the rule.

Figure 197 ON Command Format

Optional. Type COMMAND (or its abbreviation CO) in the ON field and press Enter. The following subparameters are displayed:

Table 156 ON COMMAND Subparameters

General Information

CONSOLEID Subparameter

During system initialization, each console on the system is assigned a console identifier by z/OS. This identifier (xx) is a 2-digit number from 00 through 99 that corresponds to the position of the CONSOLE statement in member CONSOLxx in the SYS1.PARMLIB library.

Only commands issued from the specified console IDs can trigger the rule.

CONSOLE Subparameter

This is the name that is assigned to the console. A valid name contains 2 to 8 alphanumeric characters.

Only commands issued from the specified console name can trigger the rule.

SYSTEM Subparameter

The name specified by the SYSTEM subparameter is the unique system name of the z/OS image in the Sysplex environment.

When a system name is specified for the SYSTEM subparameter, commands issued by the specified system can trigger rules. However, if no system is specified, only commands originally issued on the current system are used.

SMFID Subparameter

Each computer in a complex installation is assigned an SMF identifier of from 1 through 4 characters.

If SMFID is specified, only commands issued from the specified SMF IDs will trigger the rule.

Suppressing a LOGON command

Use an ON MESSAGE statement to suppress the LOGON messages appearing in the SYSLOG.

ON MESSAGE=LOGON
DO DISPLAY=SUPPRESS Y

ON COMMAND=LOGON
DO DISPLAY=SUPPRESS Y

Dealias Feature

Most z/OS, JES2, and JES3 operator commands can be specified in more than one format:

• z/OS and JES3 commands:
  These commands usually have two formats – a full name format and a shorter format known as an alias. For example, the RESET z/OS command has the alias E.

• JES2 commands:
  These commands can contain embedded backspace characters.

• z/OS, JES2 and JES3 commands:
  These commands can contain a variable number of blank spaces between parameters.

Control-O provides a Dealias feature that recognizes and converts the various formats of a command. For a list of commands for which dealiasing is supported, see List of Commands for Which Dealiasing Is Supported.

The Dealias feature edits commands in the following instances:

• during rule definition in Screen OR
  Any reference to a command in alias form is automatically changed to its full name in the ON COMMAND statement.

• when a table or rule is ordered or forced
  Any command in alias format is changed to the corresponding full name format command.

• when an operator command is intercepted by Control-O
  If it is in alias format, it is brought to its full name format before the rules are scanned.

• when an ID is specified as a show criteria in the Automation Log

RL: SHUTSYS    LIB CTO.PROD.RULES                               TABLE: JOB
COMMAND ===>                                                    SCROLL===> CRSR
+-----------------------------------------------------------------------------+
  ON COMMAND  = SHUTSYS
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION A NEW COMMAND TO SHUTDOWN THE SYSTEM
  DESCRIPTION
  ===========================================================================
  DO DISPLAY  = SUPPRESS Y ROUTE     DESC    CONSOLEID    CONSOLE
     SYSTEM
  DO COMMAND  = $PI
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  DO COMMAND  = $PPRT
     WAIT        CONSOLEID    CONSOLE          SYSTEM
     WAITMODE   N
  DO SHOUT    = TO OPER2             URGENCY R SYSTEM          CTO282I
     MESSAGE SYSTEM IS BEING SHUT DOWN
  DO
  ===========================================================================
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF               18.46.46

ON CTOPCMSG: Message/Event Selection Parameter

Specifies the message, sent by Control-M/Links for Windows NT, the appearance of which triggers execution of the rule.

Figure 199 ON CTOPCMSG Parameter Format

Optional. Type CTOPCMSG, or its abbreviation CT, in the ON field and press Enter. The subparameters shown in Table 157 are displayed.

Table 157 ON CTOPCMSG Subparameters

General Information

CONSOLEID Subparameter

During system initialization, each console on the system is assigned a console identifier by z/OS. This identifier (xx) is a 2-digit number from 00 through 99 that corresponds to the position of the CONSOLE statement in the CONSOLxx member in the SYS1.PARMLIB library.

Only messages issued from the specified console IDs can trigger the rule.

CONSOLE Subparameter

This is the name that is assigned to the console. A valid name contains 2 to 8 alphanumeric characters.

Only messages issued from the specified console name can trigger the rule.

SYSTEM Subparameter

The name specified by the SYSTEM subparameter is the unique system name of the z/OS image in the Sysplex environment.

When a system name is specified by the SYSTEM subparameter, messages issued on the specified system can trigger rules. However, if no system is specified, only messages originally issued on the current system are used.

SMFID Subparameter

Each computer in a complex installation is assigned an SMF identifier from 1 through 4 characters in length.

If SMFID is specified, only messages issued from the specified SMF IDs will trigger the rule.

DO  CONTROLO: ADDCOND condition-name  date

RL: ADDCOND*   LIB CTOP.PROD.RULES                            TABLE: SCREENS
COMMAND ===>                                                  SCROLL===> CRSR
+--------------------------------------------------------------------------+
  ON CTOPCMSG = ADDCOND*
     JNAME          JTYPE         SMFID        SYSTEM
     ROUTE          DESC          CONSOLEID    CONSOLE
     APPEARED       TIMES IN      MINUTES                        And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
  THRESHOLD
  DESCRIPTION
  ==========================================================================
  DO COND     = %%$V2                ODAT +
  DO
  ==========================================================================

FILL IN RULE DEFINITION. CMDS: EDIT , SHPF , SCHED , OPT             17.01.15

ON DSNEVENT: Message/Event Selection Parameter

Specifies a data set disposition event as a selection criteria for the execution of the rule.

Figure 201 ON DSNEVENT Parameter Format

Optional. Type DSNEVENT (or its abbreviation D) in the ON field and press Enter. The subparameters shown in Table 158 are displayed.

Table 158 ON DSNEVENT Subparameters