IMSCTRL macro

The IMSCTRL macro is required. This macro instruction must be the first statement of the system definition control statements that are entered into the system definition stage 1 for an IMS or a DBCTL system. You can have only one IMSCTRL macro instruction within an IMS system definition.

The only other macro instruction required for a batch environment is IMSGEN.

• Dynamic definition
• Supported environments
• Syntax
• Positional parameters
• Keyword parameters

Dynamic definition

The IMS control region cannot be dynamically defined. However, you can export the MODBLKS resource definitions that are generated by the environment created using this IMSCTRL macro for subsequent dynamic definition of applications, databases, transactions, and routing codes.

Supported environments

The IMSCTRL macro must be the first macro defined in the DB/DC, DBCTL, and DCCTL environments.

Syntax

A

Positional parameters

The IMSCTRL macro does not include positional parameters.

Keyword parameters

To find which parameters apply to your IMS configuration, refer to Selecting the appropriate macros to define your system.

CMDCHAR=

/

The default value.

c

Any character except comma (,), less than (<), or greater than (>). Ampersand (&) must be entered as && to define it as the command character.

NONE

No command recognition character (CRC) is defined.

CMDCHAR can be specified for DBCTL, DB/DC, or DCCTL. The value of CMDCHAR can be specified at execution time by specifying execution parameter CRC=.

With a DBCTL system, CMDCHAR specifies the command recognition character used by the MTO to enter IMS commands for this DBCTL environment. If CMDCHAR=NONE is specified and the CRC is not specified as an execution parameter (CRC=), then commands are entered for this DBCTL system with a prefix of the IMSID.

DB/DC and DCCTL systems allow commands to be entered at MCS/E-MCS consoles with a CRC prefix by specifying execution parameter keyword CMDMCS with a value other than N.

The CRC can be specified with CMDCHAR or with CRC at execution time.

If CMDCHAR=NONE is specified and the CRC is not specified as an execution parameter (CRC=), commands are entered for the DB/DC or DCCTL system with a prefix of the IMSID.

Although other products and subsystems might use certain command recognition characters, the CRC is not required to be unique among all IMS systems. Choose an unreserved character that is appropriate for your particular system.

Do not use a character for the CRC that is the same as the beginning character of a z/OS command. If the CRC is the same as the beginning character of a z/OS command, that command does not work after you start IMS. For example, if you start IMS with CRC=D, z/OS does not respond to any of the z/OS display commands such as D A,L.

The CRC value you select might affect multisegment command processing. The last character of the command is checked during multisegment command processing. If that character matches the CRC, the command is assumed to be a multisegment command. Processing of the command waits for the rest of the command. For example, if you use B for the command recognition character, and issue the command BMODIFY PREPARE ACBLIB, the command does not run. The ending 'B' in 'ACBLIB' is interpreted to indicate a multisegment command. To enter this command correctly, enter:

'BMODIFY PREPARE ACBLIB.  '

The character you choose for a DB/DC system becomes the command recognition for the IMS system. If your installation allows commands from MCS or E-MCS consoles, you need a CRC only if both of the following statements are true:

• IMS provides DBCTL service to a CCTL.
• CCTL broadcasts an IMS SWITCH command preceded by a CRC.

CMDCHAR does not affect the normal DB/DC MTO's use of the ⁄ character when entering IMS commands.

DBRC=

The system definition process ignores this parameter, though for compatibility purposes, it can still be coded.

DBRCNM=

Specifies for z/OS the IMS.PROCLIB member containing the skeletal procedure for the DBRC address space. The IMS control region automatically initiates the DBRC address space, using the z/OS start command and specifying this name. To rebuild the DBRC procedure, you must use the IMS.PROCLIB member containing the skeletal procedure for the DBRC address space. This procedure can be obtained from IMS.SDFSPROC data set and contains the name you specify in stage 1.

Consequently, the DBRC procedure must be copied from IMS.PROCLIB to SYS1.PROCLIB. For more information, see Making IMS and IMSRDR procedures accessible to z/OS.

You can specify up to an eight-character name, the first character being alphabetic. The default name is DBRC.

Specifying DBRCNM=xxxxxxxx results in the following:

• A DBRC address space cataloged procedure is created with the name xxxxxxxx.

To make the DBRC address space cataloged procedure name of xxxxxxxx operational, the following must be true:

• A DBRC address space must be cataloged as xxxxxxxx in SYS1.PROCLIB.

Simply specifying DBRCNM=xxxxxxxx in your IMS system definition is not sufficient.

DCLWA=

Establishes a default value that IMS applies to any transactions defined by subsequent TRANSACT macro statements. DCLWA= specifies whether (YES) or not (NO) IMS should perform log write-ahead for recoverable nonresponse-mode input messages and transaction output messages. The default is YES. If no value is specified for DCLWA= on the IMSCTRL macro, the value for DCLWA= on any subsequent TRANSACT macros accepts the default of YES, or you can specify YES or NO on the individual TRANSACT macros.

Specify or accept the default of YES to ensure that:

• A nonresponse-input transaction is made recoverable across IMS failures, before IMS acknowledging receipt of the input.
• Database changes are made recoverable before IMS sending associated output reply messages.

YES ensures that information in the log buffers is written to the IMS log before the associated input acknowledgment or output reply is sent to the terminal.

Specify or accept the default of YES for all VTAM® terminal types.

Specify NO if input message integrity and the consistency of output messages with associated database updates is not required. DCLWA does not apply to response mode or Fast Path input processing, and, if specified in these situations, is ignored during IMS execution.

DESC=

Specifies the message descriptor codes to be assigned to the IMS system console messages if MCS support is included in the z/OS system definition. You can specify up to 16 values. If DESC is not specified, the default value is 7.

The IMS MCS= and DESC= keywords should be defined as is required for the ROUTCDE and DESC keywords of the z/OS WTO macro.

DLINM=

Specifies for z/OS the IMS.PROCLIB member to contain the skeletal procedure for the optional DL/I address space. The IMS control region automatically initiates the DL/I address space using the z/OS start command and specifying this name.

Consequently, the DL/I procedure must be copied from IMS.PROCLIB to SYS1.PROCLIB. You probably need to modify the skeletal procedure. This procedure can be obtained from IMS.SDFSPROC data set.

For more information, refer to Member Name DLISAS in Environments that support IMS.SDFSRESL procedures.

You can specify up to an eight-character name, the first character being alphabetic. The default name is DLISAS.

Specifying DLINM=xxxxxxxx results in the following:

• A DL/I address space cataloged procedure is created with the name xxxxxxxx.

ETOFEAT=

Specifies whether the system definition process should build ETO descriptors. The default is not to build the ETO descriptors.

The first two parameters of the ETOFEAT keyword are no longer valid and are ignored if specified. Commas appear in place of these parameters in the syntax diagram.

The third parameter indicates whether the system definition process should produce ETO descriptors only (ONLY), produce descriptors along with a normal system definition (ALL), or produce a normal system definition without descriptors (NO). The default is NO.

If you have not installed ETO, the ETO option is forced off.

HSB=

Specifies whether or not an XRF-capable system is generated. The default is NO.

If you specify NO, an XRF-capable system is not generated.

If you specify YES, an XRF-capable system is generated and ISC has duplexed blocks. If you plan to run XRF or an alternate subsystem before the next planned cold start of IMS, specify HSB=YES on the IMSCTRL macro to eliminate the need for a subsequent IMS system definition and cold start.

XRF is disabled if no value is specified for HSBID in the DFSPBIMS or DFSPBDCC members, or in the IMS execution JCL. Informational message DFS3899I is issued.

IMSID=

Specifies a one- to four-character alphanumeric identifier for the IMS system.

For IMS control region: Specifies a one- to four-character identifier that is a valid subsystem identifier to the operating system being used. It can be overridden by the IMSID= keyword specified in the startup procedures.

For IMS dependent regions: Specifies a one- to four-character identifier that is a valid subsystem identifier to the operating system to which this dependent region connects. It can be overridden by the IMSID= keyword specified in the startup procedures.

For IMS batch region: Specifies a one- to four-character IMS identifier that is used in IMS messages that are written to the system log. It can be overridden by the IMSID= keyword specified in the startup procedures.

Recommendation: Specify a unique IMSID for each batch region. This helps to avoid confusion as to which region has issued a console message.

Do not use characters for the IMSID that match the beginning characters of a z/OS command. If the IMSID is the same as the beginning characters of a z/OS command, that command does not work after you start IMS. For example, if you start IMS with IMSID=D, z/OS does not respond to any of the z/OS display commands such as D A,L.

