from the new book, An Introduction to IMS™: Your Complete Guide to IBM’s Information Management System, Prentice Hall PTR, 2004.

The IMS system definition process:

• Describes the IMS resources to IMS:
• At installation time
• When maintenance is applied
• When standard application definition changes are required
• Assumes a working knowledge of the z/OS system modification program/extended (SMP/E). SMP/E is required for installation and is used as part of the IMS system definition process.
• Is evolving to be more dynamic (versus static) over time.

Related Reading: For information about SMP/E, refer to the SMP/E V3R2.0 User’s Guide.

Extended Terminal Option (ETO), a separately priced feature of IMS™, enables you to define resources dynamically, without shutting down IMS. With ETO, you can dynamically add or delete VTAM terminals and users to your IMS outside of the IMS system definition process. For more information about ETO, refer to The Extended Terminal Option (ETO).

In this article:

• Overview of the IMS System Definition Process
• IMS System Definition Macros
• The Extended Terminal Option (ETO)

Overview of the IMS System Definition Process

The IMS system definition process comprises many steps. Some steps occur only for certain types of IMS definitions (refer to Types of IMS System Definitions). The basic steps involved in IMS system definition are:

1. Modify or tailor IMS-supplied macro statements and procedures (JCL) to define the IMS system that your business requires. These macro statements and procedures are the building blocks for your IMS system (refer to IMS System Definition Macros).
2. Run the IMS preprocessor to check the macros and procedures for correctness (refer to figure 19-1).
3. Stage 1 assembly, in which you run the JCL that you modified in step 1 through the z/OS High Level Assembler program to assemble your program into the JCL that is required as input to stage 2 (refer to Stage 1 of the IMS System Definition Process).
4. Stage 2 assembly, in which you build the IMS executable load modules and, optionally, build MFS default formats and perform updates to IMS.PROCLIB (refer to Stage 2 of the IMS System Definition Process).
5. JCLIN, which is an SMP/E process that tells SMP/E how to assemble and bind modules (refer to JCLIN Processing).
6. Use the SMP/E APPLY command to process any maintenance that has not been processed using the SMP/E ACCEPT command (refer to SMP/E Maintenance).
7. Optionally, perform an IMS Security Maintenance utility generation, which generates a set of secured-resource tables (refer to IMS Security Maintenance Utility Generation).

Figure 19-2 shows an overview of the stage 1 and stage 2 components of the system definition process.

 

Types of IMS System Definitions

There are seven different types of IMS system definitions. You use the IMSCTRL macro statement to describe the type of IMS system definition to be performed, the basic IMS control program options, and the z/OS system configuration under which IMS is to execute. The IMSCTRL options that specify the different types of system definitions are described in table 19-1.

After your initial system definition, the ON-LINE, CTLBLKS, and NUCLEUS types of system definition can be used to implement changes. The ON-LINE, CTLBLKS, and NUCLEUS types of system definitions require a cold start of the IMS online system to take effect.

For certain changes to your IMS system, however, you can take advantage of the online change method using the MODBLKS type of system definition. With the MODBLKS type of system definition, the changes are made active during the execution of the online system and do not require a restart operation.

Related Reading: For the details about the different types of system definition, refer to “Using the Macro Table” in IMS Version 9: Installation Volume 2: System Definition and Tailoring.

Stage 1 of the IMS System Definition Process

Stage 1 of the system definition process uses the z/OS High Level Assembler program and uses the IMS macros as input, as described in IMS System Definition Macros. Other references are to the IMS distribution macro libraries (IMS.ADFSMAC).

The output from stage 1 of the IMS system definition process includes:

• Standard assembler listing output with any appropriate error messages.
• Stage 2 system definition input JCL, which is also used for the JCLIN process.

Depending on what is specified in the IMSGEN macro1 for stage 1, stage 2 of the system definition process can be divided up into a single job with multiple steps, or into many jobs with fewer steps.

Stage 2 of the IMS System Definition Process

Stage 2 of the system definition process assembles and binds all the modules that are required to build the necessary load modules, depending on what type of system definition is being run.

