Component Details

This chapter includes the following topics:

• Control-O/COSMOS Workflow

  • Assume that object CICSTEST has a current status of DOWN and its desired status is DOWN. No further action (regarding CICSTEST) is necessary. However, if the operator changes the desired status of CICSTEST to UP, the following events occur:

• Control-O/COSMOS Modes

• Control-O/COSMOS Databases

  • Creating and Maintaining Object Databases

  • Creating and Maintaining the Prerequisite Database

  • Creating and Maintaining Method Databases

• Control-O/COSMOS Rules

  • General Organization of the Control-O/COSMOS Rules

  • COSRUL Rule

  • COSFSMAC Rule

  • Method Rules

  • Control-O/COSMOS Initialization Rules

  • Control-O/COSMOS Object Update Rules

  • User-Defined Action Rule COSACT98

  • Miscellaneous Rules

  • AutoEdit Variables Used by Control-O/COSMOS Rules

• Control-O/COSMOS Commands

  • COSINI Command – Starting Control-O/COSMOS

  • COSTERM Command – Stopping Control-O/COSMOS

  • COSBOUNZ Command – Bring Down and Restart Control-O/COSMOS

  • COSDB Command

  • COSCMD Command

• Supporting Multiple Control-O/COSMOS Instances

  • Control-O/COSMOS Command Prefix

Control-O/COSMOS Workflow

Normally Control-O/COSMOS brings objects to a predefined desired status during IPL. However, the production environment is dynamic, and the desired status of objects can change. The following workflow is therefore used to manage Control-O/COSMOS-controlled objects:

Figure 9 Control-O/COSMOS Workflow

1. Control-O/COSMOS periodically scans the Object database.

2. If an object has a current status of UP and a desired status of DOWN, or vice versa, Control-O/COSMOS scans the Prerequisite database to determine the prerequisites for a change to the desired status, and then checks the relevant Object databases to determine if the prerequisites are satisfied.

   • If prerequisites for an object are not satisfied, no action is performed on that object.

3. Control-O/COSMOS scans the Method database to determine the method for changing the status of the object to its desired status.

   • If no method is found that matches an object in its desired status, no action is performed on the object.

4. If an appropriate method is found, Control-O/COSMOS triggers the Control-O/COSMOS rule that performs the method.

User requests (for example, Control-O/COSMOS commands or options in a Control-O/COSMOS online screen) can also be used to trigger rules that modify the contents of a Control-O/COSMOS Object database.

Control-O/COSMOS Modes

A Control-O/COSMOS mode is specified for each Control-O/COSMOS-controlled object in the Object databases. The Control-O/COSMOS mode determines if the object is handled in a special way (for example, if prerequisites are ignored). For example, a Control-O/COSMOS mode can indicate not to modify an object or not to check prerequisites before an object is modified.

A Control-O/COSMOS mode can be modified using an option in a Control-O/COSMOS screen, or using a Control-O/COSMOS command such as COSDB or COSCMD, described in COSDB Command and COSCMD Command, respectively.

The following modes are available:

Table 12 Control-O/COSMOS Modes

A Control-O/COSMOS mode is also specified for each Object database and for the entire Control-O/COSMOS facility.

The mode specified for the Control-O/COSMOS facility has a higher priority than the mode specified for each Object database.

• If mode HELD, FORCE_OK or NOPRE is specified for the Control-O/COSMOS facility, this mode overrides the mode specified for each Object database.

• If mode FREE is specified for the Control-O/COSMOS facility, the mode specified for each Object database determines the handling of Control-O/COSMOS-controlled objects.
  The mode specified for each Object database has a higher priority than the mode specified for each Control-O/COSMOS-controlled object.

• If mode HELD, FORCE_OK or NOPRE is specified for the Object database, this mode overrides the mode specified for each object.

• If mode FREE is specified for Control-O/COSMOS, and mode FREE is specified for an Object database, objects defined in the database are handled according to the mode specified in each row of that Object database (that is, object-specific mode).

When a mode is specified for all of Control-O/COSMOS or for an Object database, the mode is not changed in each row in the Object databases.

Control-O/COSMOS Databases

The following types of databases must be created:

• At least one Object database

• At least one Method database

• The Prerequisite database

Member COSMOLST in the Control-O PARM library contains definitions of all databases used by Control-O/COSMOS. When a new database is created, a row describing it must be added to member COSMOLST, described in Control-O/COSMOS Initialization Rules.

Detailed descriptions of the Control-O/COSMOS databases, including their creation and maintenance, are provided below.

Creating and Maintaining Object Databases

Control-O/COSMOS Object databases contain information about the objects (started tasks, terminals, and so on) managed by Control-O/COSMOS.

Object databases are normally created in pairs. Each pair consists of the following:

• Source Object database

• Contains all object names and pertinent information as a permanent database.

• Working Object database

• Working copy of the Source Object database used to manage objects during Control-O/COSMOS operations. This copy is modified by Control-O/COSMOS at regular intervals to reflect changes in the production environment.

Working Object databases are required and are used by Control-O/COSMOS. Source Object databases can be used, but are not required.

