Statements and parameters for IEASYMxx

HWNAME(processor-name)
The name (identifier) of a central processor complex (CPC), as defined to hardware configuration definition (HCD).

If a processor does not have a hardware name, and you define the processor in the same IEASYMxx member that you define other processors with hardware names, specify HWNAME() to indicate that a set of definitions is to apply only to the processor with no hardware name.

Value range: The processor-name is the 1- to 8-character name of the processor on which the system is running. Valid characters are alphanumeric (0–9 A–Z) and national (@ # $). The first character must be alphabetic (A–Z) or national (@ # $).
Default: Match on any hardware name.
Example:
   HWNAME(C1)              /* First test processor */

   HWNAME()            /* Definitions apply only to processors */
                       /* to which no hardware name is defined */ 

To use this parameter, or accept its default value, ensure that the processor on which z/OS® is running supports dynamic I/O configuration. Also, ensure that the I/O configuration data set (IOCDS) was built using hardware configuration definition (HCD). See the information about dynamic I/O configuration in z/OS Planning for Installation for a list of processors that support dynamic I/O configuration.

LPARNAME(lpar-name)
The name of a logical partition that is defined to a processor, which is one of the following:
  • The partition name that is specified on the Add Partition panel in HCD (see z/OS HCD User's Guide for more information).
  • The partition name that is specified on the RESOURCE or CHPID statement that is input to the I/O configuration program (IOCP).
A value of LPARNAME() indicates that a set of definitions applies to a processor that is not initialized in LPAR mode. For example, if you run a processor sometimes in LPAR mode and sometimes in basic mode, and you define separate symbols for each mode in the same IEASYMxx parmlib member, specify LPARNAME() to indicate that the system is to process a set of definitions only when running in basic mode.
Note: Start of changeWhen z/OS is running under any virtual machine (z/VM® or an alternate virtual machine), there is considered to be no LPAR name.End of change
SYMDEF(&symbol='sub-text')
Defines a static system symbol and its substitution text. Your installation can define at least 800 static system symbols in addition to the system symbols that z/OS provides, unless you are using symbols with substitution length longer than the symbol names as described below. You can define at least 700 static system symbols that are of the maximum length (16 characters) and the maximum substitution length (44 characters). You can optionally specify an ending period on &symbol.

You can use SYMD as a short name for SYMDEF.

These symbol names are supported:
  • Symbol names with length up to 16 with substitution text length limited to NameLength + 1. The name can contain an underscore (_) in any character position other than the first one.
  • Symbol names with length up to 16 with a last character of an underscore (_) with substitution text length up to 44.

Do not try to define in the system symbol table two symbols if one of them does not have any underscores and the name portion is no longer than 8 characters, and the other symbol begins with the name portion of the first immediately followed by an underscore. For example, do not define both &SYM and &SYM_2.

Do not try to define a symbol that begins the same as a reserved system symbol but with an underscore right after the "normal" end of the reserved symbol (for example, since &SYSNAME is a reserved symbol, do not define &SYSNAME_1).

When matching a pattern against symbols, an attempt is first made to match against a symbol with underscores. If a match is not made, then an attempt is made to match against a (shorter) symbol without underscores. For example, with just symbol &SYM_2 defined, the string &SYM_2 is replaced by the value for symbol &SYM_2. But with just &SYM defined, the string &SYM_2 is replaced by the value for symbol &SYM followed by "_2".

Restriction: The length of the substitution text cannot exceed the length of the symbol name plus the ampersand (&) but not plus the trailing period (.) unless the symbol name ends with an underscore. In that case, the substitution text can be up to 44 characters long. Except for the ending-with-underscore case, this restriction prevents the flow of characters beyond established limits for text entry. For example, assume that the limit for text entry is column 71. If a line that contains a four-character symbol without the trailing period (for example, &SSSS) extends to column 71, a substitution text of greater than 5 characters would force the text beyond column 71. When you use a symbol that ends with an underscore, you accept that unintended results (such as truncation with no warning) might occur if the resulting substitution causes flow of characters to extend beyond an intended limit. For example, in the parmlib case, if using a symbol that ends with an underscore, make sure that the resulting substitution would not cause characters to extend beyond column 71. Programs are not expected to, but may, accommodate such line overflow.
Value range: &symbol is the 1–16 character name of a system symbol that your installation defines to the system. You can optionally specify an ending period on &symbol.

For &symbol, names must start with an ampersand (&). The ampersand must be followed by an alphabetic (A–Z) or national (@ # $) character. Subsequent characters of the symbol name can be any valid alphanumeric (0–9 A–Z), national (@ # $), or underscore characters. The trailing period is optional, but recommended.

'sub-text' is the substitution text for the system symbol to be defined. There are no restrictions on the types of characters that can be used. The rules for specifying sub-text are:
  • Enclose the text in single quotation marks (as shown in the syntax diagram).
  • The substitution text can contain other static system symbols (or substrings of another static system symbol) in any order and in any combination. However, do not specify dynamic system symbols in the substitution text. See Using substrings of system symbols for the syntax of substrings.
  • When concatenating a static system symbol and a literal, terminate the static system symbol with a period.
  • The substitution text can be a null value (for example, SYMDEF(&VAR1='') and SYMDEF(&VAR2='&VAR1') are both valid.)
  • The length of the resolved substitution text cannot exceed the length of &symbol, including the ampersand on &symbol and excluding the single quotation marks on 'sub-text' unless the symbol ends with an underscore. For example, although the length of sub-text exceeds the length of the symbol &FRANKIE in the following example, the symbols that are contained in sub-text resolve to 1268ABC, which is a valid substitution text.
     SYMDEF(&MARYJOE.='1234568')
     SYMDEF(&FRANKIE.='&MARYJOE(1:2).&MARYJOE(-2:2).ABC')

    However, the definition &JOHN='JOHNDOE' is not valid because the resolved substitution text JOHNDOE contains more characters than the system symbol &JOHN. But the definition &LONG_='THIS_IS_LONG' is valid because the symbol name ends with an underscore.

Restriction: Do not specify blanks in SYMDEF statements, except in sub-text. For example, SYMDEF(&AB='AB' ) and SYMDEF(&A. ='A') are not valid. SYMDEF(&AB='A B') is valid.
Default: None. If you omit the SYMDEF parameter, the specified z/OS image does not use installation-defined static system symbols.
SYSDEF
Defines the following for one or more z/OS systems in a multisystem environment:
  • System symbols and their associated substitution texts.
  • The suffixes of the IEASYSxx parmlib members to be used.
Each SYSDEF statement can contain:
Filter parameters
The HWNAME, LPARNAME, and VMUSERID parameters specify the system to which one or more value parameters apply:
  • A local SYSDEF statement contains at least one filter parameter. In other words, HWNAME, LPARNAME, or VMUSERID are present on the statement. The value parameters on a local SYSDEF statement apply only to the system that HWNAME, LPARNAME, or VMUSERID identifies.
  • A global SYSDEF statement contains no filter parameters. In other words, HWNAME, LPARNAME, or VMUSERID are not present on the statement. The value parameters on a global SYSDEF statement apply to all systems that use IEASYMxx.
Value parameters
The SYSPARM, SYSNAME, SYSCLONE, and SYMDEF parameters specify the static system symbols and IEASYSxx members that a system is to use. If one or more filter parameters precede a value parameter, value that is defined on that parameter applies only to the system identified by the filter parameters. If a filter parameter does not precede a value parameter, the value parameter applies to all systems that use IEASYMxx.

If two SYSDEF statements define the same symbol for the same system, the last statement that is processed overrides any previous definitions of that symbol. For example, suppose you code a SYSDEF statement at the beginning of IEASYMxx that defines a system symbol for all systems. Later in IEASYMxx, you code another SYSDEF statement that defines the same system symbol for a specific system that is identified on the HWNAME parameter. The second definition, which is identified by HWNAME, overrides the first.

Value range: The lpar-name is the 1–8 character name of a valid logical partition. Valid characters are alphanumeric (0–9 A–Z) and national (@ # $). The first character must be alphabetic (A–Z) or national (@ # $). Do not specify all blanks for the lpar-name.
Default: Match on any LPAR name.
Examples:
   LPARNAME(TEST1)                       /* First test system */

   LPARNAME()                         /* Processor is running */
                                  /* in non-LPAR (basic) mode */
SYSCLONE(system-clone)
The value to be assigned to MVS™ static system symbol &SYSCLONE; SYSCLONE is a 1–2 character shorthand notation for the system name.

Each system in a sysplex must specify a unique SYSCLONE value. Message IXC215I is issued if the substitution text for the &SYSCLONE symbol is not unique in a sysplex.

Value range: Valid characters are alphanumeric (0–9 A–Z) and national (@ # $). Static system symbols can be used as long as the values substituted for the symbols are in the value range.
Default: The last two characters of the value that is specified on the SYSNAME parameter. This default is equivalent to &SYSNAME(-2:2).
Examples: Using a hardcoded value:
   SYSCLONE(01)               /* First test system */ 
Using another static system symbol:
   SYSNAME(S1MVS)             /* Specify name for first test system */
   SYSCLONE(&SYSNAME(1:2)) /* Resolves to first 2 chars in SYSNAME */ 
SYSPARM(aa[,bb...][,L])
The suffixes of the IEASYSxx parmlib members to be used when this SYSDEF statement is selected.

To display the contents of IEASYSxx at the operator console when the system processes each member, specify L anywhere after the first suffix and enclose the values in parentheses. For example, specify (01,L) on SYSPARM to tell the system to process IEASYS01 and display the contents of that member at the operator console. The system ignores the SYSPARM statement if the operator specifies on the LOAD parameter that the system should prompt for system information. The operator can accomplish this by specifying an A, P, S, or T IMSI character on the LOAD parameter on the system console. For details about IMSI characters, see the information about loading the system software in z/OS MVS System Commands.

The suffixes of IEASYSxx members can also be specified:
  • On the SYSPARM parameter in the LOADxx parmlib member.
  • By the operator, in response to message IEA101A SPECIFY SYSTEM PARAMETERS.

See Step 2. Determine where to specify system parameters for more information.

Value range: aa and bb are 1–2 character suffixes of a valid IEASYSxx parmlib member. Valid characters are alphanumeric (0–9 A–Z) and national (@ # $). Neither static nor dynamic system symbols are accepted.
Default: None. If you omit the SYSPARM parameter, the system uses the default member IEASYS00, the suffixes that are specified on the SYSPARM parameter in the LOADxx parmlib member, or the suffixes that are specified by the operator in response to the SPECIFY SYSTEM PARAMETERS prompt.
Example:
   SYSPARM(00,01)          /* IEASYSxx parmlib members 00 and 01 */
SYSNAME(system-name)
The name to be assigned to this MVS system. The system name is also the substitution text for the &SYSNAME system symbol. The value on this parameter can be overridden by alternate parameters that are specified by the operator in response to the SPECIFY SYSTEMS PARAMETERS prompt.
Value range: The system-name is a 1–8 character name for an MVS system. Valid characters are alphanumeric (0–9 A–Z) and national (@ # $). Static system symbols can be used as long as the values substituted for the symbols are in the value range.
Default: For information about where to specify the system name, how the system determines which name to use, and how the default value is chosen, see Step 3. Determine where to specify the system name.
Note: MVS does not prevent two systems from having the same &SYSNAME value. If system resources on multiple systems are defined using &SYSNAME (such as page data sets), the results are unpredictable.
VMUSERID(vm-userid)
The user ID of a z/VM system under which a z/OS image is running as a guest. For information about running z/OS as a guest of z/VM, see z/VM Running Guest Operating Systems.

If you run a processor sometimes as a guest under z/VM and sometimes not, and you define both instances in the same IEASYMxx parmlib member, specify VMUSERID() to indicate that the system is to process a set of definitions only when it is not running as a guest under z/VM.

Note: If a system is identified by a z/VM user ID that is not a valid system name, the system prompts the operator to specify a valid name for the system.
Value range: The vm-userid is a 1- to 8- character name of a valid z/VM system. Valid characters are alphanumeric (0–9 A–Z) and national (@ # $).
Default: Match on any z/VM user ID.
Example:
   VMUSERID(AUTOLOG1)      /* z/VM system of which z/OS is a guest */

   VMUSERID()             /* Process a set a definitions only when */
                              /* not running as a guest under z/VM */ 

Examples

The following are examples of IEASYMxx usage:

Example 1: Define a global system symbol called &LOGSYM to be used on all systems. The value for the symbol will be different on different systems. First, the IEASYMxx member is shown, then the value for &LOGSYM on various systems is listed.
SYSDEF
     SYMDEF(&LOGSYM='LOG1')  /* Define &LOGSYM for all systems */
     SYMDEF(&ABCDEF='OWL')   /* Define &ABCDEF for all systems */
     SYSPARM(BB)               /* Define SYSPARM for all systems */

SYSDEF
   HWNAME(T0)                  /* Identify a test processor      */
     SYMDEF(&LOGSYM='LOGT')  /* Override global &LOGSYM only   */
                               /* for processor T0               */
SYSDEF
   LPARNAME(R1)                /* Identify a runtime processor   */
     SYMDEF(&LOGSYM='LOGR')  /* Override global &LOGSYM only   */
                               /* for LPAR R1                    */

SYSDEF
   HWNAME(T0) LPARNAME()       /* Identify a non-LPAR processor  */
     SYMDEF(&LOGSYM='LOGN')  /* Override global &LOGSYM only   */
                               /* for T0 in non-LPAR mode        */

For this system:      &LOGSYM will have this value:
HWNAME   LPARNAME
 D0     not LPAR mode      LOG1  (only first SYSDEF matched)
 T0       R1               LOGR  (1st, 2nd and 3rd SYSDEF matched)
 T0       R2               LOGT  (1st and 2nd SYSDEF matched)
 T0     not LPAR mode      LOGN  (1st and 4th SYSDEF matched)
none      R1               LOGR  (1st and 3rd SYSDEF matched)
Example 2: Define a symbol using a previously defined symbol and substringing. (See Using substrings of system symbols for the syntax of substrings.)
   SYMDEF(&SYMBOL2='(( ')    /* &SYMBOL2 is assigned ((    */
   SYMDEF(&SYMBOL3='3,3,3 ') /* &SYMBOL3 is assigned 3,3,3 */
 .SYMDEF(&SYMBOL1='&SYMBOL2(1:2).&SYMBOL3(1:1).))')
         /* &SYMBOL1 resolves to the first two characters in   */
         /* &SYMBOL2, the first character in &SYMBOL3, and the */
         /* two hard-coded right parentheses.  &SYMBOL1=((3))  */
 
Example 3: Use the system-provided symbol to set the initial IPL VOLSER and also use substrings to define more IPL volumes. For this example, &SYSR1 = RESA01.
SYSDEF
 SYMDEF(&SYSR2='&SYSR1(1:4).02') /*SYSR2 resolves to the first */
                                 /*four characters in SYSR1 and    */
                                 /*the hard-coded 02. SYSR2=RESA02 */
 SYMDEF(&SYSR3='&SYSR1(1:4).03') /*SYSR3 resolves to the first */
                                 /*four characters in SYSR1 and    */
                                 /*the hard-coded 03. SYSR3=RESA03 */
Example 4: Use the system-provided symbol to set the initial IPL VOLSER and also use substrings to define more IPL volume names, using literal text. For this example, &SYSR1 = SRSAAA.
SYSDEF
SYMDEF(&SYSR2.='SRS2&SYSR1(-2:2)')  /* &SYSR2 resolves to SRS2AA */
SYMDEF(&SYSR3.='SRS3&SYSR1(-2:2)')  /* &SYSR3 resolves to SRS3AA */