Scenario F: Enabling the Transaction Isolation Facility

Note: The IMS Transaction Isolation Facility is not available in IBM Z and Cloud Modernization Stack (Wazi Code).

The IMS Transaction Isolation Facility of z/OS® Debugger allows users to register to debug transactions in any IMS subsystem that is enabled for the facility. Each user may also launch a private message-processing region in which the selected message processing programs will run. The actions in this section will guide you through the setup of this facility.

The IMS Transaction Isolation Facility requires that the following resources be created or reserved for z/OS Debugger users:
  1. A set of IMS message classes reserved for the private message-processing regions.

  2. For each reserved message class, a set of IMS program resources with the name EQATcccn, where ccc is the three-digit class number, and n is an ordinal number from 1 to the maximum number of transactions a single user can register to debug.

    Also, for each reserved message class, a set of IMS transaction resources must be defined. A set of non-conversational transactions with the names EQATcccn and a set of conversational transactions with the names EQACcccn must be defined, where ccc is the three-digit class number, and n is an ordinal number from 1 to the maximum number of transactions a single user can register to debug.

Do the following steps to enable this scenario:

  1. Customize and run the EQAWTIVS sample member. A VSAM data set is created to be used as a repository to store the IMS Transaction Isolation information when the IMS system is stopped.

  2. Customize and run the EQAWTIMS sample member to link-edit the z/OS Debugger exits into an IMS system control region load library data set. Note that this library must be a PDS, not a PDSE. z/OS Debugger implements the following exits for the IMS Transaction Isolation Facility:
    • DFSMSCE0 - TM and MSC Message Routing and Control User exit routine, as an alias of EQATIEXT
    • EQATIEDT - Transaction Code (Input) edit routine for EQA*cccn transactions

  3. Customize the EQAOPTS sample and create the EQAOPTS load module.

    The EQAOPTS sample builds a set of EQAOPTS commands into a data-only load module. For more information about the EQAOPTS commands, see EQAOPTS commands.

    The following EQAOPTS command applies to the IMS Transaction Isolation Facility:
    MAXTRANUSER
    This command specifies the maximum number of transactions that a single user can register to debug. The default value is 15.
  4. Modify the IMS system by performing the following actions:
    1. Ensure that the following load libraries are in the search path for the IMS system control region:
      • The load library with the z/OS Debugger IMS exits link-edited in step 2
      • The library that contains the EQAOPTS load module generated in step 3
    2. Add the VSAM data set created in step 1 to the IMS system control region by using DD name EQATIVSM.
    3. If your IMS system uses the DFSMSCE0 exit, the following is needed for the debugger's DFSMSCE0 exit, loaded from STEPLIB, to call your exit from DD EQAIMEXT:
      1. Remove the load library that contains your DFSMSCE0 exit from the STEPLIB or JOBLIB concatenation of the IMS control region.

        If you cannot remove the load library, ensure that the load library with the z/OS Debugger version of DFSMSCE0 appears before your DFSMSCE0 exit in the search path.

      2. Add the load library that contains your DFSMSCE0 exit to the IMS system control region by using DD name EQAIMEXT.
        Note: The EQAIMEXT DD is needed only for your site's DFSMSCE0 exit. It must not contain the debugger's DFSMSCE0.
        If your IMS system uses a facility, such as the generic MSC exit of IMS Tools, to manage multiple DFSMSCE0 exits, use that facility rather than the steps i and ii above to add debugger's DFSMSCE0 exit to your system.
    After you complete the actions, start or restart the IMS system.
  5. Define the user EQANBSWT to RACF®, and permit it READ access to the ASSIGN, DISPLAY, START, and STOP IMS commands:
    ADDUSER EQANBSWT NOPASSWORD DFLTGRP(SYS1)
PE ASS CLASS(CIMS) ID(EQANBSWT) ACC(READ)
PE DIS CLASS(CIMS) ID(EQANBSWT) ACC(READ)
PE STA CLASS(CIMS) ID(EQANBSWT) ACC(READ)
PE STO CLASS(CIMS) ID(EQANBSWT) ACC(READ)
SETROPTS RACLIST(CIMS) REFRESH
  6. Give the user ID for each IMS control region authority to modify the VSAM data set created in step 1.
  7. If your site restricts access to the following type-1 IMS commands, and you have enabled the IMS Common Service Layer (CSL), you must enable users to issue the QUERY TRAN type-2 IMS command.
    /DISPLAY PROG ALL
/DISPLAY TRAN *
    To enable this access, permit the users READ access to the IMS.CSLppppp.QRY.TRAN resource in the OPERCMDS class, where ppppp is the name of the IMSplex that the IMS subsystem registers with. For example:
    PE IMS.CSLPLEX1.QRY.TRAN CLASS(OPERCMDS) ID(RANCAM) ACC(READ)
