TM and MSC Message Routing and Control User exit routine (DFSMSCE0)

This topic contains Product-sensitive Programming Interface information.

Subsections:

• About this routine
• Sample IMS configurations
• Defining entry points
• Authorization checking
• Attributes of the routine
• Communicating with IMS

About this routine

The DFSMSCE0 user exit routine does the following:

• Eases TM and MSC coding and maintenance requirements, and reduces the number of exit modules.
• Supports a consistent set of routing capabilities across all of the exit entry points (or functions).

  This exit routine receives control for all User Type messages from:

  • Terminal/message input
  • MSC link input
  • Application program output
  Restriction: The DFSMSCE0 user exit routine is not called for DL/I ICAL requests for synchronous program switch.

  In turn, the exit is allowed to affect the routing of most of these messages. Exceptions are cases where rerouting would violate IMS™ architecture or cause problems such as hung terminals or incorrect application program operation. For example, rerouting application program output messages to the I/O PCB is one of these exceptions (it is not allowed), or affinity routing of synchronous APPC/OTMA transaction messages to another IMS in a shared queues environment when the resource recovery service or APPC/OTMA enablement service is not set.

  For details on the routing capabilities for each exit entry point, see the user reroute flags MSTRFL2 (terminal), MSLRFL2 (MSC link), and MSPRFL2/MSPRFL3 (application) in the DFSMSCEP user parameter list mapping tables in Table 2. Messages will be canceled or rerouted if you have set one of more of these flags in conjunction with the destination type.

  The user reroute request flags are MSTRFL2 (terminal), MSLRFL2 (MSC link), and MSPRFL2/MSPRFL3 (application). Setting one or more of these flags in conjunction with changing destination type fields, causes the message to be canceled or rerouted (see following note).

  See the DFSMSCE0 sample exit for examples of message routing.

  For affinity routing restrictions, see the topic "Managing APPC and OTMA messages in a sysplex environment" in IMS Version 13 System Administration.

  DFSMSCEP parameters that the exit can set or change to affect message routing are marked with a "U" or "B" as follows:

  I

  IMS SETS (EXIT MUST NOT CHANGE)

  U

  USER EXIT SETS

  B

  BOTH IMS/USER EXIT SET (OR CHANGE)

• Provides a common parameter list interface and linkage interface to the various entry points (or functions).
• Provides the ability to append an optional user prefix segment to TM and MSC messages which TM and MSC user exit routines can use to communicate and control user-customized routing needs.
• Provides new entry points:
  • Control at IMS initialization and termination
  • Control of messages in an MSC intermediate system
  • Application program inserts to a non-modifiable PCB
  All the entry points are optional, using a vector table that you code at the beginning of the common exit module.
• Logs routing errors and footprints in the message to indicate those exit routines that reroute the message.

Sample IMS configurations

These samples describe four separate IMS configurations and the points where the DFSMSCE0 exit routine receives control during the flow of a transaction and response message.

Single IMS system

In a single IMS environment, the TR exit routine can receive control when a message is received from the terminal. The PR exit routine receives control when an application program issues a CHNG call to a modifiable PCB or on an ISRT call to a I/O or ALT PCB to insert a message, or a GU call to the I/O PCB.

Figure 1. Single IMS system environment

Multiple Systems Coupling environment

In an MSC environment, the following occurs:

1. The TR exit routine receives control when a message is received from a terminal.
2. The PR exit routine receives control when the application program issues a CHNG call to a modifiable PCB or on an ISRT call to an I/O or ALT PCB to insert a message, or a GU call to the I/O PCB.
3. The LR exit routine receives control each time a message is received on an MSC link. The following figure shows the message flow when the transaction is received on the MSC link in IMSB (LR1) and on the MSC link in IMSC (LR2). In the response message flow, the LR exit receives control when the message arrives on the MSC link in IMSB (LR3) and when it arrives in IMSA (LR4).

Figure 2. MSC environment

Shared-queues environment

A shared-queues environment is similar to a single-IMS environment. The TR exit routine receives control on the front-end IMS system, when the message is received from the terminal. The PR exit routine receives control on the back-end IMS system when the application program receives control and issues a CHNG or ISRT call to insert a message (PR).

The PR exit routine receives control when the application program issues a CHNG call to a modifiable PCB or on an ISRT call to the I/O or ALT PCB to insert a message, or a GU call to the I/O PCB.

Figure 3. Shared-queues environment

Shared-queues MSC environment

The following occurs in a shared-queues MSC environment:

1. The TR exit routine receives control in the front-end IMS system when the transaction message is received from the terminal.
2. The PR exit routine receives control in the front-end IMS (PR1), the back-end IMS (PR2), or the remote IMS (PR3) systems when the application program receives control and issues a CHNG call to a modifiable PCB or on an ISRT call to the I/O or ALT PCB to insert a message, or a GU call to the I/O PCB.
3. The LR exit routine receives control in the remote IMS system when the transaction message is received on the MSC link (LR1), and then in the back-end IMS system when the response message is received on the MSC link (LR2).

