Using substitution variables in commands

Common substitution variables

The substitution variables that can be defined are listed in the table below.

Table 1. Substitution variables used by commands
Substitution Variable Description
&U Substitutes the user/console id of the message text originator.
&R Substitutes the id of the rule, schedule, or monitor which caused action processing.
&P Substitutes the value passed by the PARM operand of a rule, schedule, or monitor. The PARM field of the rule, schedule, or monitor may contain substitution variable patterns.
&SYSNAME Substitutes the system name.
&SYSSSIN Substitutes the system SSI name.
&GOMMAIN Substitutes the userid of the main processing server.

The following tables list the substitution variables available when an action is triggered specifically by a rule, schedule, and monitor. These substitution variables are available only when the action is triggered by the specified rule, schedule, or monitor statement.

DEFEMON substitution variables

The DEFEMON command allows the substitution variables listed in the table below.

Table 2. DEFEMON substitution variables
Variable Value
&C 0
&T Concatenation of &0 through &n
&U Constant _GOMEMON
&0-&99 Specifies information about the event monitor and event. Valid values are:
  • &0 — Constant "VMEVENT" (Length 7, Type Character)
  • &1 — Name of the event monitor (Length 1-8, Type Character)
  • &2 — Name of the event monitor's action (Length 1-8, Type Character)
  • &3 — Userid that caused the event (Length 1-8, Type Character)
    Note: In some cases, &3 represents something different. Any differences are listed in the next section, "DEFEMON variables &6-&nn".
  • &4 — Event class (Length 1-8, Type Decimal)
  • &5 — Event type (Length 1-8, Type Decimal)
  • &6-&n — Any additional information passed for a particular event class/type. Depending on the message, these variables could include one or more of the following:
    • Reason
    • Interval specified or interval remaining
    • Destination or source system
    • SSI member name and the previous, current, or new SSI mode
    • Port group name, number, status, or status reason
    • RDEV number or error status
    • VSWITCH status
    • Bridge port status or error status
    • Interval specified or interval remaining (32 bit)
    • Logon-By User ID
    • Terminal Device ID
    • Terminal conmode
    • Terminal rdev/ldev (Terminal device number)
    • extended_luname (VTAM network qualifier and logical unit name)
    • owner (user ID of the virtual machine that created the device)
    • origin_type (Terminal information)
    • origin (Terminal information)
    • Other event data

    For more specific parameter details, see the additional DEFEMON information in the section that follows.

For more information on event class (&4) and event type (&5), refer to the VM Event System Service (*VMEVENT) described in the CP Programming Services documentation (SC24-6179).
Some of the DEFEMON parameters use only event substitution variables &1 - &5 described above. These parameters are the following:
  • LOGON (Class 0, Type 0)1
  • LOGOFF (Class 0, Type 1)
  • Forced SLEEP started (Class 0, Type 4)
  • Runable state entered (Class 0, Type 5)
  • Free storage limit exceeded (Class 0, Type 6)
  • Timebomb exploded (Class 0, Type 15)
  • Virtual system reset (Class 0, Type 27)
  • Virtual Machine (Guest) is disconnecting (Class 0, Type 29)
  • Forced SLEEP active (Class 1, Type 4)
  • Free storage limit exceeded (Class 1, Type 6)
  • Virtual system reset (Class 0, Type 27)

1 For z/VM 7.2 and earlier, Class 0, Type 0 supports substitution variables &1 to &5 only. For z/VM 7.3 and later with the PTF for APAR VM66679, Class 0, Type 0 has been enhanced to support substitution variables &6 to &nn also.

DEFEMON variables &6 - &nn

This section provides additional details on the event substitution variables that are &6 and higher. The event substitution variables & 1 - & 5 are the same for all of the events, as described above, with only a few exceptions. Any exceptions are also included in the table below.