For online control regions, the IMSID must be different from any other IMS subsystem identifier or non-IMS subsystem identifier defined to the operating system under which IMS is running. This identifier is also used to relate messages that are routed to the z/OS system console with the corresponding IMS system. To avoid confusion as to which region has issued a console message, specify a unique IMSID for each batch region. This is however, not a requirement.

The IMSID name must not be the same as the procedure name that starts IMS unless one of the following is true:

• All DD statements in the startup procedure are cataloged in the master catalog.
• The unit and volume are specified on each DD statement.

IRLM=

IRLM=NO specifies that the IRLM is not used by online or batch systems unless overridden at execution time.

IRLM=YES specifies that the IRLM is used by online and batch systems unless overridden at execution time.

If the IRLM= parameter is omitted, and IRLMNM= is specified, the IRLM default is set to YES, but can be overridden by the IRLM=N parameter at execution time.

If the both the IRLM= parameter and the IRLMNM= parameter are omitted, the IRLM default is set to NO but can be overridden at execution time. If it is overridden at execution time, a default value of IRLM is used for the IRLMNM= parameter.

If the IRLMNM= parameter is omitted and the IRLM= parameter is specified, a warning assembly error message is issued stating that the IRLM= parameter is invalid, and NULL is assumed. A default value of IRLM is used for the IRLMNM= parameter if IRLM=Y is specified in the execution JCL.

IRLMNM=

Specifies a one- to four-character alphanumeric name assigned to the Internal Resource Lock Manager (IRLM) included in your system.

If the IRLMNM= parameter is not specified, the IRLM is not invoked by batch or online systems by default. To invoke the use of the IRLM by a batch or online system, you must code IRLM=Y in the execution JCL.

When the IRLMNM= parameter is not specified in the IMSCTRL macro or in the execution JCL, and IRLM=Y is specified in the execution JCL, the IRLM name that is used is IRLM.

The IRLM must be active in your system if your IMS system is to share data at the block level with other IMS systems. The IRLM is optional for systems that do not share data at the block level.

Only one IRLM can be specified for any IMS system (and thus, only one IRLMNM), but multiple IRLMs can exist within a particular z/OS system. Each IRLM must be defined as a z/OS subsystem.

The name specified on this IRLMNM= parameter must be the z/OS subsystem name assigned to the IRLM with which this IMS system is to connect. If IMS is connected to an executing copy of IRLM, Db2 for z/OS cannot connect to it. If Db2 for z/OS is connected to an executing copy of IRLM, IMS cannot connect to it.

If this parameter is specified and not overridden with the IRLM=NO parameter on the online or batch startup procedures, IMS only completes initialization if the named IRLM is available at execution time. Also, IMS uses the named IRLM for all locking services, both local and sharing. Program isolation locking is not used.

It is important to understand the interaction of this IRLMNM parameter with the DBRC parameter and with the ACCESS parameter on the DATABASE macro statement.

MAXCLAS=

Specifies the range of active (started) classes after IMS initialization. Valid values are decimal numbers from 1 to 999. The default is 1. Any transaction code class specified on either the APPLCTN or TRANSACT macro statement must not exceed this value. If the class is not active at the time of scheduling, the schedule request is treated as if the class were stopped.

MAXIO=

Is no longer used. If MAXIO is specified the value is ignored.

MAXREGN=

Specifies the maximum number of IMS control block sets that are permanently allocated. A control block set is required for each dependent region type (batch message processing, message processing, or CCTL threads) that can be started. (Note that this does not imply that the same number of dependent regions are always active.)

This value must be a decimal number from 1 through 999. When the count of dependent regions started exceeds the value specified by the MAXREGN= parameter, control block sets are dynamically allocated, but the storage for these sets is released as the dependent regions terminate. The default is 3.

The second through fourth fields specify region size (default value is 52 KB), region job class (default class is A), and job message class (default class is A).

Region size (which must be expressed in terms of xxK), region job class, and job message class must conform to the operating system JCL specifications. This operand is ignored for BATCH system definitions.

MCS=

Specifies the z/OS routing code to be assigned to the IMS system console if multiple console support (MCS) is included in the operating system. If MCS is not specified, the default is (2,7).

Although z/OS supports more than 16 route codes, IMS uses only route codes 1 through 16.

In a DBCTL environment, MCS= defines which consoles are to receive unsolicited DBCTL messages.

MSVID=

