Overview

Skill Level: Intermediate

This procedure should be performed by an experienced IMS Connect system administrator

Fallback data stores improve the availability of your IMS environment and allow you to perform maintenance without interrupting incoming client requests.
It is highly recommended that you read the entire recipe before making any changes to your systems.

Ingredients

Use this recipe to configure IMS Connect to route workload to a fallback IMS if the primary IMS is unavailable.

What is a fallback IMS in IMS Connect?

To learn more about what we mean by a fallback IMS and the role of IMS Connect in this process, watch the IBM Z channel video "Routing OTMA workload to a fallback IMS with IMS Connect" on YouTube.

To follow this recipe using your own systems, you will need IMS Connect and IBM IMS Connect Extensions for z/OS. You will need:

  • The IMS Connect Extensions ISPF dialog, to create an OTMA routing rule and several supporting definitions that routes OTMA workloads to a fallback IMS data store.
  • The Operations Console for IMS Connect Extensions, to monitor OTMA workloads and to suspend and resume routing to IMS data stores.

Optionally, you can also use IBM IMS Performance Analyzer for z/OS or the IMS Connect transaction analysis app for Splunk to analyze transaction performance and to view the results of workload redistribution. If you would like to use Splunk, you will need to configure the IMS Connect Extensions feed to collect the necessary records. For more information, see Forwarding a live feed of IMS Connect events to Splunk.

 

Result

In this recipe you will create an OTMA workload routing scheme by creating several definitions in IMS Connect Extensions:

  • Datastores: IMS Connect Extensions datastore definitions. The purpose of these definitions is to inform IMS Connect Extensions about the DATASTORE statements you have defined in IMS Connect.
  • OTMA routing lists: Contains one or more datastore definitions. IMS Connect Extensions requires you to organize datastores into lists for the purposes of rules-based routing.
  • OTMA routing rule: Defines the routing behavior in terms of OTMA routing lists.

The following diagram demonstrates an IMS Connect Extensions-based OTMA fallback routing scheme using these definitions:

IMS Connect Extensions Fallback Routing