The steps involved in stage 2 refer to the IMS distribution macro library (IMS.ADFSMAC) at assembly time, and the distribution load library (IMS.ADFSLOAD) at bind time.

The output of stage 2 of the system definition process includes:

• Executable load modules in data sets IMS.SDFSRESL and IMS.MODBLKS.
• IMS options definitions in the data set IMS.OPTIONS.
• Assembled object code for use in later system definition steps in the data set IMS.OBJDSET.
• Optionally, the runtime IMS. PROCLIB data set.

The PROCLIB= parameter in the IMSGEN stage 1 macro determines whether the IMS.PROCLIB data set is to be populated by this system definition. The IMS.PROCLIB library contains IMS started tasks and JCL procedures, as well as the IMS.PROCLIB members required by IMS and IMS utilities to provide options.

• Optionally, the runtime IMS default MFS screens in data sets IMS.FORMAT, IMS.TFORMAT, and IMS.REFERAL.

The MFSDFMT= parameter in the IMSGEN stage 1 macro determines whether the default message format screens are built as part of stage 2 of the system definition process.

1. You specify the assembler and binder data sets and options, and the system definition output options and features in the IMSGEN macro.

JCLIN Processing

Because the stage 2 system definition process actually assembles and binds the IMS modules based on the definitions for that particular system and is run outside of SMP/E control, the input JCL for system definition stage 2 must be used as input to the JCLIN process. This input JCL ensures that SMP/E knows how to manage any maintenance that is added to the system following this IMS system definition.

Run the JCLIN process following any IMS system definition, to ensure that SMP/E is always synchronized with the updated IMS.

SMP/E Maintenance

All IMS system definitions use the IMS SMP/E distribution libraries and the IMS stage 1 macros as input. As a result, any SMP/E maintenance (SYSMODs - PTFs, APARs or USERMODs) that processed using the SMP/E APPLY command, but not processed using the SMP/E ACCEPT command, prior to an IMS system definition, might be regressed as a result of that IMS system definition, depending on the type of IMS system definition, and the impact of the SYSMOD.

Related Reading: For more information about performing SMP/E maintenance on IMS, refer to “IMS Service Considerations” in IMS Version 9: Installation Volume 1: Installation Verification.

IMS Security Maintenance Utility Generation

For security beyond that provided by default terminal security, you can use the various security options provided by the Security Maintenance utility (SMU) or by RACF (or equivalent product). You define the RACF security for IMS resources outside of the IMS system definition process.

The SMU is executed offline after the completion of stage 2 of the system definition process. The output of the SMU is a set of secured-resource tables, which are placed in the MATRIX data set. The tables are loaded at system initialization time and, for certain options, work with exit routines and RACF during online execution to provide resource protection.

R E C O M M E N D A T I O N: Any maintenance that has been processed using the SMP/E APPLY command, but not processed using the SMP/E ACCEPT command, should be processed again (using both commands) following an IMS system definition, unless further investigations have shown specific cases where this is not necessary.

IMS System Definition Macros

The IMS system definition macros change from release to release of IMS. Refer to a specific version of IMS Installation Volume 2: System Definition and Tailoring for version-specific details about the system definition macros. The IMS Version 9 system definition macros are briefly summarized here:

APPLCTN: The APPLCTN macro allows you to define the program resource requirements for application programs that run under the control of the IMS DB/DC environment, as well as for applications that access databases through DBCTL. An APPLCTN macro combined with one or more TRANSACT macros defines the scheduling and resource requirements for an application program. Using the APPLCTN macro, you only describe programs that operate in message processing regions, Fast Path message-driven program regions, batch message processing regions, or CCTL threads. You also use the APPLCTN macro to describe application programs that operate in batch processing regions. When defining an IMS data communication system, at least one APPLCTN macro is required.

BUFPOOLS: The BUFPOOLS macro specifies default storage buffer pool sizes for the DB/DC and DBCTL environments. The storage buffer pool sizes specified are used unless otherwise expressly stated for that buffer or pool at control program execution time for an online system.