Control-O/COSMOS determines what actions are performed, by scanning the Working Object databases. All information in the Working Object databases is copied from the Source Object database each time Control-O/COSMOS is activated. You can use other means to create the Working Object database. For example, the Working Object database can be created dynamically.

Creating rows with a rule can create a Working Object database. For example, an operator command can be issued to display objects and a command response can be used to add rows to the list of objects to be managed.

An Object database, describing started task (STC) objects at your site, can be created using the SYSIMAGE facility, and can be maintained through the Variable Database Definition facility. This Object database can be modified, and other Object databases can be created, using the Variable Database facility.

Maintaining separate Source and Working Object databases provides the following advantages:

• Saves disk space.

• The Working Object database contains much information that is meaningless after Control-O/COSMOS is brought down. The Source Object database contains only the information necessary for re-creation of Working Object databases.

• Enables management of objects using one Source Object database.

• The Source Object database is used to upload information for multiple Working Object databases (that is, one on each CPU) when Control-O/COSMOS is started. Using one Source Object database avoids duplicate definitions in multi-CPU and Sysplex environments.

Example

VTAM normally depends on JES2 no matter which CPU of the system is involved. Therefore, if an object named JES2 is appropriately defined in the Source Object database, the definition of JES2 is copied to the Working Object database of every CPU.

Source Object Databases

When Control-O/COSMOS is started, information is copied from the Source Object databases to the Working Object databases.

Addition, modification and deletion of Control-O/COSMOS-controlled objects are performed on only the Source Object databases. These operations are performed using the Variable Database Definition facility (screen IV), described in Online Facilities.

Each object is described by a row in the Source Object database. The following columns must be included in the Source Object database:

Table 13 Required Columns in the Source Object Database

The following screen segment contains sample content of a Source Object database (as displayed in the Variable Database screen):

Figure 10 Source Object Database Example

ROW       CPU        OBJECT    DESIRED   ATIPL     NOTIPL    MODE     CLASS   
    00001000  ALL        JES2      DOWN      UP        DOWN      FREE     BASE
    00002000  ALL        VTAM      DOWN      UP        DOWN      FREE     COMM
    00003000  ALL        CICP      DOWN      UP        DOWN      FREE     DC
    00004000  ALL        CICT      DOWN      UP        DOWN      FREE     DC
    00005000  ALL        TCP       DOWN      UP        DOWN      FREE     COMM
    00006000  ALL        IDMS      DOWN      UP        DOWN      FREE     DB
    00007000  ALL        IMS       DOWN      UP        DOWN      FREE     DB
    00008000  ALL        NETV      DOWN      UP        DOWN      FREE     COMM
    00009000  ALL        OMON      DOWN      UP        DOWN      FREE     IOA

Information in the Source Object database is copied to columns with the same names in the Working Object database. If a column exists in the Source Object database, and no column with the same name is found in the Working Object database, information in that column is not copied.

Working Object Databases

Working Object databases are scanned periodically by Control-O/COSMOS to determine if specified objects are in their desired statuses. When Control-O/COSMOS is activated, rows containing object-related information are copied from the Source Object Databases to Working Object databases.

Most columns in Working Object databases contain information copied from the Source Object databases. However, certain additional columns are added for information required for ongoing Control-O/COSMOS operations.

Each Working Object database must contain all columns in the Source Object database except for ATIPL and NOTIPL. In addition, the following columns must appear in the Working Object database:

Table 14 Working Object Database – Column Descriptions

For started task objects, it is recommended that the following columns be included:

Table 15 Started Task Objects – Columns

The following screen segment contains sample content of a Working Object database (as displayed in the Object Status screen):

Figure 11 Working Object Database Example

   O OBJECT   CURRENT  DESIRED  CLASS    MODE     STATUS      JES2     UP       UP       BASE     FREE     CD=OU
      VTAM     DOWN     UP       COMM     FREE     CD=DU PR=JES2
      CICP     DOWN     UP       DC       FREE     CD=DU PR=VTAM APLCICP
      CICT     DOWN     UP       DC       FREE     CD=DU PR=VTAM
      TCP      DOWN     UP       COMM     FREE     CD=DU PR=VTAM APLTCP
      IDMS     DOWN     UP       DB       FREE     CD=DU PR=JES2
      IMS      DOWN     UP       DB       FREE     CD=DU PR=JES2
      NETV     DOWN     UP       COMM     FREE     CD=DU PR=VTAM JES2 APLNETV
      OMON     DOWN     UP       IOA      FREE     CD=DU PR=JES2 APLOMON
      CTM      DOWN     UP       IOA      FREE     CD=DU PR=JES2
      CTD      DOWN     UP       IOA      FREE     CD=DU PR=JES2
      ADAB     DOWN     UP       DB       FREE     CD=DU PR=JES2
      DB2T     DOWN     UP       DB2      FREE     CD=DU PR=JES2

Multiple Source and Working Object Databases

Multiple Source Object databases can be defined for Control-O/COSMOS objects. The number of Source Object databases appropriate for your site depends on the nature of the objects to be managed and the way in which Control-O/COSMOS is to be implemented. Definition of multiple Source Object databases enables you to:

• Separate objects of different types (for example, started tasks and VTAM LUs).

• Specify different UP/DOWN status names. For example, for objects of a certain type ONLINE/OFFLINE or ACTIVE/INACTIVE may be appropriate.

• Define different columns in the Object databases. For example, a column for started task objects containing the open reply ID of the started task (if any). A reply ID is meaningful only for a started task but is meaningless for a VTAM LU.

Objects defined in each Source Object database are copied to Working Object databases when Control-O/COSMOS is initialized.

In a multi-CPU environment, a single Source Object database (stored on disk) can be used to generate a Working Object database (in memory only) in each CPU. This simplifies object management by enabling management of Object databases in multiple CPUs using a single central file (meaning, a Source Object database).

Creating and Maintaining the Prerequisite Database

The Control-O/COSMOS Prerequisite database contains prerequisites for Control-O/COSMOS-controlled objects. Only one Control-O/COSMOS Prerequisite database can be defined.

When Control-O/COSMOS determines that an object’s current status does not match its desired status, Control-O/COSMOS checks the prerequisites for that object in the desired status.

The Control-O/COSMOS Prerequisite database determines whether or not an object can be brought to its desired status, and in this way controls:

• Sequence in which objects are activated during IPL.

• Sequence in which objects are deactivated during a shutdown.

Because Control-O/COSMOS can manage more than one Object database, prerequisites can describe dependencies between objects in the same or different Object databases.

Prerequisites and Inverse Prerequisites

A standard Control-O/COSMOS prerequisite specifies a particular object that must be up before another specific object can be brought up.

Unless indicated otherwise, Control-O/COSMOS automatically applies the inverse relationship of all prerequisites as well. When bringing down objects, inverse application of Control-O/COSMOS prerequisites helps ensure that objects are brought down in a logical order during system shutdown.

For example, if object A can only be brought up when object B is already up, object B can only be brought down if object A is already down.

Although application of the inverse relationship is the default, exceptions to this can be specified in the optional WAY field (described below).

Columns of the Prerequisite Database

The Prerequisite database must contain the following columns:

Table 16 Prerequisite Database Columns

The following screen segment contains sample content of a Prerequisite database (as displayed in the Variable Database Definition screen):

Figure 12 Prerequisite Database Example

    ROW       FMOBJ     TOOBJ     FMDB      TODB       WAY   
    00007000  TCP       VTAM                           UP
    00008000  CICT      APLCICT                        UP
    00010000  IMS       JES2                           UP
    00011000  VTAM      JES2
    00012000  TCP       APLTCP    COSSTCOB  COSVTMOB
    00013000  CICP      VTAM                           DOWN
    00014000  CTD       JES2                           DOWN

Control-O/COSMOS checks prerequisite dependency relationships between objects, for UP/DOWN, DOWN/UP or equivalent statuses (for example, ONLINE/OFFLINE, described in Generic Statuses). Other statuses are not checked for prerequisites.

Creating and Maintaining Method Databases

Method rules are Control-O rules that are invoked to change the status of an object. To determine which Method rule to invoke, Control-O/COSMOS searches the Method database. Rows of the Method database contain information (methods) indicating which rule performs the change of an object from its current status to its desired status.

Each Method database must contain the following columns:

Table 17 Method Database Columns

The following screen segment contains sample content of a Method database (as displayed in the Variable Database Definition screen):

Figure 13 Method Database Screen Example

    ROW       CURRENT   DESIRED   OBJDB     METCLASS  METHOD   
    00001000  DOWN      UP                            COSMET01
    00002000  UP        DOWN                          COSMET04
    00003000  UNKNOWN                                 COSMET03
    00004000  DOWN      UP        COSVTMOB            COSMET11
    00005000  UP        DOWN      COSVTMOB            COSMET12
    00006000  UNKNOWN             COSVTMOB            COSMET13

Control-O/COSMOS compares the information in each row of the Method database with the attributes of the object whose status is to be changed.

Attributes of a method may match the object’s attributes exactly, or a partial match may occur. Furthermore, multiple methods can match object attributes to varying degrees. Therefore, an algorithm is used rate (assign a score to) each method. Based on this rating, the method that best matches the attributes of the object to be changed is invoked. For more information, see Generic Statuses, and Method Selection Logic.

Generic Statuses

The most common statuses for Control-O/COSMOS-controlled objects, are UP, DOWN and UNKNOWN. Different terminology may be appropriate for some object types. For this reason, Control-O/COSMOS allows specification of different UP, DOWN and UNKNOWN values in member COSMOLST for each Object database. For example, objects in a certain database may have a status of ONLINE or ACTIVE instead of UP, a value of OFFLINE or INACTIVE instead of DOWN, and a value of NOTFOUND instead of UNKNOWN.

When comparing an object’s current and desired statuses with rows in the Method database, Control-O/COSMOS first attempts to match the actual status name (for example, ONLINE or OFFLINE). However if UP, DOWN or UNKNOWN is specified in the Method database, this results in return of a partial match. Control-O/COSMOS also matches any status beginning with the characters UP and DOWN with statuses UP and DOWN respectively.

