Coding Each AOF Rule Type › Command Rules › )CMD—Event Specifier of CMD Rules

)CMD—Event Specifier of CMD Rules

The CMD-event definition section has the following format:

)CMD cmdverbspec

Adhere to the following guidelines when specifying the character string for the cmdverbspec:

• Specify 1 to 10 characters.
• The string cannot contain embedded blank spaces.
• z/OS Command Considerations:
  • Specify the full command verb or a mask of the command verb when attempting to trigger on z/OS commands.

    For example, when writing a command rule that triggers whenever a z/OS DISPLAY command is issued, specify )CMD DISPLAY rather than )CMD D, or specify )CMD MODIFY rather than )CMD F to execute on z/OS modify commands. Although you must specify the full z/OS command verb in the event definition section of the rule, a command rule recognizes a command event if an operator issues a short form (alias) of the command. Additional logic can be implemented into the )PROC section of the rule to interrogate the CMD.TEXT event variable to see the exact command that was entered.

  • Z/OS may reissue some commands internally if they do not originate from the CONSOLE address space, that is, if a program issues the commands rather than a z/OS console.

    z/OS reissues such commands so that the processing occurs in the CONSOLE address space, thus causing a CMD rule to possibly execute twice. z/OS reissues DISPLAY ACTIVE commands and any other command that creates paged-frame display output on a z/OS console.

• JES2 Command Considerations:

  Use these guidelines when you are writing rules that respond to JES2 commands:

  • When you attempt to trigger on JES2 commands, specify the JES2 command character followed by the first letter of the JES2 command. For example, if $ is the JES2 command character and you want to trigger on the $TI initiator command, then specify )CMD $T.
  • You can add logic to the )PROC section of the rule to interrogate the CMD.TEXT event variable and see the JES2 command that was entered.
  • For both JES2 and z/OS, you can use a delimiter character to enter more than one command on a single line. JES2 uses a semicolon to delimit multiple commands and z/OS uses the character specified by the CMDDELIM parameter in the CONSOLxx member of the logical PARMLIB concatenation.

    The CMD rule specifier needed to trap stacked JES2 commands is impacted by the type of issuing console (extended, MCS, SMCS, and so on). It is also impacted by the setting of the z/OS CMDDELIM parameter.

    Use these guidelines when you are creating CMD rules to process JES2 stacked commands:

    • If CMDDELIM is set to a semicolon (;), and the issuing console is a MCS or SMCS console, then stacked JES2 commands can only be issued in the form of: $cmd1;$cmd2;$cmd3. For example, $PI1;$TI1,C=X;$SI1.

      Each stacked JES2 command will trigger an associating unique CMD rule, or a wild card catch all JES2 CMD rule will be executed for each stacked command. In this example, a )CMD $* rule would execute three times (once for each command), a )CMD $P rule would execute once, a )CMD $T would execute once, and a )CMD $S rule would execute once.

    • If CMDDELIM is not set (there is no z/OS command stacking), or CMDDELIM is set to some value other than a semicolon (;), or CMDDELIM is set to a semi-colon (;) and the issuing console is not a MCS or SMCS console, then stacked JES2 commands can be issued in the form of $cmd1;cmd2;cmd3. For example, $PI1;TI1,C=X;SI1.

      The entire list of commands stacked together is treated as one command. This command is processed by either one CMD rule that processes all JES2 commands or a specific CMD rule that processes the first command within the list of stacked commands.

      For example, a )CMD $* rule would execute once for the complete stacked command, or a )CMD $P rule would execute once for the complete stacked command. In both cases, additional rule logic to interrogate the value of the cmd.text environmental variable should be coded to process each command accordingly.

    If you are attempting to process and automate various JES2 commands, it may be suitable to create a catch all JES2 rule that rejects command stacking. To implement this type of control logic, see the sample rule JESSTACK in the ops.sample data set.

• JES3 Command Considerations:

  When writing rules that respond to JES3 commands, begin the cmdverbspec event identifier string with the first character in the JESCHAR parameter string. Only the first character in JESCHAR is meaningful in a JES3 environment. When CA OPS/MVS processes a command on a JES3 system, it attempts to match the command prefix with one of the JES3 system or sysplex prefixes. If a match is found, CA OPS/MVS creates a common command verb (see CMD.VERB), regardless of which command prefix was used or whether the command was abbreviated. The purpose of this is to make sure that you have to write only a single command rule for each JES3 command, regardless of how it was issued.

  The command verb (and CMD.VERB) consists of the real command verb with the original prefix stripped off and replaced by the first character in JESCHAR. This does not affect the command text itself, only the verb used to execute the rules. For example, assume you have the following:

  JES3 SYN prefix =  8
  JES3 PLEXSYN prefix = %%
  CA OPS/MVS JESCHAR parameter = *
  

  When you issue the JES3 command 8I S, a rule with a command verb (CMD.VERB) of *INQUIRY is executed. CMD.TEXT will not be changed and remains 8I S (unless CMD.TEXT is changed by the rule itself). The same rule is executed if you issue the command %%I S; CMD.VERB will be the same as in the prior case but the CMD.TEXT will be %%I S.

  The use of multiple system or sysplex command prefixes is fully supported by CA OPS/MVS, whether these prefixes are single- or multiple-character.

  If your CMD rule needs to make decisions based on the original JES3 command prefix, then use the following three environmental variables:

  CMD.JES3PREFIX

  Indicates the original command prefix

  CMD.JES3SYN

  Set to 1 if the original JES3 command prefix is a system scope prefix (SYN)

  CMD.JES3PLEXSYN

  Set to 1 if the original JES3 command prefix is defined as a sysplex scope prefix (PLEXSYN)

  If you set JESCHAR to the same value on all your systems, one rule should be able to work on all your JES3 systems, regardless of what the SYN and PLEXSYN values are on those systems.

  • If the first character in JESCHAR is an * (which is also the wildcard character), you may need to perform additional checking in the PROC section of the rule. Because the cmdverbspec string in the event definition section begins with the wildcard (*) character, a rule triggered by an INQUIRY command is also triggered by NOINQUIRY (not a JES3 command) and INQUIRY (a possible z/OS command). You can solve the problem by coding the processing section of your rule as shown in this example:

    )CMD *INQUIRY
    )PROC
     if CMD.VERB ¬= '*INQUIRY' then
     return 'NOACTION'
    

  • A CMD rule can change *START PRTR1 to *START PRTR2 but not to VARY 2F0,OFFLINE.
• Subsystem Command Character Considerations other than JES2 Commands:

  Specify the command character followed by the wildcard character (*) to execute on commands issued using a product-defined command character. For example, assuming the character / is the command character of a particular subsystem, code a specification of )CMD /* to trigger on commands issued using its command character. Additional logic can be implemented in the )PROC section of the rule to interrogate the CMD.TEXT event variable to see the exact command that was entered.

• You can use the wildcard character (*) where applicable. For example,
  • ST* matches z/OS START and STOP commands or any pseudo command that beings with ST.
  • * matches all command events on the system.
• Lowercase letters are acceptable, but the AOF converts them to uppercase for event testing.