Table 3. DEFEMON event substitution variables &6 and higher
Event parameter or message Variable # Description
LOGON (Class 0, Type 0)2 &6 Logon-By User ID, Length 1-8, Type Character
&7 Terminal Device ID, Length 1, Type Hex
&8 Terminal conmode, Length 1, Type Hex
&9 Terminal rdev/ldev Length 4, Type Hex
&9 extended_luname, Length 17, Type Character
&10 owner, Length 1-8, Type Character
&11 origin_type, Length 1, Type Hex
&12 origin, Length 0-16, Type Hex
Failure condition detected (Class 0, Type 2) &6 Reason, Length 1-3, Type Decimal
LOGOFF timeout started (Class 0, Type 3) &6

Interval, Length 1 - 5, Type Decimal

&72

Timeout interval (32 bit), Length 1 - 10, Type Decimal

Virtual machine outbound relocation started (Class 0, Type 9) &6 Destination system, Length 1-8, Type Character
Virtual machine inbound relocation started (Class 0, Type 10) &6 Source system, Length 1-8, Type Character
Virtual machine outbound relocation complete (Class 0, Type 11) &6 Destination system, Length 1-8, Type Character
Virtual machine inbound relocation complete (Class 0, Type 12) &6 Source system, Length 1-8, Type Character
Virtual machine outbound relocation terminated (Class 0, Type 13) &6 Reason, Length 1-3, Type Decimal
Virtual machine inbound relocation terminated (Class 0, Type 14) &6 Reason, Length 1-3, Type Decimal
Virtual Machine (Guest) is reconnected. (Class 0, Type 28).2 &6 Logon-By User ID, Length 1-8, Type Character
&7 Terminal Device ID, Length 1, Type Hex
&8 Terminal conmode, Length 1, Type Hex
&9 Terminal rdev/ldev Length 4, Type Hex
&9 extended_luname, Length 17, Type Character
&10 owner, Length 1-8, Type Character
&11 origin_type, Length 1, Type Hex
&12 origin, Length 0-16, Type Hex
Failure condition exists (Class 1, Type 2) &6 Reason, Length 1-3, Type Decimal

LOGOFF timeout service (Class 1, Type 3)

&6 Interval remaining, Length 1-5, Type Decimal
&72 Interval remaining (32 bit), Length 1-10, Type Decimal
Virtual machine outbound relocation active (Class 1, Type 9) &6 Destination system, Length 1-8, Type Character
Virtual machine inbound relocation active (Class 1, Type 10) &6 Source system, Length 1-8, Type Character
SSI mode change &3 SSI name, Length 1-8, Type Character
(Class 2, Type 7) &6 Previous SSI mode, Length 2, Type Hex
  &7 New SSI mode, Length 2, Type Hex
SSI member state change &3 SSI name, Length 1-8, Type Character
(Class 2, Type 8) &6 Previous SSI mode, Length 2, Type Hex
  &7 New SSI mode, Length 2, Type Hex
  &8 New SSI mode, Length 2, Type Hex
SSI mode &3 SSI name, Length 1-8, Type Character
(Class 3, Type 7) &6 Current SSI mode, Length 2, Type Hex
  &7 Current SSI mode, Length 2, Type Hex
SSI member state &3 SSI name, Length 1-8, Type Character
(Class 3, Type 8) &6 Current SSI mode, Length 2, Type Hex
  &7 Current SSI mode, Length 2, Type Hex
  &8 Current SSI mode, Length 2, Type Hex
Device activated, LAN now operational &3 VSWITCH name, Length 1-8, Type Character
(Class 4, Type 16) &6 Port group name, Length 1-8, Type Character
  &7 RDEV number, Length 4, Type Hex
  &8 Port number, Length 2, Type Hex
  &9 Port status, Length 2, Type Hex
  &10 Port status reason, Length 4, Type Hex
  &11 VSWITCH status, Length 2, Type Hex
  &12 RDEV error status, Length 2, Type Hex
