Reference information for using IMS macros

Use IMS macro statements to generate a sequence of assembler statements from a single source statement. IMS provides a set of macro statements for system definition.

For example, to describe program resource requirements for your application programs, use the APPLCTN macro. To define characteristics of VTAM® nodes and non VTAM communication, use the TERMINAL macro.

The APPLCTN, DATABASE, RTCODE, and TRANSACT macros are used to define application programs, databases, Fast Path route codes, and transactions. These IMS resources can be changed, added, and deleted by using either dynamic resource definition (DRD) or online change. The online change process requires that some system definition tasks be performed offline. The DRD process, which uses CREATE, DELETE, and UPDATE commands to define these resources, does not require any offline tasks. When DRD is enabled (by specifying MODBLKS=DYN in the DFSCGxxx PROCLIB member), online change for resources in the IMS.MODBLKS data set, but not for other resources, is disabled. Likewise, when DRD is disabled (MODBLKS=OLC in the DFSCGxxx PROCLIB member), commands that are used for DRD, except for some types of the UPDATE command, are not supported. The UPDATE commands that change status or runtime values are supported.

System definition macros and their uses

The following table contains a list of IMS system definition macros. Selecting the appropriate macros to define your system describes which macros and macro keywords can be modified by which type of system definition.

Table 1. System definition macros and their uses
Type of macro statement   Macro name Resources each macro defines
System configuration macros FPCTRL macro Fast Path options
IMSCTRL macro Library naming, JCL options, and ETO feature
IMSGEN macro z/OS system and control options
MSGQUEUE macro Message queue device and message sizes
Database and application macros   APPLCTN macro Program characteristics and PSB names
DATABASE macro DBD names
RTCODE macro Fast Path message routing
TRANSACT macro Transaction processing options
Data communication macros Non-VTAM device1 COMM macro General communication options
LINE macro Communication line to IMS
LINEGRP macro

DD names for communication devices
NAME macro LTERM definition
TERMINAL macro Physical characteristics of terminal
Multiple System Coupling MSLINK macro Logical Link names
MSNAME macro Partner systems
MSPLINK macro Physical link names
NAME macro LTERM definition
VTAM COMM macro General communication options
NAME macro LTERM definition
SUBPOOL macro Set of LTERMs for a static ISC session
TERMINAL macro Physical characteristics of a static terminal
TYPE macro VTAM terminal type
VTAMPOOL macro Multiple systems with ISC sessions
1 See the LINEGRP UNITYPE= keyword for detailed information.

Resource naming rules

