Using IMS Transaction Isolation to create a private message-processing region and select transactions to debug

Note: This section is not applicable to IBM® Developer z/OS® (non-Enterprise Edition) or IBM Z and Cloud Modernization Stack (Wazi Code).

z/OS Debugger's IMS Transaction Isolation facility allows you to debug IMS message processing programs (MPPs) in an environment that is isolated from other users of the same programs. If your IMSplex uses shared queues, you can register for a transaction, start a region, or perform any other operation from a single connection and the IMS Transaction Isolation facility will notify other LPARs of the operations.

Using the IMS Transaction Isolation facility, you can do the following tasks:
  1. Display a list of transactions available for a given IMS subsystem.
  2. From that list of transactions, register to debug a specific transaction in a private message region that is created for your use.
  3. For transactions you are registered to debug, specify other pattern-matching information, such as the content of messages that are sent to the transaction. This allows you to trap the transaction under specific conditions.
  4. Start a private message-processing region based on the execution environment of a selected transaction. The private message-processing region is configured to use delay debug mode, and is hardcoded to read delay debug preferences from your delay debug profile data set. For more information about delay debug, see Using delay debug mode to delay starting of a debug session.
  5. Customize your private message region by supplying personal libraries for the STEPLIB concatenation.
To use the IMS Transaction Isolation facility, do the following tasks:
  1. Start IBM z/OS Debugger Utilities. For more information, see Starting IBM z/OS Debugger Utilities.
  2. In the IBM z/OS Debugger Utilities panel (EQA@PRIM), type 4 in the Option line and press Enter.
  3. In the Manage IMS Message Processing Programs panel (EQAPRIS), type 5 in the Option line and press Enter.
  4. The IMS Transaction Isolation Facility panel (EQAPMPSL) is displayed. The following screen highlights the fields in the panel.
    
--------------- IMS Transaction Isolation Facility ---------- Row 1 to 7 of 201
 Command ===>                                   Scroll ===> PAGE

IMS system . . . . . . IMS1  1 

 2  _ Manage additional libraries and delay debug options.
       Your region: @USRT001 Class 021 Stopped 
       Delay debug data set: 'USRT001.DLAYDBG.EQAUOPTS'

  Filters:  3 
   / Display full transaction list.
   _ Display only transactions you are registered to debug.
   _ Filter by name ==> dtmq   
__ 4 __50 Maximum number of transactions (0 - no limit)

(E) Edit  (S) Start Region  (P) Stop Region  (R) Register  (D) De-register
Sel   Transaction  PSB name  Reserved user    Region name    Status
_  5   ADDINV      DFSSAM04
_      ADDPART     DFSSAM04
_      APOL11      APOL1
_      APOL12      APOL1
_      APOL13      APOL1
_      APOL14      APOL1
 F1=Help      F3=Exit      F4=IMSIDLst  F7=Backward  F8=Forward  F12=Cancel
     1  IMS System
    Specify the IMS subsystem identifier where you debug.
    Press F4 to receive a list of IMS subsystems that are set up for IMS Transaction Isolation.
     2  Manage additional libraries and delay debug options
    Place a forward slash (/) in the entry field and press Enter to display the Manage Additional Libraries and Delay Debug panel (EQAPMPRG).
     3  Filters
    You can use these selections to change the transactions that are displayed for the selected IMS subsystem.
     4  Maximum number of transactions
    This value limits the number of transactions displayed for the given filter. If there are more transactions matching the filter than the transactions that are displayed, a message is displayed.
    Note: If you set too high of a limit or enter 0 to set no limit, the performance of this panel will be degraded considerably.
     5  Transaction action character
    The following actions can be performed for each transaction listed:
    Action Function Description
    E Edit Displays the Edit pattern-matching parameters panel (EQAPMPED).
    S Start Region Starts a private message-processing region based on the current execution environment for the selected transaction. If you do not start the region, it will also register to debug the transaction.
    P Stop Region Stops the private message-processing region that you started.
    R Register Register to debug the selected transaction. When a message for the transaction is scheduled in the IMS subsystem, the message is routed to your private message-processing region if all pattern-matching parameters are satisfied.
    D De-register Removes your registration to debug the selected transaction. Messages are no longer routed to your private message-processing region for this transaction.
  5. In the Manage Additional Libraries and Delay Debug panel (EQAPMPRG), you can perform the following tasks:
    1. Edit the delay debug options data set.
    2. Specify Language Environment® options for the private message region.
    3. Add data sets to the message region STEPLIB concatenation.

    When z/OS Debugger creates your private message-processing region, if you have a delay debug options data set allocated, the private message-processing region is in delay debug mode. This allows you to use the delay debug options data set to control the TEST option that is used and the programs that are trapped.

    If you do not have a delay debug data set allocated, z/OS Debugger creates the private message-processing region with a hardcoded CEEOPTS DD. The hardcoded CEEOPTS DD contains the string TEST (ALL, *,PROMPT,VTAM®%userid:*), where userid is your TSO user ID.

    All private message-processing regions started by IMS Isolation contain a CEEOPTS DD card. You can specify additional Language Environment options for this CEEOPTS DD by using the Other run-time options field.

    To add a data set to your private message-processing region's STEPLIB, type an I in the Cmd column of the data set table at the bottom of the panel. This adds an empty line to the table that you can complete with a data set name and a disposition.

    Each data set in the table is added to the beginning of the STEPLIB concatenation for the private message-processing region, in the order that is specified in the table. You can change the relative position of the data sets in the table by modifying the values in the Seq column.

    For more advanced manipulation of the DD card, you can type a forward slash (/) in the Cmd column for a DD card and press Enter. A menu is displayed where you can change the allocation parameters, the DCB parameters, and other characteristics that are specified on the DD card for a data set.

  6. The following screen highlights the fields on the Edit pattern-matching parameters panel (EQAPMPED).
    
---------------------- Edit pattern-matching parameters ---------------------
 Command ===> __________________________________________    Scroll ===> CSR 

 Message processing program debug settings:

 Region class  . . .  007           Region name . . @USER1 
 Transaction . . . .  IVTCV                             
 User ID to match. .  USER1  1                             
 Transaction Message  rrr  2                               
    Range start  . .  12  3                                 
    Range length . .  32  4  
   5  Match case /      6  Data is hex _











  F1=Help             F3=Exit      F4=Run      F5=Findnext     F7=Backward
  F8=Forward         F10=Submit   F12=Cancel
     1  User ID to match
    This field designates the user ID or pattern that is used to match against the user ID when a given instance of the selected transaction is run. The value may be a full user ID or a pattern that ends with the character '*'.
     2  Transaction Message
    Data that you enter in this field is used to match against all messages that are scheduled for the selected transaction. If the string you type is contained within the message, the message is considered a match, if the other pattern-matching parameters are also satisfied (see  5  and  6 ).
     3  Range start
    The first position to check. The transaction name usually can be found in position 1, which is the default start of the range.
     4  Range length
    The maximum number of bytes to scan. If the length is not given, the range ends at the end of the message segment.
     5  Match case
    Place a forward slash (/) in the entry field to indicate that the string in "Transaction Message" is considered a match if all characters match, including their case.
     6  Data is hex
    Place a forward slash (/) in the entry field to indicate that the string in "Transaction Message" is a hexadecimal string.