• UP is a generic status which matches any of the following:

  • A status of UP.

  • A status beginning with the characters UP (for example, UPLOADED).

  • An UP value (for example, ONLINE or ACTIVE) specified for the Object database in member COSMOLST.

• DOWN is a generic status which matches any of the following:

  • A status of DOWN.

  • A status beginning with the characters DOWN (for example, DOWNLOAD).

  • A DOWN value (for example, OFFLINE or INACTIVE) specified for the Object database in member COSMOLST.

• UNKNOWN is a generic status which matches any of the following:

  • A status of UNKNOWN.

  • An UNKNOWN value (for example, NOTFOUND) specified for the Object database in member COSMOLST.

During the search for a method to change an object’s status, an exact match of status names (for example, ONLINE to ONLINE) is assigned a higher priority than a match to a generic status name (for example, ONLINE to UP). For more information, see Method Selection Logic.

Adding a New Method to Control-O/COSMOS

A sample Method database and Method rules are supplied with Control-O/COSMOS. However, additional methods are needed to implement Control-O/COSMOS management of objects in your operating environment.

A method must exist for each action Control-O/COSMOS may be required to perform. If a new object is defined, you must verify that methods for bringing that object UP and DOWN exist. If they do not, you must create them.

Creation of a new method involves:

• Definition of Control-O rules (meaning, Method rules) to perform the necessary actions.

• Addition of rows in the relevant Method databases that reference the Method rules and indicate when and for which objects they are used.

When a Control-O/COSMOS method is selected, Control-O/COSMOS rule COSFSMAC is triggered first to automatically point to the object to be modified. Therefore, Method rules need only indicate actions to perform on the actual object (resource) to be modified. For more information, see COSFSMAC Rule.

    -----------------------------------------------------------------------------
     ON RULE     = COSMET02
     OWNER IOAADMIN GROUP      MODE  PROD    RUNTSEC
     DESCRIPTION STOP A STARTED TASK
     DESCRIPTION
     ===========================================================================
     DO COMMAND  = P %%OBJECT
        WAIT        SYSTEM   CONSOLE   CONSOLEID
        WAITMODE   N
     DO
     ===========================================================================

For more information about the Variable Database Definition facility, see the online facilities chapter of the Control-O User Guide.

Method Selection Logic

Control-O/COSMOS compares attributes of the object whose status is to be changed with rows in the Method database. Control-O/COSMOS attempts to match current status, desired status, object name, and object class with information specified for the various methods in the Method database.

• Each row in the Method database is assigned a score.

• Exact matches of object and method attributes are assigned the highest score.

• Partial matches (for example, matches with a generic status) are assigned an intermediate score.

• In certain columns, null can be specified. If an attribute of the object is compared with a method attribute specified as a null value, it is assigned a low score.

• Mismatches (for example, a comparison of status UP and status DOWN) result in rejection of the current method. Control-O/COSMOS continues with the next row in the Method database.

Below is a list of the columns in the Method database and how they are compared with attributes of the object under consideration. All columns listed below are analyzed. Control-O/COSMOS decides which method to invoke only after analyzing all rows in the Method database.

Each row in the Method database is assigned a score depending on how well it matches the description of the object to be modified. The Method rule specified in the row with the highest score is invoked. If no method matches the object under consideration, no action is performed.

The Method database columns are listed below in order of importance. For example, the first column (CURRENT) is assigned a more significant score than the second (DESIRED).

The following Method database columns are analyzed:

• CURRENT

  Compared with the current status of the object under consideration.

  • If the current status of the object matches the CURRENT column of the Method database row, the row is assigned a high score.

  • If the current status of the object matches a generic status specified in the CURRENT column in the Method database row, the row is assigned an intermediate score.

  • If the current status of the object does not match the CURRENT column, the row is rejected, and Control-O/COSMOS continues with the next row in the Method database.

• DESIRED
  

  Compared with the desired status of the object under consideration.

  • If the desired status of the object matches a generic status specified in the DESIRED column in the Method database row, the row is assigned an intermediate score.

  • If a null value is specified in the Method database row, the row is assigned a low score.

  • If the desired status of the object does not match the DESIRED column, the row is rejected, and Control-O/COSMOS continues with the next row in the Method database.

• OBJDB

  Compared with the name of the Working Object database containing the object under consideration.

  • If the value in this column matches the name of the Working Object database, the row is assigned a high score.

  • If a null value is specified in this column, a low score is assigned.

  • If a value is specified in this column and it does not match the name of the object database, the row is rejected, and Control-O/COSMOS continues with the next row in the Method database.

• METCLASS

  Compared with the name and class of the object under consideration.

  • If the name of the object matches the value in this column, the row is assigned a high score.

  • If the name of the object does not match the METCLASS column but the name of the object class does match, the row is assigned an intermediate score.

  • If a null value is specified in this column, the row is assigned a low score.

  • If a value is specified in this column and it does not match the name of the object or the object class, the row is rejected, and Control-O/COSMOS continues with the next row in the Method database.

The scores assigned to matches in each column of a row are added together to determine its total score.

The rule named in the METHOD column of the row with the highest total score is invoked to process the object.

If more than one row is assigned the highest total score (that is, if there is a tie), the first- appearing row with the highest total score is chosen.