Additional device activated, LAN previously operational &3 VSWITCH name, Length 1-8, Type Character
(Class 4, Type 17) &6 Port group name, Length 1-8, Type Character
  &7 RDEV number, Length 4, Type Hex
  &8 Port number, Length 2, Type Hex
  &9 Port status, Length 2, Type Hex
  &10 Port status reason, Length 4, Type Hex
  &11 VSWITCH status, Length 2, Type Hex
  &12 RDEV error status, Length 2, Type Hex
Device deactivated, LAN remains operational &3 VSWITCH name, Length 1-8, Type Character
(Class 4, Type 18) &6 Port group name, Length 1-8, Type Character
  &7 RDEV number, Length 4, Type Hex
  &8 Port number, Length 2, Type Hex
  &9 Port status, Length 2, Type Hex
  &10 Port status reason, Length 4, Type Hex
  &11 VSWITCH status, Length 2, Type Hex
  &12 RDEV error status, Length 2, Type Hex
Device deactivated, LAN no longer operational &3 VSWITCH name, Length 1-8, Type Character
(Class 4, Type 19) &6 Port group name, Length 1-8, Type Character
  &7 RDEV number, Length 4, Type Hex
  &8 Port number, Length 2, Type Hex
  &9 Port status, Length 2, Type Hex
  &10 Port status reason, Length 4, Type Hex
  &11 VSWITCH status, Length 2, Type Hex
  &12 RDEV error status, Length 2, Type Hex
Device activated, bridge port operational &3 VSWITCH name, Length 1-8, Type Character
(Class 4, Type 20) &6 Bridge port RDEV number, Length 4, Type Hex
  &7 Bridge port status, Length 2, Type Hex
  &8 Bridge port error status, Length 2, Type Hex
Device deactivated, bridge port no longer operational &3 VSWITCH name, Length 1-8, Type Character
(Class 4, Type 21) &6 Bridge port RDEV number, Length 4, Type Hex
  &7 Bridge port status, Length 2, Type Hex
  &8 Bridge port error status, Length 2, Type Hex
A Global virtual switch member had a connectivity problem and the local system using the same global virtual switch and shared port group took over the MAC address to continue toprovide connectivity. The MAC Address assigned to Virtual Switch Name (with associated Port Group Name, PCHID Number, Port Number, and System Identifier) has been assigned to Local Virtual Switch Name on Local System Identifier.    
(Class 4, Type 22) &3 Virtual Switch Name, Length 8, Type Character
  &6 System Identifier, Length 8, Type Character
  &7 Local Virtual Switch Name, Length 8, Type Character
  &8 Local System Identifier, Length 8, Type Character
  &9 MAC Address, Length 12, Type Hex
  &10 Port Group Name, Length 8, Type Character
  &11 PCHID Number, Length 4, Type Hex
  &12 Flags, Length 2, Type Hex
  &13 Port number, Length 1 - 3, Type Decimal
A connectivity problem affecting a global virtual switch and shared port group member has been repaired or a different global virtual switch member has taken over the MAC Address. The MAC Address previously assigned to Local Virtual Switch Name and Local System Identifier is now assigned to Virtual Switch Name with associated Port Group Name, PCHID Number, Port Number, and System Identifier.    
(Class 4, Type 23) &3 Virtual Switch Name, Length 8, Type Character
  &6 System Identifier, Length 8, Type Character
  &7 Local Virtual Switch Name, Length 8, Type Character
  &8 Local System Identifier, Length 8, Type Character
  &9 MAC Address, Length 12, Type Hex
  &10 Port Group Name, Length 8, Type Character
  &11 PCHID Number, Length 4, Type Hex
  &12 Flags, Length 2, Type Hex
  &13 Port number, Length 1 - 3, Type Decimal
The System has successfully joined the IVL Domain. &3 Local System Identifier, Length 8, Type Character
(Class 4, Type 24) &6 IVL Domain, Length 2, Type Hex
  &7 Flags, Length 2, Type Hex
