Substitution text for the symbols is defined in MVS and is substituted by MVS in place of the symbols during VTAM startup, major node activation, and table activation.

By using MVS system symbols in VTAMLST, you can code a single start option list and a single configuration list that can be used to start VTAM on multiple systems. You can also code one set of major nodes, routing and dynamic reconfiguration definitions, and user-definable tables. You can define and maintain a single VTAM for use on multiple systems.

You can also use MVS system symbols in the TSOKEY00 parmlib member.

In addition, you can use MVS system symbols in VTAM network operator commands and Transaction Processing Facility (TPF) logon manager operator commands. Substitution text for the symbols is defined in MVS and is substituted by MVS in place of the symbols during command processing. This eliminates the need for the operator to know the exact name of a resource when issuing a command on a particular system.

You can use MVS system symbols in non-sysplex and sysplex environments.

Overview

Before coding MVS system symbols in VTAMLST, TSOKEY00, or in VTAM network operator commands or TPF logon manager operator commands, you might want to issue the DISPLAY SYMBOLS command on each system on which you plan to use the symbols. The DISPLAY SYMBOLS command is an MVS command that displays defined symbols and their substitution text for the system on which the command is issued. See z/OS MVS System Commands for information about how to use the DISPLAY SYMBOLS command.

Additional installation-defined symbols can be defined if you need them.

Consider how to best use the defined symbols and any additional symbols you might want to define. System symbols in VTAMLST are most useful for defining system identifiers and names when coding:

• Start options, especially those that specify system names and identifiers; for example, CONFIG, SSCPID, and SSCPNAME.
• A configuration list. Use the symbols in the names of the major node members contained in the configuration list.
• Definitions for major nodes and minor nodes. Use the symbols in the names of definition statements and in the values you specify on operands on the definition statements.
• Definitions for routing and dynamic reconfiguration. Use the symbols in the names of definition statements and in the values you specify on operands on the definition statements.
• The following user-definable tables:
  • APPN Class of Service (COS) definitions
  • APPN-to-subarea COS mapping table
  • Associated LU table
  • Message-flooding prevention table
  • Model name table
  • Subarea-to-APPN COS mapping table
  Use the symbols in the names of macroinstructions and in the values you specify on operands on the macroinstructions.

To use MVS system symbols in VTAM network operator commands and TPF logon manager operator commands, use the symbols in the values you specify on command operands, especially those that specify resource names (for example, ID). You can also use the static system symbols shown in Table 1.

Table 1. MVS static system symbols that can be used in VTAM

Symbol name	Description	Length of text	Where defined	Default substitution text
&SYSCLONE	Shorthand notation for the name of the system; often used in fields that are limited to two characters.	1–2 characters	IEASYMxx parmlib member	Last two characters of substitution text are defined to &SYSNAME symbol.
&SYSNAME	The name of the system	1–8 characters	IEASYMxx or IEASYSxx parmlib member	The processor identifier. See the z/OS MVS Initialization and Tuning Reference and the z/OS MVS Initialization and Tuning Guide for information about the processor identifier.
&SYSPLEX	The name of the sysplex	1–8 characters	COUPLExx or LOADxx parmlib member	If LOADxx does not specify the sysplex name, &SYSPLEX defaults to LOCAL until the COUPLExx member is processed.
&installation- defined system symbol	Up to 100 system symbols defined by your installation	1–8 characters	IEASYMxx parmlib member	None.

During VTAM startup, major node activation, resource activation, table activation, and command processing, MVS substitutes the text defined for these system symbols wherever the symbols appear in VTAMLST, TSOKEY00, and in commands.

Note: Other products, such as NCP and NetView®, use VTAMLST to obtain certain definitions. See the other products' publications to determine how they support MVS system symbols in VTAMLST.

Coding guidelines

Substitution text for system symbols is defined in MVS. For complete information about how to define the symbols, including default substitution text, see the z/OS MVS Initialization and Tuning Reference and the z/OS MVS Initialization and Tuning Guide. This section provides guidelines for coding the symbols in VTAMLST.

The symbols must begin with an ampersand (&) and should end with a period (.). However, if MVS finds a system symbol that does not end with a period, it substitutes text for the symbol when the next character is:

• Null (the end of text is reached)
• A character that is not alphabetical, numeric, or one of the national characters, @, #, or $

For example, if &SYSCLONE is defined in MVS to equal 01—SYSCLONE(01)—and &SYSNAME is defined to equal HOST01A—SYSNAME(HOST01A)—, you could code the symbols in VTAMLST as follows:

…CONFIG=&SYSCLONE.,SSCPNAME=HOST&SYSCLONE.A

or:

…CONFIG=&SYSCLONE.,SSCPNAME=&SYSNAME

It is recommended that you always end MVS system symbols with a period. Otherwise, you risk a higher incidence of syntax errors.

Note: For ease of reading, periods are not shown at the end of symbols in this document, except when the symbols are used in examples.

A symbol name can have one to eight characters between the ampersand and the period.

After MVS substitutes the symbols with the text defined in MVS, VTAM will ensure that the resulting values are valid. Current VTAM coding conventions still apply when MVS system symbols are used in VTAMLST. So, for example, if &SYSCLONE is defined in MVS to equal 01, and CONFIG=&SYSCLONE is coded in VTAMLST, VTAM accepts the resolved value, CONFIG=01. If, however, CONFIG=01&SYSCLONE is coded, VTAM rejects the resolved value, CONFIG=0101, because the value specified on the CONFIG start option must be two characters in length. For information about current VTAMLST coding conventions, see the z/OS Communications Server: SNA Resource Definition Reference.

Example of VTAM definitions in a sysplex environment without the use of MVS system symbols