Step-by-step

  1. Verify that the desired primary target and fallback IMS data stores are defined in IMS Connect Extensions

    To route OTMA workload in IMS Connect, IMS Connect Extensions needs to know about the IMS data stores you have in IMS Connect. If you have completed the installation procedures described in the IMS Connect Extensions User’s Guide, the necessary definitions will have been created in the IMS Connect Extensions repository. To review these definitions, use the IMS Connect Extensions ISPF dialog.

    From the IMS Connect Extensions primary menu, select option 1 Definitions.

    IMS Connect Extensions Definitions Panel

    Select option 3 Datastores.

    A list of IMS data stores defined in the IMS Connect Extensions repository are displayed in the list. Use this list to identify the IMS data store you wish to use for fallback routing, as well as the IMS data store that serves as the primary data store used under normal operating conditions.

    IMS Connect Extensions Datastores List Panel

    If your IMS data stores are not defined in this list…

    • Run the TAKEUP utility. The utility will locate the DATASTORE statements defined in the HWSCFGxx member of the IMS PROCLIB data set and create the necessary definitions in IMS Connect Extensions. See Creating an initial configuration in the IMS Connect Extensions User’s Guide for further details.
    • Use the IMS Connect Extensions ISPF dialog. Type NEW followed by the data store name and then press Enter.

     

    View the status of the data stores using the Operations dialog. From the IMS Connect Extensions primary menu, select option 2 Operations.

    Select 2 Systems.

    Type DS next to the IMS Connect system and press Enter.

    IMS Connect Extensions Datastore Monitor Panel

  2. Create primary and fallback OTMA routing lists

    To use an IMS data store in an IMS Connect Extensions routing rule, you must first add it to an OTMA routing list. Because we have two IMS data stores which we will use for two different purposes, we will create two lists, one for the primary target and one for the fallback. To do this, return to the Definitions panel and select option 10 OTMA Routing Lists.

    To create the primary target list, type NEW followed by a name for the new routing list and press Enter.

    Add a description if you like.

    Assign the primary IMS data store to this list. To do this, position the cursor on the field beneath the Datastore column and then press the Prompt function key (F4). 

    Type S to select the primary IMS data store and then press Enter.

    IMS Connect Extensions OTMA Routing List Panel

    When you have finished making changes, press the Exit function key (F3). The new routing list is displayed in the OTMA Routing Lists panel.

    Repeat this process for the fallback IMS data store. Type NEW followed by a name for the new routing list and press Enter.

    Select the fallback IMS data store.

    IMS Connect Extensions OTMA routing list

    Press the Exit function key (F3) to exit.

    IMS Connect Extensions OTMA Routing Lists Panel

  3. Create the OTMA routing rule

    It’s time to create the OTMA routing rule that will route messages to your fallback IMS data store. We will use the lists and data store definitions we created in previous steps. To do this, return to the Definitions panel once again and select option 9 OTMA Routing Rules.

    Type NEW followed by a name for the new routing rule and press Enter.

    To select the IMS Connect system associated with this rule, select 1 System and then place the cursor on the System field and press the Prompt function key (F4).

    Type S to select the IMS Connect system and then press Enter.

    The Original Datastore field allows you to control when this OTMA routing rule is triggered. Specifying * in this field will force all incoming workload to be processed by this routing rule. You can, if you like, further isolate the rule to match on specific IMS data stores. For more information, see Principles of OTMA rules-based routing in the IMS Connect Extensions User’s Guide.

    In the Target column, enter the name of the primary target OTMA routing list for Send-Receive Transactions, Send-Only requests, and Resume TPIPE requests. If you like, you can use the prompt key (F4) to select it from a list.

    Type Y to activate each of these message types. At this stage, we have implemented a form of “pass through” routing which simply passes OTMA workload to the IMS data store contained within the OTMA routing list.¬†

    Now we will add the fallback. In the Fallback column, enter the name of the fallback OTMA routing list for each of the message types.

    IMS Connect Extensions OTMA Routing Rule Panel

    Press the Exit function key (F3) to exit.

  4. Enable IMS Connect Extensions routing and activate the routing rule

    You now have all the definitions in place. All that remains is to perform a series of enabling steps. First we will activate the OTMA routing rules feature in IMS Connect (Note: You only need to do this once per IMS Connect system). To do this, return to the Definitions panel once again and select option 1 System Definitions.

    Type S to select the IMS Connect system and then press Enter.

    If you have not already done so, enter a slash (/) next to Activate IMS Connect Extensions.

    To activate OTMA rules-based routing, select Activate Advanced Features and Activate OTMA rules.

    IMS Connect Extensions Activating OTMA Routing

    Press the Exit function key (F3) to save the definition and exit.

    Now we need to refresh the running IMS Connect system with our new and updated definitions. To do this, return to the primary menu and select option 2 Operations.

    Type CX next to the IMS Connect system.

    Select option 2 Refresh.

    We will use this panel to apply the changes we have made to the IMS Connect system definition, and to load our new OTMA routing rule.

    IMS Connect Extensions Refreshing Definitions

    First we will update the IMS Connect definitions. Select option 1 System Definition.

    Type a slash (/) next to the command displayed on the Command Processor panel and then press Enter to submit it.

    IMS Connect Extensions Command Processor

    A response code of 0000 indicates that the update was successful. The IMS Connect Extensions routing feature is now active in IMS Connect, but the rule itself is not yet active.

    Press the Exit function key (F3) to return to the Refresh Commands panel.

    Select option 7 OTMA Routing Rules.

    Type a slash (/) next to the command displayed on the Command Processor panel and then press Enter to submit it.

    A response code of 0000 indicates that the update was successful.

    At this point in time, your OTMA routing rule is now active in IMS Connect. Use the message log to review.  Type LOG and then press Enter.

    You can see the active rules in the log. The message types you selected are listed together with the target and fallback OTMA routing lists you have selected.

    The IMS data stores that can be found in each list are reported below.

    IMS Connect Extensions Log Routing Rules

    Your fallback routing system is complete. Now we should test it.

  5. Test the fallback routing system

    Watch it on the IBM Z YouTube channel

    Watch the IBM Z channel video “Routing OTMA workload to a fallback IMS with IMS Connect” to see us test the fallback routing system on a live system…

    Operations Console for z/OS Explorer

    To test the fallback, we are going to use the IMS Connect Extensions Operation Console for z/OS Explorer. You can download the Operations Console from the downloads page on the IBM Explorer for z/OS website.

    Once you have set up and started the Operations Console, double-click on the IMS Connect system in the Navigation window.

    Select the Datastores tab. The primary target and fallback IMS data stores are listed. Workload is being directed to the primary.

    Right click on the primary data store and select Route Drain. This will suspend routing to the data store. Once the Waiting Reply count falls to zero, it has finished processing any outstanding requests and is now idle. At this point you could perform any maintenance you wish without affecting services. Note that the fallback is now accepting requests.

    IMS Connect Extensions Operations Console Datastore Tab

    To return to normal operation, right click once again on the primary IMS data store and then select Route Resume. The primary will now resume processing requests and the Waiting Reply count on the fallback IMS data store will eventually fall to zero.

    IBM IMS Performance Analyzer for z/OS

    If you use IBM IMS Performance Analyzer for z/OS, you can generate a report that displays the results of OTMA workload routing performed by IMS Connect Extensions OTMA rules-based routing.

    IMS Performance Analyzer IMS Connect OTMA workload routing summary report

    To do this, create a summary report form that contains the ORIGDS (Original IMS data store referenced in the IRM_IMSDestID field of the IRM), TARGDS (Target IMS data store that actually processed the request) and TRANCNT (transaction count) form fields.

    Not sure how to create a form?

    Take a look at the IBM developer recipe Report IMS transaction performance using forms in IBM IMS Performance Analyzer for z/OS for a step by step sequence.

    IMS Performance Analyzer IMS Connect OTMA workload routing summary report form

    IMS Connect Extensions feed and Splunk

    If you are using the IMS Connect transaction analysis app for Splunk, the Transaction rate chart on the Overview dashboard¬†shows the transaction rate for each IMS data store and demonstrates how the workload was picked up by the fallback when the primary was suspended using the “drain” command.

    IMS Connect Transaction Analysis Splunk App Fallback Datastore

    You can also use the Workload Mapping dashboard to see how your workload was handled during the fallback period. The sankey diagram on the left side of the dashboard shows you the relative distribution of workload between the two data stores over the selected time period.

    Set up the IMS Connect Extensions feed to Splunk

    To see these charts, you will need to set up the IMS Connect Extensions feed for Splunk. For more information, see the IBM developer article Forwarding a live feed of IMS Connect events to Splunk. You can also try the Splunk app without a mainframe using the pre-loaded sample data supplied in our custom Docker image. For instructions on how to download and run the Docker container on your PC, click here.

Join The Discussion