In a shared-queues environment, two additional levels of affinity routing are available for messages destined to a transaction. One level requests the transaction message to be routed locally on the current IMS system. This is referred to as local affinity. The other level requests the transaction message to be routed to the back-end IMS system. This is referred to as back-end affinity. Affinity routing is available in the terminal, link receive, and program routing entry points.

Figure 4. Shared-queues MSC environment

Defining entry points

You can define the entry points and conditions for IMS to call the DFSMSCE0 exit routine by coding the user vector table macro (DFSMSCVT). In the front of the module, code the VECTOR=MSCVTABLE parameter in the DFSMSCSV macro to point to the resulting vector table. The DFSMSCVT macro supports 12 entry points that you can specify to select those conditions for which the exit routine is called (2 for IMS initialization and termination, and 10 entry points in the flow of TM message processing).

The entry points enable:

• Rerouting a message to a different destination name or a different remote IMS in a MSC system.
• Requesting transaction affinity processing (processing messages in a specific IMS) in a shared queues IMSplex system by requesting that the message process locally in the current IMS or in a different back-end IMS.
• Rejecting the message

The DFSMSCE0 user exit routine can change the routing of a message by setting flags and fields in the user parameter list that IMS passes to the exit routine. This parameter list is mapped by the DFSMSCEP macro, and then returned to IMS. The parameter list contains:

• Fields and flags to indicate IMS conditions, such as MSC or shared-queues system definition
• Information regarding the message, such as source and destination names and MSC system identifiers (SYSIDs) for routing control

Some of the information in the parameter list is for reference only, while other information can be changed to affect the rerouting of the message. See the DFSMSCEP macro, described in Table 2 through Table 7, for more information.

At any of the user exit entry points (other than the initialization or termination entry points), the exit routine can request a user prefix segment to be added to the message. If a user prefix is already obtained for this message by a previous call to the exit routine, IMS passes the address of the user prefix to the exit routine. The exit routine can reference or change the user prefix, but cannot delete it or change its length. This prefix can contain user routing information that can be passed to the other routing exit entry points to be used to reroute the message. After the user prefix is obtained, it remains appended to the message and is logged with the message (for example, a type 01 or type 03 message log record is mapped by the QLOGMSGP macro).

For each routing request, the user exit routine is passed a 512–byte work area that is initialized to zeros and that the user exit routine can use as a work area, such as for creating a user prefix.

No IMS System Definition changes are needed to invoke the DFSMSCE0 exit routine, and MSC does not need to be available; however, several of the routing functions are only available for MSC messages. The DFSMSCE0 exit routine is loaded at IMS initialization, provided that the load module is link edited into IMS.SDFSRESL or a user library concatenated to IMS.SDFSRESL.

Authorization checking

The exit call during link receive processing controls the level of authorization checking. The level of authorization is controlled by the field MSLRFL3 of the parameter list during link receive. IMS sets one of the flags in MSLRFL3 when calling the link receive entry points to indicate which level of security checking is active. If the message is a local transaction message, resetting or changing this flag will override the level of security to be performed for this message. Flag MSLRFL1 can be tested to determine if the message is a local transaction. The following parameters in the MSLRFL3 field specify the level of authorization:

MSLR3MSN

Authorization by MSNAME. The accessor environment element (ACEE) dynamically created for first authorization, then reused.

The specification of MSLR3MSN causes the security environment based on the MSNAME to be built the first time it is needed for an authorization check. Thereafter, the environment is saved and is reused for subsequent checking.

MSLR3CTL

Authorization by CTL address space security. The specification of MSLR3CTL uses the security environment of the CTL address space that already exists.

MSLR3USR

Authorization by user ID of input terminal. ACEE dynamically created and deleted for each authorization.

The specification of MSLR3USR causes the security environment based on the user ID of the input terminal (that entered the transaction) to be built each time it is needed for an authorization check.

MSLR3XIT

Authorization by user exit (DFSCTRN0). MSLR3XIT can be specified by itself, or with either MSLR3MSN, MSLR3CTL, or MSLR3USR. The specification of MSLR3XIT causes DFSCTRN0 or DFSCTSE0 to be called, if they exist.

MSLR3NON

No security authorization checking.

MSLR3NON can only be specified without any of the other four options. The specification of MSLR3NON bypasses all security checking, and allows the use of the transaction destination.

MSLR3MSN, MSLR3CTL, and MSLR3USR are mutually exclusive. The use of MSLR3MSN, MSLR3CTL, or MSLR3USR causes RACF® (or an equivalent product) to be called for authorization of the use of the transaction destination.

On entry, the MSLRFL3 field contains the system default value from MSCSEC=(,xxx) in the DFSDCxxx PROCLIB member. The exit can then override the system default, or leave it as is.

Attributes of the routine

The TM and MSC Message Routing and Control user exit routine must be written as reentrant. The exit routine receives control while running in a 31-bit addressing mode, and must return control in that mode. The exit routine is called in TASK mode, with no locks held, and can be in cross memory, non_AR mode.

Communicating with IMS

This topic provides information about how to communicate with IMS using the DFSMSCE0 user exit routine.

Contents of registers on entry