As already mentioned, if no row match was found (meaning, all rows were rejected), no action is performed on the object being considered.

The following table shows the possible combinations of matches of information that can invoke a Method rule. These combinations are listed in order of their scores (that is, row number 1 is the highest score, 2 the second highest, and so on).

Table 18 Method Rule Invocations

Control-O/COSMOS Rules

Many Control-O/COSMOS tasks are performed using specially defined Control-O rules. Throughout this chapter, method rules have been mentioned as the rules that perform the actions that bring an object to its desired status. However, keep in mind the following points:

• Method rules do not work alone. They work together with another rule, called COSFSMAC.

• There are other sets of rules (besides COSFSMAC and Method rules) that perform functions other than bringing an object to its desired status.

The following rules and types of rules work together according to function. They are described in detail in this section.

• COSFSMAC Rule and Method Rules

  These rules perform the changes required to bring an object to its desired status.

• Control-O/COSMOS Initialization Rules

  These rules are used in Control-O/COSMOS initialization.

• System Event Detection Rules, The COSELECT rule, and Filter and Action Rules (including Generic Action rule COSACT99)

  These rules work together to detect system events (for example, the starting up or bringing down of a started task) and update the appropriate Working Object database with the information.

• User-Defined Action Rule COSACT98

  This rule is triggered by option R in the Object Status screen, and can be used to define a customized action to be performed when this option is chosen.

• Miscellaneous Rules

  Several rules that perform miscellaneous functions.

A list of local and Global variables used by Control-O/COSMOS rules is provided following the rule descriptions.

General Organization of the Control-O/COSMOS Rules

Control-O/COSMOS is implemented by a Control-O subtask whose main objective is to check the status of the controlled objects, and to issue a message when an action is required. These messages cause Control-O/COSMOS rules to be triggered, which work to balance the system as necessary.

As of version 6.1.00, the Control-O/COSMOS table has been split into two separate tables, $COSMOSO and $COSMOSU. These tables are stored in the IOAhighlevel.IOAENV and CTOhighlevel.RULES libraries, respectively.

• $COSMOSO table contains those rules provided and maintained by BMC. This table is maintainable through SMP/E fixes.
• $COSMOSU table contains those rules that you can modify, and is therefore not maintained by SMP/E fixes.

COSRUL Rule

As of version 6.1.00, rules are no longer directly executed by DO RULE statements, but instead through the COSRUL rule. For example, the syntax of statements such as

DO RULE=COSELECT ....

has been changed to

DO RULE=COSRUL COSELECT ....

In addition to calling a specified Control-O/COSMOS rule, COSRUL also determines whether to preprocess, postprocess, or override that rule by using one of the following special AutoEdit variables:

• %%PRE_rulename
• %%PST_rulename
• %%OVR_rulename

where rulename is the name of the relevant Control-O/COSMOS rule.

In this way, you can add additional statements both before and after those provided by BMC and, if necessary, completely override the original rule.

The following statements, which are found in the USRCLEAR rule of the $COSMOSU table, cause the user-defined rules PREMET01, PSTMET03, and OVRMET04 in the $COSMOSU table to preprocess, postprocess, and override the COSMET01, COSMET03, and COSMET04 rules in the $COSMOSO table, respectively:

/*/* PREMET01 TO EXECUTE BEFORE COSMET01
/*
DO SET=%%PRE_COSMET01=PREMET01
/*
/* PSTMET03 TO EXECUTE AFTER  COSMET03
/*
DO SET=%%POST_COSMET03=PSTMET03
/*
/* OVRMET04 TO OVERRIDE COSMET04
DO SET=%%OVER_COSMET04=OVRMET04

For example, when you execute the command

DO RULE=COSRUL COSMET01

COSRUL uses the information in the first DO SET statement to execute the PREMET01 rule before calling the COSMET01 rule.

COSFSMAC Rule

When Control-O/COSMOS determines that an object is not in its desired status, it searches for a method to set the object to its desired status. When an appropriate method is found, the following internal message is issued:

COSFSMAC dbname row rulename parms

where

• dbname – Name of the Working Object database containing the object to be modified.

• row – Number of the database row describing the object to be modified.

• rulename – Name of the Method rule to be used to modify the object.

• parms – Parameters (if any) to be passed to the Method rule.

This message triggers rule COSFSMAC that:

• Specifies the Object database containing the object to be modified as the current Global Variable pool (Reserved User-defined variable %%$GLOBAL).

• Specifies the row describing the object to be modified as the current database row (Reserved User-defined variable %%$DBROW).

• Triggers the specified Method rule.

Since the COSFSMAC rule performs the above routine tasks, it simplifies coding of Method rules. Method rules assume that when they are triggered, the Global variable pool and database row are already set. Only actions to be performed (for example, issuing a START command) need to be included in the Method rule.

Method Rules

Method rules define actions that change the status of a Control-O/COSMOS-controlled object.

Method rules must begin with an ON RULE statement. They are triggered by a DO RULE statement in the COSFSMAC rule. The rule name specified in the ON RULE statement of the Method rule must be the name specified in the METHOD column of the Method database.

When Control-O/COSMOS determines that an object’s status does not match its desired status, it searches the Method database for the name of a method to change the status of the object. When a matching row is found in the Method database, the rule specified in the METHOD column of the row is triggered (using the COSFSMAC rule).

Sample Method rules (with a prefix of COSMET) are provided with Control-O/COSMOS. These Method rules can be customized and additional Method rules can be defined to conform with site requirements.

Control-O/COSMOS Initialization Rules

This topic describes the COSMOLST and Object database initialization rules.

COSMOLST Variable Initialization Rules

When Control-O/COSMOS is initialized, the contents of each record in member COSMOLST are displayed in a message. These messages trigger the following rules to process COSMOLST information and to set Global variables used by Control-O/COSMOS rules:

Table 19 Initialization Rules

For more information about the Global variables used by Control-O/COSMOS, see AutoEdit Variables Used by Control-O/COSMOS Rules.

Object Database Initialization

The following rules handle initialization of the Control-O/COSMOS Object databases.

• COSFSMIN
  Handles initialization of Object databases. During initialization of Control-O/COSMOS, this rule copies records from the Source Object database to the Working Object database and specifies appropriate values for the various columns in the Working Object database.

• The rule also sets the current status of all objects to UNKNOWN. Therefore, the next time Control-O/COSMOS scans the Object database, a rule is triggered to determine the current status of each object.

• COSFSMIC
  Resets certain Global variables after all Control-O/COSMOS Object databases have been initialized. This rule can be modified to perform additional actions that are required after Control-O/COSMOS initialization is completed.

Control-O/COSMOS Object Update Rules

System event detection rules detect system events that affect objects controlled by Control-O/COSMOS (for example, the starting up or bringing down of a started task).

After a system event detection rule detects a system event, the rule passes parameters to, and triggers, the Control-O/COSMOS COSELECT rule. The parameters passed to the COSELECT rule are the names of a Filter rule and an Action rule. The COSELECT rule uses the Filter and Action rules to register the event in the appropriate Working Object database object. For more information, see COSELECT Rule.

General Rules

Every event-detection rule triggers a General rule that handles events of the appropriate type (for example, starting a started task). The General rules determine which arguments to pass to the COSELECT rule.

The following General rules are supplied with Control-O/COSMOS:

Table 20 Control-O/COSMOS General Rules

COSELECT Rule

The COSELECT rule is triggered by other Control-O/COSMOS rules to search for Object database rows on which to perform a specified action. The names of a Filter rule and an Action rule are supplied as parameters to the COSELECT rule.

The COSELECT rule performs the following actions:

1. The COSELECT rule applies the specified Filter rule to each row of the specified Object databases.

   • If the current row is selected by the Filter rule, the specified Action rule is triggered to perform an action on the current row.

2. The COSELECT rule increments the row number (%%$DBROW) and applies the Filter rule to the next row of the Object database.

Filter rules and Action rules are described later in this chapter.

The DO RULE statement that triggers the COSELECT rule supplies the following parameters:

COSELECT database filter action

where

• database is the name of the Working Object database to scan. Valid values:

• >dbname – The name of the database to scan.

• ALL – Scan all databases.

• filter is the name of the Filter rule applied to each database row scanned by the COSELECT rule.

• action is the name of the Action rule to apply to database rows chosen by the Filter rule.

IF       %%CURRENT NE %%DESIRED
DO SET      = %%COS_SELECTED = YES
ENDIF

DO SHOUT    = TO OPER              URGENCY R SYSTEM   
MESSAGE CONTROL-O/COSMOS - %%CPU/%%OBJECT/%%CURRENT/%%DESIRED/%%MODE/%%TEXT

Filter Rules

Filter rules are triggered by the COSELECT rule, described in COSELECT Rule, to determine whether or not to perform an action on the current row in an Object database.

If an action must be performed on the current row, the Filter rule sets variable %%COS_SELECTED to YES. The COSELECT rule detects this and triggers the appropriate Action rule.

Sample Filter rules (with a prefix of COSFLT) are provided with Control-O/COSMOS. These filters can be customized and additional Filter rules can be defined to conform with your site’s requirements.

Action Rules

Action rules are triggered by the COSELECT rule when a Filter rule determines that an action is to be performed on the current row in an Object database. The name of the Action rule to be applied is passed as a parameter to the COSELECT rule by the General rule that handled the system event.

Sample Action rules (with a prefix of COSACT) are provided with Control-O/COSMOS. These actions can be customized and additional Action rules can be defined to conform with your site’s requirements.

COSACT99 Rule

The COSACT99 rule is a generic Action rule that can be used to define tasks to be performed subsequent to execution of each Action rule. Most Action rules trigger the COSACT99 rule before returning control to the COSELECT rule.

Sample rule COSACT99 that is supplied with Control-O/COSMOS checks if debug information is displayed. Additional actions can be specified in this rule to conform with your sites requirements.

User-Defined Action Rule COSACT98

The COSACT98 rule is triggered when option R (User) is specified on the Control-O/COSMOS Object Status screen.

Sample the COSACT98 rule supplied with Control-O/COSMOS issues a Shout message describing the object for which the option was specified.

This rule can be customized to perform a user-defined action (for example, one not available using the predefined options in the Object Status screen).

Miscellaneous Rules

Consider also the following rules when implementing Control-O/COSMOS at your site:

Table 21 Miscellaneous Control-O/COSMOS Rules

AutoEdit Variables Used by Control-O/COSMOS Rules

The variables described in the following tables are used by Control-O/COSMOS rules.

• Local variables are used by the COSELECT rule, and related rules, to keep track of information during the run of a COSELECT rule.

• Most Global variables listed below are set by Control-O/COSMOS initialization rules. These variables are stored in Global variable pool COSWORKV.

For more information about how these variables are used, see rule table Control-O/COSMOS in the Control-O Rule library.

Local Variables

Table 22 Local Variables

Global Variables

Table 23 Global Variables

Control-O/COSMOS Commands

Several commands are provided with the Control-O/COSMOS facility. These commands are divided into the following groups:

• commands that affect the operation of Control-O/COSMOS

• commands that perform actions on Control-O/COSMOS-controlled objects, many of which perform actions that can also be performed using Control-O/COSMOS online screens

Except where noted, Control-O/COSMOS commands have no special parameters or syntax. To use them, type the command where appropriate on the current screen and press Enter.

This section describes each Control-O/COSMOS command and the rules that they trigger

COSINI Command – Starting Control-O/COSMOS

Use this command to start Control-O/COSMOS.

The following Shout messages are issued in response to the COSINI command:

Figure 15 COSINI Shout Messages

COSMOS -     THE FOLLOWING STARTING OPTIONS ARE AVAILABLE:
COSMOS -     1 - DESIRED = UP
COSMOS -     2 - DESIRED = DOWN
COSMOS -     3 - DESIRED = CURRENT (AND SET MODE FORCE_OK)
COSMOS -     4 - DESIRED = SOURCE DATABASE DESIRED COLUMN
COSMOS -     5 - DESIRED = SOURCE DATABASE ATIPL COLUMN
COSMOS -     6 - DESIRED = SOURCE DATABASE NOTIPL COLUMN
nn CONTROL-O/COSMOS - SELECT ONE OPTION

These messages indicate different options that can be used to determine startup status for Control-O/COSMOS-controlled objects.

The option that is recommended depends on whether Control-O/COSMOS will be responsible for starting other resources (objects) in the system.

• If Control-O/COSMOS is started at IPL, option 5 is recommended. This option causes the desired status to be set according to the ATIPL column in the Source Object database.

• If Control-O/COSMOS is started without an IPL, option 3 is recommended. Option 3 sets each object’s mode to FORCE_OK.

• When a Control-O/COSMOS Object database is initialized, the current status of each object is set to UNKNOWN. The next time Control-O/COSMOS scans the Object database, a rule is triggered to determine the current status.

• If startup option 3 (mode FORCE_OK) was specified at Control-O/COSMOS startup, the desired status is modified to match the new current status. After current and desired statuses are set, objects can be assigned a mode of FREE to transfer control of the object status to Control-O/COSMOS.

• If a startup option other than 3 was specified, the desired status for each object is set according to the specified option. The next time Control-O/COSMOS scans the Object database, Control-O/COSMOS takes steps to ensure that objects are brought to their desired statuses.

Command Workflow

The following steps are performed internally when you run the COSINI command:

1. The COSINIT0 rule is triggered. This rule issues a series of Shout messages describing available startup options, and one WTOR message telling the user to choose one of these options.

2. When a startup option is specified in response to the WTOR message, the option number is stored in an AutoEdit variable and the following command is issued:

   • F CONTROLO,COSMOSSTART

3. During initialization, Control-O/COSMOS issues internal messages in the following format:

   • COSFSMIN dbname

   • Where dbname is the name of a Working Object database to initialize.

4. The COSFSMIN rule is triggered by the message in step 3. This rule triggers the COSELECT rule.

5. The COSELECT rule applies Action rule COSACT70 to perform the following actions on each Object database row:

   • Copies necessary information from the Source Object database to the Working Object database.

   • Sets the CURRENT status of the object to UNKNOWN.

   • Sets the DESIRED status according to the option specified in response to the WTOR message described in Step 1.

COSTERM Command – Stopping Control-O/COSMOS

• Use this command to shut down the Control-O/COSMOS facility.

• This command shuts down the Control-O/COSMOS facility without affecting the status of Control-O/COSMOS-controlled objects.

• COSTERM triggers the COSTERM rule, which issues the following operator command:

F CONTROLO,COSMOSSTOP

• You can modify the COSTERM rule for added functionality.

COSBOUNZ Command – Bring Down and Restart Control-O/COSMOS

This command bounces (recycles) the Control-O/COSMOS facility by terminating Control-O/COSMOS and then restarting it.

This command triggers the COSBOUNZ rule, which also reloads Control-O/COSMOS databases, thereby refreshing all Control-O/COSMOS information.

COSDB Command

This command is used to change Object database or Control-O/COSMOS mode, or to display information about Object databases. The command syntax is:

F CONTROLO,COSDB=dbname,cmd

where

• dbname is the name of the database on which the command is performed. mandatory. Valid values are:

If the COSDB command is being used to display information, this value indicates that information describing all Object databases is to be displayed.

• cmd is the action to be performed. Mandatory. Valid values are:

The COSDB command affects specified Object databases directly. No Control-O/COSMOS rules are triggered to perform the actions requested using this command.

COSCMD Command

This command triggers the COSCMD rule, which changes the information in an Object database according to specified parameters.

The syntax for this command is:

COSCMD cmd dbname select-criteria

where

• COS is the special command prefix defined during Control-O installation.
• cmd
  Action to be performed. Valid values are:

• dbname
  Name of the database containing objects on which the command is to be performed. Optional. Valid values are:

• select-criteria
  Selection criteria that determine the objects to be processed by the command. Optional. Valid values are:

• A maximum of two selection criteria can be specified. If a value of EXCEPTION is specified, no other selection criteria can be specified.

• If more than one selection criterion is specified, the selection criteria have an AND relationship.

• If no selection criteria are specified, the requested action is performed on all objects defined in the specified database.

Command Workflow

The following actions are performed for each invocation of the COSCMD command:

1. The COSCMD rule is triggered. This rule determines the Filter and Action rules for the requested action and passes them to the COSELECT rule.

2. The COSELECT rule applies the specified Filter rule and Action rule to the specified Object databases.

For more information, see COSELECT Rule

Shortcuts for the COSCMD Command

A number of shortcuts for the COSCMD command are supplied with Control-O/COSMOS. Each of these shortcuts triggers a rule that invokes the COSCMD command with specific parameters.

COSUP — Start Up All Control-O/COSMOS-Controlled Objects

This command sets the desired status of all objects that are controlled by Control-O/COSMOS to UP, and their mode to FREE. The next time Control-O/COSMOS scans the Object databases, it takes steps to ensure that objects not currently up are brought up (if prerequisites are satisfied). This command might typically be used to simulate an IPL or to test Control-O/COSMOS operations.

The COSUP command invokes the COSUP rule, which issues the following command:

COSCMD DESIUP ALL

COSDOWN — Shut Down All Control-O/COSMOS-Controlled Objects

Use this command to shut down all objects that are controlled by Control-O/COSMOS in a system. This command sets the desired status of all Control-O/COSMOS controlled objects to DOWN. The next time Control-O/COSMOS scans the Object databases it notes the change and takes steps to ensure that Control-O/COSMOS-controlled objects are brought down. The COSDOWN command invokes the COSDOWN rule that issues the following command:

COSCMD DESIDOWN ALL

COSOBJ — Display information about an Object Command

This command displays information about a specified object. The syntax for this command is:

COSOBJ obname

where obname is the name of the object to be described.

Control-O/COSMOS searches all Working Object databases for the specified object. If more than one object with the specified name is located, all objects with the specified name are described in the output messages.

This command invokes the COSOBJ rule, which issues the following command:

COSCMD DISPALL ALL OBJECT obname

Supporting Multiple Control-O/COSMOS Instances

Usually, only one Control-O/COSMOS instance, running on one IOA installation, is started for each CPU. When more than one IOA installation is running on the same CPU, Control-O/COSMOS normally runs on only one of these IOA installations. In these cases, Control-O/COSMOS commands are handled by the single Control-O/COSMOS instance.

There are, however, test and development environments that may require more than one Control-O/COSMOS instance for each CPU. In such environments, it is essential that Control-O/COSMOS commands are run on the correct instance of Control-O/COSMOS.

Control-O/COSMOS Command Prefix

Version 6.1.00 handles this situation by requiring you to define a 3-character command prefix for each Control-O/COSMOS instance during ICE installation, using the PROCPRFO parameter of that instance. You use these defined prefixes in place of the regular COS prefixes for each Control-O/COSMOS command.

Each Control-O/COSMOS instance has a set of Control-O/COSMOS rules beginning with the ??? prefix. These rules implement the Control-O/COSMOS commands that use the defined command prefixes. For example, the rules ???INI and ???UP implement the commands that correspond to the COSINI and COSUP commands, respectively. These ???-prefixed rules check whether the prefix of a Control-O/COSMOS command matches the prefix of the Control-O/COSMOS instance specified in its PROCPRFO parameter.

When you enter a prefixed Control-O/COSMOS command, all Control-O/COSMOS instances in the IOA environment receive that command. Each instance compares the Control-O/COSMOS command with the %%COSPREFIX variable, which was initialized with the value of the PROCPRFO parameter by the ON RULE USRCLEAR rule in the $COSMOSU table. If the defined prefix and command prefix do not match, command processing is terminated for that Control-O/COSMOS instance. Otherwise, the command is executed normally. If the prefix does not match that of any Control-O/COSMOS instances, the command is not executed.

When using the ??? prefix, note the following:

• If a rule with the ??? prefix triggers a Control-O/COSMOS command, that command will use the same prefix as the triggering command.

• Control-O/COSMOS commands are now trapped by the ON COMMAND rules that use the ??? prefix. These ON COMMAND rules check the prefix and, if there is a match, pass control to the corresponding ON RULE rules.