Specifies a one- to three-digit decimal number 1 - 676 that is used to complete the eight-character name of the generated IMS Multiple Systems Verification utility control blocks module generated for this system (DFSMSxxx). If fewer than three decimal digits are specified, the value is right-justified and filled to the left with zeros. (For example, specifying 3 creates the name DFSMS003.)

This control blocks module is assembled and bound during IMS system definition stage 2 processing. The Multiple Systems Verification utility procedure (IMSMSV) is, as the user directs, placed into the IMS.PROCLIB data set.

The MSVID= keyword:

• Is applicable only to resources in the IMS.MODBLKS data set that are defined by system definition.
• Is required when MSVERIFY is specified in the SYSTEM keyword.
• Is ignored if no multiple systems definition statements are present.
• Is ignored for DBCTL.
• Must be present to generate the IMS Multiple Systems Verification utility control blocks and procedure.

The MSC Verify utility (DFSUMSV0) can verify resources defined by system definition. It cannot verify resources defined dynamically, because those resources are no longer in MODBLKS. However, you can use the /MSVERIFY command to verify resources that are defined dynamically.

The specification of MSVID on the IMSCTRL macro statement is not related to the specification of SYSID on the MSNAME macro statement.

NAMECHK=

Specifies whether (YES) or not (NO) resource name checking and cross-checking are to be performed, and, if NAMECHK=NO, whether sorting is to be performed in stage 1 (S1) or stage 2 (S2).

If duplicate resource name checking and resource name cross-checking are performed (that is, NAMECHK is specified as or uses the default of YES), sorting must be performed in stage 1 (S1 specified or used by default). If resource name checking is to be bypassed, sorting can occur in either stage 1 (S1 specified or by default) or stage 2 (S2 specified).

It is suggested that you use the default values for NAMECHK unless:

• You have run the preprocessor before your stage 1 run and you want to omit resource name checking here (by specifying NAMECHK=NO).
• You have a specific performance reason for having IMS sort in stage 2 (for example, you generally run stage 1 multiple times per stage 2).

Related reading: For information about the options available to you by including or omitting the preprocessor in combination with options on the NAMECHK parameter, see Verifying the stage 1 input.

SYSTEM=

Specifies the operating system configuration and the type of IMS system definition to be performed.

The first SYSTEM= parameter must be VS/2, indicating the operating system is z/OS.

The second SYSTEM= parameter consists of two subparameters. The first subparameter defines type of system definition. The definition types are: ALL, BATCH, CTLBLKS, MODBLKS, MSVERIFY, NUCLEUS, and ON-LINE.

The second SYSTEM= subparameter defines the system definition environment class. The three system definition environment classes are:

DB/DC

Builds a standards IMS system. DB/DC is the default.

DBCTL

Builds only the DBCTL environment.

DCCTL

Builds only the DCCTL environment.

If you do not specify DBCTL on the second subparameter, the following functions are always included:

• All enhanced security codes and commands
• All MFS code, commands, procedures, and default formats
• VTAM code and commands, whenever VTAM is requested

The MFS format library is a required data set (regardless of whether MFS is used), except for DBCTL systems.

The MSVERIFY,DBCTL type/class combination is invalid. An error message is generated for invalid combinations.

The third SYSTEM= parameter indicates the operating system; the default is 390 (z/OS).

When you first install IMS, you must perform a full system definition. Thereafter, you can perform a subset of the full system definition to add or change a function. The parameters used in these subset system definitions are described in this topic.

The SMP JCLIN process should be run after the stage 1 of all definition types.

ALL

Combines the BATCH and ON-LINE options.

BATCH

Moves required modules from the IMS distribution libraries to the user's libraries; it also generates system procedures and a database system.

A BATCH definition should not be run to add maintenance or to add or delete database functions or features to a residence library that contains a nucleus with the Data Communication feature.

CTLBLKS

Generates control block modules of all IMS control blocks for use within an IMS nucleus in the IMS control program region. The blocks built in the MODBLKS option are also included in this definition. This subparameter should be specified to replace the control blocks of an existing nucleus. If you are performing a CTLBLKS definition, the new nucleus must have the same suffix as the old nucleus. SMP maintenance integrity is lost if you rename the nucleus before using it in a CTLBLKS definition because SMP does not recognize the contents of the renamed nucleus. To change the control blocks in an existing nucleus, do a CTLBLKS definition. To generate a new nucleus, do a NUCLEUS definition.