On entry, the exit routine must save all registers using the provided save area. The registers contain the following:

This exit routine uses the Version 6 standard exit parameter list. The address of the work area that is passed to this exit routine in SXPLAWRK can be different each time that this exit routine is called.

The DFSMSCE0 user parameter list and field definitions are mapped by the DFSMSCEP macro.

The initialization entry parameter list and field definitions are mapped by the DFSMSCEP macro.

The termination entry parameter list and field definitions are mapped by the DFSMSCEP macro.

The terminal routing parameter list and field definitions are mapped by the DFSMSCEP macro.

The link receive parameter list and field definitions are mapped by the DFSMSCEP macro.

The program routing parameter list and field definitions are mapped by the DFSMSCEP macro.

The DFSMSCE0 exit routine is called with one caller save area in R13. Field MSCESSET in DFSMSCEP points to six preformatted save sets for the exit routine's use. The routine (INITSAV) in the sample exit routine (DFSMSCE0) chains these save sets to the caller save set and moves R13 to the first save set in MSCESSET. This allows the DFSMSCE0 exit routine to call other routines and to pass a save set chain. When DFSMSCE0 returns to IMS, the DFSMSCLV macro (Linkage=Yes) returns to the caller save set and restores registers.

Callable services

Storage services and control block services can be performed by invoking IMS callable services. This exit routine can use callable services with the ECB passed at MSCEECB of the user exit PARMLIST.

This exit routine can use IMS Callable Storage Services. This exit routine is defined to IMS as an IMS standard user exit. Exit routines that are defined to IMS receive the callable services token in the standard exit parameter list. This exit routine does not need to issue an initialization call (DFSCSII0) to use IMS callable services.

The exit routine receives control at the following points: the Terminal Routing (TR) call, the Link Receive (LR) call, and the Program Routing (PR) call. In each situation, if the DFSMSCE0 user exit routine is called (based on the DFSMSCVT vector entry) and obtains a user prefix, IMS attaches the prefix to the message and passes it on to other DFSMSCE0 entry points.

For each entry point parameter selected by the DFSMSCVT macro, the exit routine must provide a label for the entry point, as shown in the following table.

The DFSMSCVT macro parameters listed in the preceding table have the following characteristics:

INIT entry point

Receives control at IMS initialization, immediately after the exit routine is loaded.

TERM entry point

Receives control at IMS termination when IMS is shutting down. The INIT and TERM entry points are not associated with a message.

The next 4 entry points are for the Link Receive (LR) user exit routine:

LRTRAN

Receives control when a message is received on an MSC link, and the destination is a local transaction in the received system.

LRLTERM

Receives control when a message is received on an MSC link, and the destination is a local LTERM in the received system.

LRDIR

Receives control when a direct-routed message is received for the local IMS system. The destination can be an LTERM or a transaction. Direct-routed messages are created by an application program running in a remote MSC system that inserts messages using directed routing (in other words, inserts messages to a PCB MSNAME destination).

LRINT

Receives control for any message received on an intermediate IMS system (in other words, a message received on an MSC link that is destined to another remote MSC system). This includes intermediate messages that are inserted by a remote IMS system using directed routing.

The next 2 entry points are for the Program Routing (PR) user exit routine:

PRCHNG

Receives control when an application program issues a CHNG call to a modifiable PCB.

PRISRT

Receives control when an application program issues the first ISRT call (first segment) to a modifiable PCB, non-modifiable PCB, or I/O PCB.

PRGU

Receives control when an application program issues a GU call to a I/O PCB. The exit may request or update a user prefix but no message routing is supported.

Using user prefixes

Messages contain a variety of prefixes that IMS uses to route and process the message. These prefixes are mapped by the QLOGMSGP macro, and are in front of the message, before the user data segments. These prefixes are for internal IMS use. DFSMSCE0 can add a user prefix to this message. This prefix is mapped by the DFSMSCUP macro. The exit routine can build this prefix in one of two ways:

• Test the field MSCEUPR in DFSMSCEP for zero to see if a user prefix already exists. If not obtained (zero), build a prefix in the 512–byte work area by addressing some area in the work area that is large enough to hold the prefix. Set bytes 0 and 1 to the prefix length (5 to 512 bytes), storing the address back in MSCEUPR. The exit routine can then alter the user data portion of the prefix (bytes 4 to 512). When the exit routine returns control to IMS, IMS sets the prefix code (byte 2 = 8E) and the reserved flag (byte 3) and copies the prefix to the message.
• Test the field MSCEUPR in DFSMSCEP for zero to see if a user prefix already exists. If not obtained (zero), set flag MSCE2UPR=1 and field MSCEUPRL to the length of the requested prefix (5 to 512 bytes) and return to IMS. IMS obtains storage that is large enough for the user prefix and stores the address in MSCEUPR, resets flag MSCE2UPR, and returns control to the exit routine. The exit routine can then alter the user data portion of the prefix (bytes 4 to 512). When the exit routine returns control to IMS, IMS sets the prefix code (byte 2 = 8E) and the reserved flag (byte 3) and copies the prefix to the message, and then frees the original prefix storage.