The System has left the IVL Domain. &3 Local System Identifier, Length 8, Type Character
(Class 4, Type 25) &6 IVL Domain, Length 2, Type Hex
  &7 Flags, Length 2, Type Hex
An event with no defined formatting routine was received &3 Constant "*UNKNOWN", Length 8, Type Character
(Class and Type are both "Other") &6 Event data, Length 0-80, Type Hex
2 These parameters are only applicable to z/VM 7.3 and later with the PTF for APAR VM66679.

DEFIMON substitution variables

The DEFIMON command allows the substitution variables listed in the table below.

Table 4. DEFIMON substitution variables
Variable Value
&0 Constant "IDLE"
&1 Name of the idle monitor
&2 Name of the idle monitor's action
&3 Type of resource that is monitored: RULE, MACHINE, SCHEDULE, SPOOL, EVENT, PAGE, or IDLE.
&4 Name of the monitored resource
&5 Indicates the number of times the monitored resource was triggered within the interval specified on the OCCUR operand.

DEFMMON substitution variables

The DEFMMON command allows the substitution variables listed in the table below.

Table 5. DEFMMON substitution variables
Variable Value
&0 Constant "MACHINE"
&1 Name of the machine monitor
&2 Name of the machine monitor's action
&3 User ID that caused the action

DEFPMON substitution variables

The DEFPMON command allows the substitution variables listed in the table below.

Table 6. DEFPMON substitution variables
Variable Value
&C 0
&T Concatenation of &0 &1 &2 &3 &4 &5 &6
&U Constant _GOMPMON
&0-&99 Specifies information about the page monitor and page space. Valid values are:
  • &0 - Constant "PAGE"
  • &1 - Name of the page space monitor
  • &2 - Name of the page space monitor's action
  • &3 - Condition field that is passed to the action (USAGE or INCREASE)
  • &4 - Page usage percent
  • &5 - Page usage percent increase for this monitor
  • &6 - Interval of the page monitor

DEFSMON substitution variables

The DEFSMON command allows the substitution variables listed in the table below.

Table 7. DEFSMON substitution variables
Variable Value
&C 0
&T The concatenation of &0 &1 &2 &3 &4 &5 &6 &7 &8
&U The constant _GOMSMON
&0-&99 Specifies information about the spool monitor, spool usage, and spool file usage. Valid values are:
  • &0 - Constant SPOOL
  • &1 - Name of the spool monitor
  • &2 - Name of the spool monitor's action
  • &3 - Condition field passed to the action (USAGE or INCREASE)
  • &4 - Spool usage percent
  • &5 - Spool usage percent increase for this monitor
  • &6 - Spool file usage percent
  • &7 - Spool file usage percent increase for this monitor
  • &8 - Interval of the spool monitor

DEFRULE substitution variables

The DEFRULE command allows the substitution variables listed in the table below.

Table 8. DEFRULE substitution variables
Variable Value
&C Indicates the class of the message text. Valid classes are:
  • 1 - Text came from CP MSG or CP MSGNOH.
  • 2 - Text came from CP WARNING.
  • 3 - Text came from CP console output (includes OBSERVER messages.
  • 4 - Text came from CP SMSG.
  • 5 - Text came from VM console output.
  • 6 - Text came from CP error message.
  • 7 - Text came from CP informational message.
  • 8 - Text came from CP single console image facility (includes SECUSER messages).
  • 22 - Text came from Operations Manager Remote Source Input Filter. Refer to GOMRSIF for more information.
  • 23 - Text came from Operations Manager Remote Syslog Filter. Refer to GOMRSYL and GOMRSYM in Usage notes for more information.
&T Full message text
&U User ID of the message text originator
&0-&99 Words of the text

DEFSCHD and RUN substitution variables

The DEFSCHD and RUN commands allow the substitution variables listed in the table below.

Table 9. DEFSCHD and RUN substitution variables
Variable Value
&C 0
&T Null
&U Constant _GOMSCHD
&0 Constant "SCHEDULE"
&1 Name of the schedule
&2 Name of the schedule's action