COMM: The COMM macro specifies general communication requirements that are not associated with any particular terminal type. The COMM macro is always required for terminal types that are supported by VTAM, and might also be required to specify additional system options, such as support for MFS on the master terminal.

CONFIG: The CONFIG macro statement provides the configuration for a switched 3275 terminal. Because the configuration provided by the CONFIG macro is referenced when the named 3275 dials into IMS, differently configured 3275 terminals can use the same communication line. All CONFIG macro statements must be between the LINEGRP macro and the LINE macros. LINE macros can refer to named CONFIG macros defined previously in this line group or in previously defined line groups.
CTLUNIT: The CTLUNIT macro specifies 2848, 2972, and 3271 control unit characteristics. The CTLUNIT macro is valid only for 3270 remote line groups.

DATABASE: The DATABASE macro defines the set of physical databases that IMS manages. One DATABASE macro statement must be specified for each HSAM, HISAM, HDAM, or PHDAM database. Two DATABASE macro statements are required for each HIDAM or PHIDAM database: one for the INDEX DBD and one for the HIDAM or PHIDAM DBD. One DATABASE macro instruction must be included for each secondary index database that refers to any database that is defined to the online system. For Fast Path, a DATABASE macro statement must be included for each main storage database (MSDB) and data entry database (DEDB) to be processed.

FPCTRL: The FPCTRL macro defines the IMS Fast Path options of the IMS control program, and the DBCTL environment. The FPCTRL macro is ignored when the IMSCTRL statement specifies that only a BATCH or MSVERIFY system definition is to be performed.

IDLIST: The IDLIST macro statement is used to create a terminal security list for switched 3275s.

IMSCTF: Defines additional options and system parameters under which IMS is to operate.

IMSCTRL: The IMSCTRL macro statement describes the basic IMS control program options, the z/OS system configuration under which IMS is to execute, and the type of IMS system definition to be performed.

The IMSCTRL macro instruction must be the first statement of the system definition control
statements.

IMSGEN: IMSGEN specifies the assembler and binder data sets and options, and the system definition output options and features.

The IMSGEN macro must be the last IMS system definition macro, and it must be followed by an assembler END statement.

LINE: The LINE macro provides the address and characteristics of one line in the line group specified by the LINEGRP statement. The LINE macro describes both switched and nonswitched communication lines to IMS.

LINEGRP: The LINEGRP macro defines the beginning of a set of macro instructions that describe the user’s telecommunications system.

MSGQUEUE: The MSGQUEUE macro defines the characteristics of the three message queue data sets: QBLKS, SHMSG, and LGMSG. The information you specify in this macro is also used in a shared-queues environment. The MSGQUEUE macro is required for all DB/DC and DCCTL systems.

MSLINK: The MSLINK macro defines a logical link to another system.

MSNAME: The MSNAME macro provides a name for the remote and local system identifications that it represents.

MSPLINK: The MSPLINK macro defines a physical MSC link.

NAME: The NAME macro defines a logical terminal name (LTERM) that is associated with a physical terminal. You might need to provide a NAME macro for the following macros: TERMINAL, SUBPOOL, MSNAME.

POOL: The POOL macro describes a pool of logical terminals that are associated with a set of switched communication lines.

RTCODE: The RTCODE macro is used one or more times with the APPLCTN macro that defines a Fast Path application program. The RTCODE macro specifies the routing codes that identify the program named in the preceding APPLCTN macro. A TRANSACT macro that specifies an IMS Fast Path-exclusive transaction builds an internal RTCODE macro with a routing code that is identical to the transaction code.

SECURITY: The SECURITY macro specifies optional security features that are in effect during IMS execution unless they are overridden during system initialization.

STATION: The STATION macro describes the physical and logical characteristics of System/3 or System/7 remote intelligent stations.

SUBPOOL: The SUBPOOL macro, when used in a VTAM macro set, is a delimiter between groups of NAME macros that create LU 6.1 LTERM subpools.

When the SUBPOOL macro is used in a switched communication device macro set, the SUBPOOL macro defines a set of logical terminals.

