Defining OTMA routing rules

OTMA routing rules enable you to specify routing behavior for IRM messages. They describe which OTMA routing lists to use to route messages that have a given original IMS data store identifier (IRM_IMSDESTID). To define OTMA routing rules, select option 1.9 OTMA Routing Rules from the IMS Connect Extensions primary menu.

The OTMA Routing Rules panel displays a list of rules defined in your IMS Connect Extensions repository. Use the Filter field to list only items that match a filter pattern.

Figure 1. The OTMA Routing Rules panel in the IMS Connect Extensions ISPF dialog

   File  Menu  Settings  Help 
 ──────────────────────────────────────────────────────────────────────────────
                     OTMA Routing Rules                  Row 1 from 4 
 Command ===> NEW                                              Scroll ===> PAGE

 Filter . . .           (Blank or pattern)

 Enter "/" to select action
             Original  - Rule Condition Qualifier -- ------- Applies to -------
 /  Name     Datastore Qualifier Type       Listname Type   Definition Plan
    ALLRULE  SY10      TRANSACTION          TXLLA    ALL               WEEKLY
    CEX2112  TESTDS    TRANSACTION          TLIST1   ALL               MAINT
    OTRR1    SBDS1     NONE                          ALL             
    OTRR2    SXB001    NONE                          SYSTEM SBPI02   
 ******************************* Bottom of data ********************************

To define a new OTMA routing rule, enter NEW on the Command line. Enter the 1-8 character name of your routing rule and press Enter. The OTMA Routing Rule panel is displayed. In this dialog you will define the routing behavior for messages with a specified DestID.

Figure 2. The OTMA Routing Rule panel in the IMS Connect Extensions ISPF dialog

   File  Menu  Settings  Help 
 ──────────────────────────────────────────────────────────────────────────────
                     OTMA Routing Rule                              
 Command ===>                                                                  

 Name  . . . . : ALLRULE  
 Description . . All-systems rule               

 Apply rule to:                       Rule is active when:                      
 3  1. System  . . . . .           +     Routing Plan . . WEEKLY    +
    2. Group . . . . . .           +     Rules with no plan are always active
    3. All systems                      

 Condition:                                                                     
    Original Datastore . SY10      (IRM_IMSDestId)
    Additional qualifier TRANSACTION           +
       List name . . . . TXLLA     +

                                                       ---- Routing lists ----- 
 /  Message types                                      Target    +  Fallback  + 
    Send-Receive Transactions                                                
 Y  Send-Only requests                                 SBMRL                 
    Resume TPIPE requests                                                    
    Synchronous call-out resume TPIPE requests                               
    Synchronous call-out responses

The panel displays the following information:

Name

The name of the OTMA routing rule.

Description

A description of this routing rule.

Apply rule to

Specifies the IMS Connect system or systems to which this rule will apply. Choose from the following options:

1 System: Apply the rule to a single system. Use the the Prompt function key (F4) to select from a list of defined systems. To define an IMS Connect system, see Defining IMS Connect systems.
2 Group: Apply the rule to a group of systems. Use the the Prompt function key (F4) to select from a list of defined groups. To define a group, see Defining system groups.
3 All systems: Apply the rule to all IMS Connect systems.

Routing Plan

Optional. Assign the routing rule to a routing plan. A routing plan defines a group of routing rules that are intended to operate at the same time.

Use the Prompt function key (F4) to select from a list of defined routing plans. To define a routing plan, see Defining routing plans.

Note: A routing rule that is not assigned to a routing plan will always be in effect, except when it is overridden by a routing rule that contains a more specific message matching condition.

Condition

Specifies the conditions that must be met by the incoming IRM message for the rule to take effect. Select from the following options:

Original Datastore (IRM_IMSDestId)

A value that is to be matched against the string that appears in the IRM_IMSDESTID field on incoming IRM messages in order to select this OTMA routing rule for the incoming message. For more information on IRM structures for IMS Connect client messages, see Format of user portion of IRM for HWSSMPL0, HWSSMPL1, and user-written message exit routines in the IMS user documentation.

Important: The value supplied by the client in the IRM_IMSDESTID message field does not have to be the name of an IMS data store defined in the IMS Connect configuration member. In IMS Connect Extensions, the value it receives is simply used identify matching messages to which this rule applies. As such, there are several options available when specifying a value on this panel:

The value can be a fully qualified IMS data store name (for example, IMSA, which will only be applicable if it is a direct match to the IRM_IMSDESTID field.
The value can be a prefix string with a trailing asterisk (for example, IMS*) which indicates that the IRM_IMSDESTID field need only match the prefix string component of the name in order to be selected.
The value can be a single asterisk (*) which matches any IRM_IMSDESTID field value.

When multiple rules exist that contain overlapping IRM_IMSDESTID values, more specific name values in the Original Datastore field take precedence over less specific values such as masked name values. Only the first OTMA routing rule found to match the IRM_IMSDESTID field for a given incoming message is activated.

Additional qualifier

Specifies an optional condition that qualifies this rule. Use the Prompt function key (F4) to select a qualifier type. The following options are available:

NONE: The routing rule has no additional qualifiers. The rule will match on the IRM_IMSDESTID only. The rule will take precedence over any other rules that match on the same IRM_IMSDESTID and also specify an additional qualifier.
TRANSACTION: The routing rule will only take effect for the named transactions that match the IRM_IMSDESTID. Use the Prompt function key (F4) on the List name field to select a transaction list. To define a transaction list, see Defining transaction lists.
Note: If you use the TRANSACTION qualifier, you may also wish to define an additional unqualified rule (Additional qualifier = NONE) for the same IRM_IMSDESTID to act as a master rule. If you specify a qualifying rule without a matching master rule in the repository, an implied routing rule will be generated internally at run time. Use the message log to review the set of routing rules that are in effect. Messages CEX5091I and CEX5191I list the routing rules that are in effect. See Browsing the message log for an IMS Connect.

Message types

Route messages to IMS data stores based on the message type.

When an incoming message is matched to the name in the Original Datastore field, IMS Connect Extensions selects a routing list based on the message type.

For each of the listed message types, choose from the following options.

Y: Enable routing for this message type. Requests that match this routing rule are routed to a list of IMS data stores specified in the Target field. Use the optional Fallback field to specify a list of fallback IMS data stores in the event that the IMS data stores listed in the Target field are unavailable. Use the Prompt function key (F4) to select a list of defined OTMA routing lists. To define an OTMA routing list, see Defining OTMA routing lists.
blank: Inherit settings from rules applying to the same condition (IRM_IMSDestID) at either the All systems or Group level. A Group level rule will inherit settings from the All systems level. A system level rule will inherit settings from the Group level, if one is defined, otherwise from the All systems level. The Target and Fallback fields are ignored and no routing will occur.
N: Disable OTMA rules-based routing. In other words, this rule will not apply to this message type at the level specified in the Apply rule to field. Any values in the Target and Fallback fields are ignored and no routing will occur.

If there is no higher level rule for the condition, then INHERIT (blank) is the same as DISABLE (N).

For SYSTEM the higher level is GROUP and ALL.
For GROUP the higher level is ALL.
for ALL there is no higher level.

The following message types are supported:

Send-Receive Transactions: Standard IMS Connect transactions.
Tip: This message type can also be used to route IMS commands if CEXROUTE IMSCMDROUTE=YES is specified in the control input data set. See Control input data set options.
Send-Only requests: IMS Connect Send Only requests.
Resume TPIPE requests: IMS Connect Resume TPIPE (RTPIPE) requests.
Resume TPIPE requests do not have a transaction code, and may be paired with Send Only messages. If you are pairing Send Only requests with Resume TPIPE requests, use the same collection of target and fallback IMS data stores for both message types and ensure all data stores are part of the same shared queue. If the messages can be routed to more than one IMS Connect system, then all IMS Connect systems that will handle a Send Only with Resume TPIPE transaction must refer to the same Super Member.
Note: Routing Resume TPIPE requires an OTMA Super Member and shared queues.
Synchronous call-out resume TPIPE requests: Routing for Resume TPIPE (RTPIPE) messages marked as synchronous callout requests.
Synchronous call-out responses: Routing for synchronous callout responses.

Tip: Use IRM field IRM_F4 to help you determine the types of messages in your environment. To view this part of the IMS request message (IRM) use IBM IMS Problem Investigator for z/OS to browse the IMS Connect Extensions journal. For more information on IRM, see Format of user portion of IRM for HWSSMPL0, HWSSMPL1, and user-written message exit routines in the IMS user documentation. See also Reporting and analysis with IMS Problem Investigator.

To save the new routing rule, press the Exit function key (F3). The new routing rule is displayed in the OTMA Routing Rules panel.

Before OTMA routing rules can take effect, you must select the Activate OTMA rules option in the system definition. See Defining IMS Connect systems.