Following is an example of the VTAM definitions required to enable VTAM to run on two MVS hosts in a sysplex without the use of MVS system symbols.

Two MVS hosts, HOST01 and HOST02, exist in a sysplex. Each host starts VTAM and is running the same VTAM application programs on its system. The following members are defined in the VTAMLST data set to enable this configuration:

ATCSTR01
 
  CONFIG=01,
  SSCPID=01,
  SSCPNAME=HOST01,
⋮
 
ATCSTR02
 
  CONFIG=02,
  SSCPID=02,
  SSCPNAME=HOST02,
⋮
 
ATCCON01
 
  APPLS01
⋮
 
ATCCON02
 
  APPLS02
⋮
 
APPLS01
 
  APPL01A  APPL …
  APPL01B  APPL …
  APPL01C  APPL …
⋮
 
APPLS02
 
  APPL02A  APPL …
  APPL02B  APPL …
  APPL02C  APPL …
⋮

VTAM is started from MVS HOST01 with the following command:

START VTAM,LIST=01

VTAM is started from MVS HOST02 with the following command:

START VTAM,LIST=02

Two separate start option list members are defined in VTAMLST to enable VTAM to be started on both systems:

• ATCSTR01, which specifies names and identifiers to be used when VTAM is started on HOST01
• ATCSTR02, which specifies names and identifiers to be used when VTAM is started on HOST02

Each start option list specifies the name of a configuration list to be used when VTAM is started on that system. Two configuration list members are defined in VTAMLST:

• ATCCON01, which specifies the major nodes to be activated when VTAM is started on HOST01
• ATCCON02, which specifies the major nodes to be activated when VTAM is started on HOST02

Even though identical application programs are to be activated on both systems, because they must have unique names within the sysplex, they must be defined in two separate major nodes with unique names. One major node is specified in one configuration list and the other major node is specified in the other configuration list.

Three application programs are defined in major node APPLS01 with the following names:

• APPL01A
• APPL01B
• APPL01C

Identical application programs are defined in major node APPLS02 with the following names:

• APPL02A
• APPL02B
• APPL02C

APPLS01 is specified in configuration list ATCCON01, indicating that VTAM should activate the major node defined by APPLS01 when VTAM is started on HOST01. Within member APPLS01, the APPL definition statements, APPL01A, APPL01B, and APPL01C are defined, indicating that the application programs defined by these statements should be activated when the major node defined by APPLS01 is activated.

APPLS02 is specified in configuration list ATCCON02, indicating that VTAM should activate the major node defined by APPLS02 when VTAM is started on HOST02. Within member APPLS02, the APPL definition statements APPL02A, APPL02B, and APPL02C are defined, indicating that the application programs defined by these statements should be activated when the major node defined by APPLS02 is activated.

You can see that the more systems you have in a sysplex environment, each running identical VTAM application programs, the more VTAM definitions you must code in VTAMLST.

Using MVS system symbols in a sysplex environment

Following is an example of how the definitions in the previous section can be reduced by using MVS system symbols.

The following members are defined in a VTAMLST data set that is accessible to two MVS systems, HOST01 and HOST02, in a sysplex:

ATCSTR00
 
  CONFIG=00,
  SSCPID=&SYSCLONE.,
  SSCPNAME=&SYSNAME.,
⋮
 
ATCCON00
 
  APPLS
⋮
 
APPLS
 
  APPL&SYSCLONE.A  APPL …
  APPL&SYSCLONE.B  APPL …
  APPL&SYSCLONE.C  APPL …
⋮

How the symbols resolve when HOST01 starts VTAM:

The following substitution text is defined in MVS HOST01:

SYSCLONE(01)
SYSNAME(HOST01)

VTAM is started from MVS HOST01 with the following command:

START VTAM,LIST=00

LIST=00 is not required on the START command because it is the default. VTAM substitutes every instance of &SYSCLONE in VTAMLST with 01 and every instance of &SYSNAME with HOST01. As a result, VTAM uses the following definitions:

ATCSTR00
 
  CONFIG=00
  SSCPID=01,
  SSCPNAME=HOST01,
⋮
 
ATCCON00
 
  APPLS
⋮
 
APPLS
 
  APPL01A  APPL …
  APPL01B  APPL …
  APPL01C  APPL …
⋮

How the symbols resolve when HOST02 starts VTAM:

The following substitution text is defined in MVS HOST02:

SYSCLONE(02)
SYSNAME(HOST02)

VTAM is started from MVS HOST02 with the following command:

START VTAM,LIST=00

LIST=00 is not required on the START command because it is the default. VTAM substitutes every instance of &SYSCLONE in VTAMLST with 02 and every instance of &SYSNAME with HOST02. As a result, VTAM uses the following definitions:

ATCSTR00
 
  CONFIG=00
  SSCPID=02,
  SSCPNAME=HOST02,
⋮
 
ATCCON00
 
  APPLS
⋮
 
APPLS
 
  APPL01A  APPL …
  APPL01B  APPL …
  APPL01C  APPL …
⋮

Using MVS system symbols in a non-sysplex environment

If multiple VTAMs are not in a sysplex environment, but are nonetheless related (for example, in a state university environment where one VTAM is started on campus A and one VTAM is started on campus B) one VTAMLST data set might be copied from the campus A system and installed and used to start VTAM on the campus B system. MVS system symbols can be used in this situation to reduce the system definitions in VTAMLST, much like they are used in the sysplex example "Using MVS system symbols in a sysplex environment". Instead of being two MVS hosts in a sysplex, HOST01 and HOST02 might be the two hosts in the state university environment, HOST01 on campus A and HOST02 on campus B.