SETROPTS RACLIST(OPERCMDS) REFRESH
  8. Enable administrative users to configure the IMS Transaction Isolation Facility. Users that are authorized for this function use IBM® z/OS Debugger Utilities option 4, suboption 6 "Administer IMS Transaction Isolation Environment", to reserve message classes for z/OS Debugger usage, and to generate other artifacts for the IMS Transaction Isolation Facility.

    To control access to the Administer IMS Transaction Isolation Environment panel, create RACF FACILITY EQADTOOL.IMSTRANISOADMIN with UACC(NONE). Permit users who might access the panel ACC(READ) to the FACILITY.

  9. Use IBM z/OS Debugger Utilities option 4, suboption 6 "Administer IMS Transaction Isolation Environment" to reserve message classes for use by the IMS Transaction Isolation Facility. Ensure that these classes are not in use for other dependent regions in your IMS system.

    When multiple versions of IMS subsystems are installed on your system, you can use suboption 6 to provide a specific RESLIB used by this IMS subsystem. If no RESLIB is specified on suboption 6, the one from us5imrsl in EQAZDFLT is used as the default.

    If you require the IMS Transaction Isolation Facility to use type-2 IMS commands to retrieve the transaction list (see step 7 above), supply the IMSplex name on the suboption 6 panel.

  10. Customize the hlq.SEQASAMP(EQAWICRT) sample job and submit the job to generate one or both of the following resource definitions:
    • Stage-1 IMS system definition macros to create the necessary IMS resources for the classes you have selected. The macros are generated to the data set with the DD name EQARESDS.
    • Type-2 IMS commands to create the necessary IMS resources for the classes you have selected. The commands are generated to the data set with the DD name EQATY2DS.
  11. Use the resource definitions from step 10 to update the IMS system definition, preferably by using the Type 2 commands to update the system dynamically, if you are using Dynamic Resource Definition (DRD). Otherwise, add the Type 1 commands to the stage 1 input to your system definition process, and regenerate the IMS system definition.
    Note: The EDIT parameter in the stage-1 input requires at least a CTLBLKS level of system definition. A MODBLKS definition cannot be used.
    Restart the IMS system, if necessary, to pick up the changes.
  12. Add any important IMS PROCLIBs to EQAZPROC in hlq.SEQATLIB. This action allows IBM z/OS Debugger Utilities to expand any IMS PROCs that are discovered when the execution environment of the selected transaction is cloned.
  13. Additional customization parameters are available in member EQAZDFLT of hlq.SEQATLIB library. To set the value for any of these parameters, remove the preceding comment character (!) and specify the value, followed by a semicolon (;).
    
!*
! Default job name for dynamic IMS MPR creation
!*
! Up to 7 characters of the user's TSO user ID will be substituted
! for the string &&user&&. 
!* 
mprdebug =                         ! Job name for debugging
     @&&user&& ;             1        ! IMS MPR 
!*
! Specify the name of the main IMS RESLIB. This will be the first 
! data set in the STEPLIB for the batch job that runs the EQANBSWT 
! BMP program. 
!* 
!us5imrsl = ;                2  
!us5dtmod = ;                3  
!us5dtce1 = ;                4 
 
!us5trnft = ;                5  
!us5trnmx = ;                6 
 
!us5adspc = ;                7         ! Override for JOB parm ADDRSPC 
!us5bytes = ;                          ! Override for JOB parm BYTES 
!us5cards = ;                          ! Override for JOB parm CARDS 
!us5ccsid = ;                          ! Override for JOB parm CCSID 
!us5class = ;                          ! Override for JOB parm CLASS 
!us5cond = ;                           ! Override for JOB parm COND 
!us5group = ;                          ! Override for JOB parm GROUP 
!us5jeslg = ;                          ! Override for JOB parm JESLOG 
!us5lines = ;                          ! Override for JOB parm LINES 
!us5melim = ;                          ! Override for JOB parm MEMLIMIT 
!us5msgcl = ;                          ! Override for JOB parm MSGCLASS 
!us5msglv = ;                          ! Override for JOB parm MSGLEVEL 
!us5notfy = ;                          ! Override for JOB parm NOTIFY 
!us5pages = ;                          ! Override for JOB parm PAGES 
!us5paswd = ;                          ! Override for JOB parm PASSWORD 
!us5perf = ;                           ! Override for JOB parm PERFORM 
!us5prty = ;                           ! Override for JOB parm PRTY 
!us5rd = ;                             ! Override for JOB parm RD 
!us5regn = ;                           ! Override for JOB parm REGION 
!us5rstrt = ;                          ! Override for JOB parm RESTART 
!us5seclb = ;                          ! Override for JOB parm SECLABEL 
!us5schen = ;                          ! Override for JOB parm SCHENV 
!us5time = ;                           ! Override for JOB parm TIME 
!us5typrn = ;                          ! Override for JOB parm TYPRUN 
!us5user = ;                           ! Override for JOB parm USER
     1  mprdebug
    Establishes the pattern that is used to create the job name for any private message regions started by users of the IMS Transaction Isolation Facility. The user's TSO ID is substituted in the string where &&user&& appears.
     2  us5imsrsl
    Identifies the IMS RESLIB to use when tasks are performed for the IMS Transaction Isolation Facility. This parameter is necessary only when the proper IMS RESLIB is not in the link list concatenation.
    This setting applies to IMS subsystems where the RESLIB is not specified with IBM z/OS Debugger Utilities option 4.6. If the client needs to use a specific RESLIB for a particular IMS subsystem, specify the RESLIB with option 4.6.
     3  us5dtmod
    Identifies the z/OS Debugger SEQAMOD library to use when tasks are performed for the IMS Transaction Isolation Facility. This parameter is necessary only when the proper z/OS Debugger SEQAMOD library is not in the link list concatenation.
     4  us5dtce1
    Identifies the z/OS MVS™ Language Environment® runtime library (CEERUN) to use when tasks are performed for the IMS Transaction Isolation Facility. This parameter is necessary only when the proper Language Environment library is not in the link list concatenation.
     5  us5trnft
    Defines the default transaction name filter when a new user accesses the EQAPMPSL panel for the first time.
     6  us5trnmx
    Defines the default maximum number of transactions that is returned to the user on the EQAPMPSL panel. A value of 0 returns the entire list of transactions, which can have a significant performance impact if your IMS system has defined many transactions.
     7  JOB parameter overrides
    Use these parameters to specify or override any parameters on the JOB statement that is created based on the JOB statement of the “cloned” message region.
For more information about how application programmers use the IMS Transaction Isolation Facility, see the section "Using IMS Transaction Isolation to create a private message-processing region and select transactions to debug" in the IBM z/OS Debugger User's Guide.