The SMP JCLIN process should be run after the stage 1 of a CTLBLKS definition.

A CTLBLKS specification generates the MSC Verification Utility control blocks, if MSC definitions are present. When you specify CTLBLKS, you need not perform a separate system definition with MSVERIFY.

If any device or option is to be deleted during a CTLBLKS definition, unresolved references may exist when the nucleus is bound. This can also happen if logical terminal names are added or deleted before the occurrence of master or secondary master logical terminal names.

MODBLKS

Generates the control blocks members for resources to be added or changed online. These control blocks are used by the IMS control region and the Multiple Systems Coupling Verification utility.

The MODBLKS system definition requires that the stage 1 input contains all source statements for the existing system to which the online changes are to be made, except for communication specifications. If you use the Multiple Systems Coupling MSVERIFY utility, all source statements, including communication specifications, are required input to your stage 1 run. However, if communication specifications are omitted from a MODBLKS system definition, the following stage 1 error checking is not performed:

• Transaction names are not cross-checked against LTERM names to locate duplicates.
• For MSC users, the remote system ID (SYSID) on the TRANSACT macro statement is not checked against the remote system ID (SYSID) on the MSNAME macro statement to ensure that they are not duplicates.

Thus, omitting communication statements can result in undetected system definition errors. You must therefore consider your requirements for improved stage 1 performance against the possibility of undetected errors in your stage 1 input to determine whether you want to include or omit communication statements from your MODBLKS system definition input.

Only APPLCTN, DATABASE, TRANSACT, and RTCODE statements can be added, deleted, or modified. The restrictions pertaining to these modifications are found in the descriptions of these macro statements. IMS does not enforce these restrictions; rather, you are responsible for adhering to the directions provided there.

The effects of a MODBLKS system definition are made known to the IMS online system with a master terminal operator /MODIFY command sequence.

Stage 2 assembler output for a MODBLKS system definition is placed in IMS.OBJDSET. Binder output for the control blocks members affected by running an online change is placed in IMS.MODBLKS.

Certain types of changes, when made across a MODBLKS system definition, do not affect an existing resource except across a cold start. That is, the effects of prior commands are not negated by online change procedures. For example, resources that have been modified by commands such as /START, /STOP, /ASSIGN, /MSASSIGN are not altered, nor are resources whose status has been altered because of changes in the operating configuration (for example, a resource stopped because of an error condition).

Important: If you run stage 1 and stage 2 processing using the IMSCTRL macro without specifying MODBLKS, a cold start is required. Failing to specify MODBLKS causes updates to IMS.SDFSRESL, which requires the new IMS.SDFSRESL to be copied and, therefore, a cold start.

MSVERIFY

Generates a subset of the online control blocks required for execution in a multiple-IMS system configuration. MSVERIFY also generates the bind JCL and control statements required to place the Multiple Systems Verification utility into the IMS.SDFSRESL data set. This subparameter should be specified to generate a test system to verify, before attempting online execution, the consistency of definitions in an MSC configuration. This keyword causes an assembly error if the multiple systems definition statements are not present. If MSVERIFY is specified, MSVID is required.

NUCLEUS

Generates an IMS nucleus for the IMS control program region and control block modules for all IMS control blocks. This subparameter should be specified when generating an alternate nucleus that includes new or deleted old system features, such as additional terminal support or conversational support. A NUCLEUS specification generates the MSC Verification utility control blocks if MSC definitions are present. If NUCLEUS is specified, you do not need to perform a separate system definition, with MSVERIFY specified, to obtain the blocks.

To change the control blocks in an existing nucleus, do a CTLBLKS definition. To generate a new nucleus, do a NUCLEUS definition.

The SMP JCLIN process should be run after the stage 1 of all definition types.

ON-LINE

Moves required modules from the IMS distribution libraries to the user's libraries, generates system procedures, and generates those modules that contain the CTLBLKS and NUCLEUS options for an IMS system. It generates the assembler language and bind statements for all operating systems and VTAM-sensitive modules that are supplied in source form.

You must specify ON-LINE with the hyphen.

Usage information

Guidance information is provided to help you select the CTLBLKS, NUCLEUS, ON-LINE, or MODBLKS system definition type to use when modifying an existing ALL type of system definition. The guidelines can help you determine whether modification of parameters at execution can preclude the need for a new system definition.