TERMINAL: The TERMINAL macro defines physical and logical characteristics of VTAM nodes and non-VTAM communication terminals.

TRANSACT: The TRANSACT macro is used one or more times with each APPLCTN macro to identify transactions as IMS exclusive, IMS Fast Path potential, or IMS Fast Path exclusive. The TRANSACT macro specifies the transaction codes that cause the application program named in the preceding APPLCTN macro to be scheduled for execution in an IMS message processing region. The TRANSACT macro also provides the IMS control program with information that influences the application program scheduling algorithm.

TYPE: The TYPE macro defines the beginning of a set of communication terminals and logical terminal description macros that include the TERMINAL and NAME macros. The TYPE macro begins a description of one set, which contains one or more terminals of the same type. The TYPE macro defines terminals attached to IMS through VTAM and is equivalent to the LINEGRP and LINE macro set that is used to define terminals attached to IMS by means other than VTAM.

VTAMPOOL: The VTAMPOOL macro, required for parallel session support, begins the definition of the LU 6.1 LTERM subpools.

The Extended Terminal Option (ETO)

The IMS Extended Terminal Option (ETO) allows you to dynamically add VTAM terminals and users to your IMS: they do not need to be predefined during system definition. ETO is a separately priced feature of the IMS Transaction Manager (TM) and provides additional features such as output security, automatic logoff, and automatic signoff.

By using ETO, you can achieve each of the following goals:

• Improved system availability by reducing the scheduled down time that is associated with adding or deleting VTAM terminals.
• Faster system availability to users, because they can establish an IMS session from any VTAM terminal in the network.
• Improved IMS security by relating output messages to users, rather than to terminals.
• Reduced number of macros required to define the terminal network. This reduces system definition time and storage requirements.
• Reduced checkpoint and restart time. For ETO terminals and user structures, resources are not allocated until they are actually required; similarly, when they are no longer required, they are deleted.
• Reduced number of skilled system programmer resources that are required for maintaining static terminal definitions.

Related Reading: For more information about ETO, refer to IMS Version 9: Administration Guide: Transaction Manager.

ETO Terminology

The following sections describe the terms that have ETO-specific meanings. These meanings are important for understanding ETO.

Terminals: A terminal is a physical VTAM logical unit (LU) that establishes a session with IMS. A physical terminal is represented using a control block.

When a terminal is not built by ETO but is defined at system definition, it is called a static terminal. A static terminal can be a VTAM node. When messages are sent to a static terminal they are queued to a logical terminal (LTERM) message queue, where they await retrieval by the recipient. When a terminal is not defined at system definition and ETO builds a terminal, that terminal is called a dynamic terminal, or an ETO terminal. For dynamic terminals, the logical terminal (LTERM) is known as a dynamic user message queue, and the LTERM associates the messages with the user, rather than with the physical terminal. Associating messages with the users provides more security for these users, because they can access their messages only when they sign on using their unique user ID. In addition, all users in the network can access their messages from any physical terminal, instead of being restricted to using a particular physical terminal.

Dynamic User: A dynamic user is a user who signs on to a dynamic terminal and who has a unique identification (user ID) that IMS uses for delivering messages. The user is usually associated with a person but can also be associated with another entity, such as a printer.

Terminal Structure: A terminal structure is a control block that represents a specific terminal that is known to IMS. A terminal structure is created when the individual terminal logs on to IMS and is deleted when the terminal logs off with no remaining associated activity.

User Structure: A user structure is a set of control blocks, including a user block and one or more LTERM blocks. The message queues are associated with the dynamic user, as opposed to the physical terminal, and they are queued to the user ID. Usually, a user structure represents a person who uses IMS.

The dynamic user structure connects to the physical terminal only when the user signs on. This provides a secure environment, because different users accessing the same terminal cannot receive each other’s messages.

IMS creates a user structure when either of the following events takes place:

• A dynamic user signs on to IMS.
• Output messages that are destined for a dynamic user are sent to the user, but the user has not signed on to IMS.