These rules and restrictions apply to all IMS macros.
  • Names cannot include a blank, comma, period, hyphen, or equal sign.
  • All PSB and DMB names must begin with an alphabetic character (alphabetic = A through Z, #, $, and @) followed by zero to seven alphanumeric characters.
  • The PSB name, DBF#FPU0 is a reserved name.
  • For route codes, DBFDFRT1 is a reserved name.
  • Logical terminal names and transaction codes must be one to eight alphanumeric characters in length. (Alphanumeric = A through Z, #, $, and @, 0 - 9.) Each name within the set comprising LTERM names and transaction codes must be unique.
  • User IDs that are passed to RACF® must be one to eight alphanumeric characters, that is, letters A through Z, digits 0 - 9, and the national characters #, $, and @.

    For ETO terminals, if the user ID is used to build the LTERM structure, the user ID must be one to eight alphanumeric characters.

  • Node names must be unique among themselves, but can duplicate LTERM names, transaction codes, or subpool names.
  • Subpool names must be unique among themselves, but can duplicate LTERM names, transaction codes, or node names.
  • IMS null words must not be used as resource names (FOR, TO, ON, AFTER, and SECURITY). Also, resource names must not begin with DFS (except for DFSIVPxx and DFSSAMxx, and DFSCONE for transactions) or DBCDM; nor should WTOR, MSDB, SDB, DBRC, BASICEDT, or ISCEDT and its aliases be used as a resource name.
  • Command keywords must not be used as resource names.

    Related reading: For more information about command keyword restrictions, see List of reserved words.

  • Symbolic names can be used to define 3270 and SLU Type 2 devices. See the description of the TYPE= keyword of the TERMINAL macro statement for the format of these names. A symbolic name must be used to define the format of any 3270 display device with a screen size other than 480 or 1920 characters.
  • Resource names must not end with the IMS ID or the CRC character that was chosen by coding the CMDCHAR parameter of the IMSCTRL macro. The last characters of a command are checked during multisegment command processing. If the characters match the IMS ID or the CRC, the command is assumed to be a multisegment command. Command processing waits for the rest of the command.

    For example, if you define a NODE whose name ends with IMS ID IMSA, and you issue the command IMSADIS NODE xxxxIMSA, the command does not run. The ending IMSA in the NODE name indicates a multisegment command. To run this command, enter:

    'IMSADIS NODE xxxxIMSA. '

Maximum occurrences of each IMS system definition macro statement

Each IMS macro statement can appear in an IMS system definition a limited number of times.

The maximum number of IMS resources that can be defined is a design limit (that is, a theoretical limit). You should not assume that your installation can successfully define the maximum number of IMS resources that is shown in the following table. The actual limit on this number is influenced by many limiting factors in your hardware and software configuration.

If you are defining and generating resources into the IMS.MODBLKS data set that is defined as a partitioned data set (PDS), one factor that limits the number of IMS resources that can be defined is the maximum size, 16 M, of a PDS member. The actual number of IMS resources that can be defined for a MODBLKS data set defined as a PDS depends on the size of the resource control block:
  • 16777215/184 (SMB length from SMBTOTSZ) = 91,180 transactions
  • 16777215/112 (PDIR length from PDIRLEN) = 149,796 programs
  • 16777215/48 (RCTE length from RCTELEN) = 349,525 routing codes
  • Databases are limited to 32,700.
If you are defining and generating resources into the IMS.MODBLKS data set that is defined as a partitioned data set extended (PDSE), one factor that limits the number of IMS resources that can be defined is the maximum size, 2 G, of a PDSE member. The actual number of IMS resources that can be defined for a MODBLKS data set defined as a PDSE depends on the size of the resource control block:
  • 2147483647/184(V14 SMB length from SMBTOTSZ) = 11,671,106 transactions
  • 2147483647/112(V14 PDIR length from PDIRLEN) = 19,173,961 programs
  • 2147483647/48(V14 RCTE length from RCTELEN) = 44,739,242 routing codes
  • Databases are limited to 32,700.

The following table shows the maximum number of times each macro statement can occur.

Table 2. Maximum occurrences of each IMS system definition macro statement
Macro statement Maximum occurrences
APPLCTN

149,796 for PDS
19,173,961 for PDSE
BUFPOOLS 1
COMM 1
DATABASE1 32,700
FPCTRL 1
IDLIST 1000
IMSCTRL 1
IMSGEN 1
LINE 1000
LINEGRP 676 - (Number of MSPLINK macros specified)
MSGQUEUE 1
MSLINK 676 or 9996
MSNAME 676
MSPLINK 676 or 9996 - (Number of LINEGRP macros specified)
NAME 999,999 - (Number of switched line macros specified)
RTCODE

349,525 for PDS
44,739,242 for PDSE
SUBPOOL 999,999 - (Number of TERMINAL and STATION macros specified)
TERMINAL2 200,000
TRANSACT

91,180 for PDS
11,671,106 for PDSE
Transaction Edit Routines3 255
TYPE 200,000
User routines4 200
VTAMPOOL5 1
Notes:
  1. In IMS execution, database allocation is limited to the number of DD names that z/OS allows.
  2. Because of the size of the IMS control block, the maximum number of static terminal resources that can be defined is approximately 200,000.
    Recommendation: If your system includes many terminals, use the ETO feature. By using the ETO feature, you can manage terminals more effectively during IMS online activity.
  3. Transaction Edit routines are specified in the EDIT operand of the TRANSACT macro. Although the limit of TRANSACT statements is 999,999, only 255 transaction edit routines are accepted.
  4. User Routines: Refer to the user-supplied physical terminal output and input edit routines (specified in the EDIT operand of the LINEGRP and TYPE macros).
  5. VTAMPOOL is used once for each set of LU 6.1 subpools defined. It can be used multiple times within a system definition to define multiple sets of LU 6.1 subpools.
  6. The MSLINK and MSPLINK maximum occurrences are 999.

Coding conventions

All IMS installation information uses the following conventions in coding macros and examples:
  • Uppercase letters, stand-alone numbers, and punctuation marks must be coded exactly as shown. The only exceptions are subscripts, which are not coded.
  • Lowercase letters, words, and associated numbers represent variables for which specific values can be substituted.
  • A space or the lowercase b indicates one blank position.
  • If an alternative item is underlined, it is the default. IMS assumes that if none of the items is coded, the underlined item is automatically the choice.
  • You must specify positional parameters in the order shown.
  • You can specify keyword parameters in any order.