The user structure name is usually the same as the user ID. A user structure can also represent a logical destination, such as a printer. In this case, the user structure name can be the same as or different from the LTERM name that your installation uses in its application programs and its exit routines. For example, you can assign the same name to a user structure for a printer that you assign to its LTERM destination node name. However, output is then queued according to the terminal, and not to the user.

Figure 19-3 illustrates:

• A physical terminal (Node LU1)
• Two logical terminals (LTERM LT1A and LTERM LT1B) that are defined as being associated with Node LU1
• The message queues that are associated with logical terminals LTERM LT1A and LTERM LT1B
• The traditional, static system definition for LU1, LTERM LT1A, and LTERM LT1B

Figure 19-4 illustrates:

• A physical terminal (Node LU1)
• A dynamic user (US1)
• Two dynamic logical terminals (LTERM US1 and LTERM US2) that are dynamically associated with user US1
• The dynamically built user message queues that are associated with logical terminals LTERM US1 and LTERM US2
• The dynamic definition (descriptor) that IMS builds for LU1, US1, LTERM US1, and LTERM US2

Descriptors

A descriptor provides information to IMS when IMS builds a dynamic resource for a logon or a signon. IMS stores the descriptors in two IMS.PROCLIB members, DFSDSCMx and DFSDSCTy.

For more information about these PROCLIB members, refer to IMS Version 9: Installation Volume 2: System Definition and Tailoring.

IMS uses four types of descriptors:

• Logon descriptors
• User descriptors
• MSC descriptors
• MFS device descriptors

 

Logon Descriptors

A logon descriptor is a skeleton that IMS uses to build an ETO dynamic terminal. It provides information regarding a terminal’s physical characteristics. IMS uses logon descriptors in conjunction with exit routines to create terminal structures.

IMS uses three types of logon descriptors:

Generic: A generic logon descriptor provides characteristics for all terminals of a particular type. For example, all SCS printers might share a single generic descriptor. Similarly, all 3270 terminals might share a generic logon descriptor.

Group: A group logon descriptor provides characteristics for a collection of terminals, each of which has compatible hardware characteristics and is defined to IMS in the same manner. The characteristics of these terminals are usually identical, but they can differ. IMS uses the group logon descriptor to derive their characteristics.

Specific: A specific logon descriptor provides characteristics for a single terminal, and these characteristics apply only to that terminal. The specific descriptor name matches the name of the terminal that it describes.

User Descriptors

A user descriptor is a skeleton from which IMS builds a user structure. A user descriptor can provide user options and queue names.

MSC Descriptors IMS uses an MSC descriptor to create a remote LTERM, which is an LTERM that does not exist on the local IMS. The physical terminal definition (either static or dynamic) for the remote LTERM is in the remote IMS.

Each MSC descriptor for a remote LTERM is loaded during IMS initialization and tells IMS which MSC link to use for output destined for that remote LTERM.

MFS Device Descriptors An MFS device descriptor allows you to add new device characteristics for MFS formatting without requiring an IMS system definition. The MFS Device Characteristics Table utility (DFSUTB00) uses MFS device descriptors to update default formats in the MFS library.

R E C O M M E N D A T I O N: Although you might need to use specific logon descriptors during the actual migration to ETO, use generic logon descriptors or group logon descriptors after you have migrated to ETO; these types of descriptors ease network administration.

IMS also uses MFS device descriptors to update the MFS device characteristics table. IMS loads this table only during initialization; therefore, updates are not effective until the next IMS initialization.

How Structures are Created and Used

Structures are created in the following situations:

• Logon
• Signon
• Output is queued to your LTERM
• /ASSIGN command is used to assign an LTERM to a non-existent user
• /ASSIGN command is used to assign a non-existent LTERM to a user
• /CHANGE USER user AUTOLOGON command is directed to a non-existent user

In all cases, IMS searches for an existing terminal or user structure before creating a new one. IMS creates and deletes user structures in the following sequence:

1. When you establish a session between IMS and an undefined terminal, IMS selects a logon descriptor.
2. Using the information in the logon descriptor, the customization defaults, and VTAM information, IMS builds an IMS terminal control block (called a VTAM terminal control block or VTCB) that describes the new terminal.
3. When you sign on, if a user structure does not exist, IMS builds one, using information from a user descriptor that it selects, and then connects this user structure to the terminal structure.
4. IMS deletes terminal structures or user structures when they are no longer needed to maintain sessions. User structures are typically deleted when you sign off, if no special status needs to be maintained and if no messages remain queued. IMS deletes terminal structures when no terminal status exists (such as trace mode), no user is signed on, and the terminal is idle.

If you are using the Resource Manager and a resource structure, IMS normally maintains status in the resource structure instead of the local control blocks. Therefore, IMS deletes the resource structures.

This sequence applies only to terminal logon and logoff and to user signon and signoff. When asynchronous output is queued to a user, IMS creates the user structure, as needed.

Related Reading: For more information about the Resource Manager, refer to “Resource Manager,” An Introduction to IMS™: Your Complete Guide to IBM’s Information Management System, or IMS Version 9: Common Service Layer Guide and Reference. For more information about how IMS manages terminal and user structures, refer to IMS Version 9: Administration Guide: Transaction Manager.

Descriptors and Exit Routines

Using descriptors and exit routines, you can assign characteristics to dynamic terminals and assign user structures to be associated with those dynamic terminals.

A descriptor provides the basic information for the dynamic terminal. An exit routine completes or changes this information. Two methods of using descriptors and exit routines are:

• You can use many descriptors and code little or no processing logic in exit routines.
• You can use few descriptors and code exit routines to perform much of the processing.

How Descriptors Are Created and Used

All descriptors are created during IMS initialization, prior to IMS startup. You must specify that you want ETO support and ensure that the ETO initialization exit routine (DFSINTX0) does not disable ETO support.

During IMS initialization, IMS reads and validates all ETO descriptors. IMS initialization then continues, and the descriptors remain in storage for the duration of IMS execution. Any changes you make to descriptors become effective after the next initialization of IMS.

IMS uses descriptors to create both terminal and user structures. IMS rebuilds structures during an IMS restart, if appropriate. For example, if messages are queued for a structure and IMS shuts down, the structures are rebuilt when IMS restarts. IMS rebuilds these structures to be the same as they were before the IMS restart. IMS does not use the descriptors or exit routines to rebuild these structures. Therefore, any changes you make to descriptors are only reflected in new structures that are built after IMS restart, and the changes are not reflected in structures that are rebuilt during IMS restart.

Example USERA signs on using descriptor DESCA, which specifies an auto signoff time of 20 minutes (ASOT=20). USERA starts an IMS conversation, and then IMS abnormally terminates. The system programmer changes DESCA to ASOT=10. After the IMS restart, USERB signs on using DESCA. USERA’s structure was rebuilt during the IMS restart. USERA still has a value of 20 minutes for the auto signoff time (ASOT=20), and USERB has a value of 10 minutes for the auto signoff time (ASOT=10).

Summary of ETO Implementation

Figure 19-5 shows an overall view of an ETO implementation. The steps that follow correspond to the highlighted numbers in figure 19-5.

1.  The system-defined descriptors that are built during system definition are stored in IMS.PROCLIB as member DFSDSCMx.
2. Your user-defined descriptors that are written to override the system definition defaults are stored in IMS.PROCLIB as member DFSDSCTy. MFS descriptors that are processed by the MFS Device Characteristics Table utility (DFSUTB00) are stored in the device characteristics table.
3. Logon, user, and MSC descriptors are loaded at IMS initialization using the input from IMS.PROCLIB.
4. The Logon and Logoff exit routines are called during logon and logoff.
5. The Signon and Signoff exit routines are called during signon and signoff.
6. Output is delivered to the destination specified in the Output Creation exit routine, unless the user is created during signon.
7. If IMS is unable to determine where output should be delivered, the messages are added to the dead-letter queue. Messages might not be delivered because:

• Figure 19-5: Summary of ETO implementation
• The user signon is rejected.
• A physical-to-logical relationship does not exist between the device and the LTERM.

 

Figure 19-5: Summary of ETO implementation.