Sample customization of the IMS Transaction Isolation Facility

Here is an example of the customization of IMS Transaction Isolation Facility at a typical client location. In this example, the system has the following features:

The IMS sub system name is IMSA.
The IMS product high-level qualifier is PROD.IMSV14.
Dynamic Resource Definition (DRD) is active.
The maximum number of transactions, which is defined by the MAXCLAS parameter of the IMSCTRL system definition macro, is 200.
Dependent regions currently defined in the system serve classes in the range 21 - 100.
The IBM® z/OS® Debugger data sets are installed under the high-level qualifier ZDEBUG.

The IMS administrator decides that 10 region classes are reserved for IMS Isolation users, which means that 10 users can debug in private message regions simultaneously.

As the class range 21 - 100 is used for normal development and test activity, the IMS Isolation classes must be in the range 1 - 20 and 101 - 200. The IMS administrator chooses classes 131-140 to reserve for IMS Isolation users.

Next, the IMS administrator performs the following steps to prepare the IMS control region to run with IMS Isolation:

Edit the ZDEBUG.SEQASAMP(EQAWTIVS) member and SUBMIT it to create the VSAM data set PROD.ZDEBUG.EQATITBL.


//EQAWTIVS JOB
//*********************************************************************
//*        DELETE THE EXISTING FILE                                   *
//*********************************************************************
//DELETE    EXEC PGM=IDCAMS,REGION=1M
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
 DELETE PROD.ZDEBUG.EQATITBL
 SET MAXCC=0
/*
//*********************************************************************
//*        DEFINE A NEW VSAM DEBUGGING PROFILE DATASET                *
//*********************************************************************
//DEFINE    EXEC PGM=IDCAMS,REGION=1M
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
/*                         */
/* DEFINE IMS ISOLATION    */
/* TABLE INDEX AND PATH    */
/* DATA SETS               */
/*                         */
   DEFINE CLUSTER (RECORDS(999) -
    NAME (PROD.ZDEBUG.EQATITBL) -
    SHAREOPTIONS(2 3) -
    LOG(NONE) -
    INDEXED)         -
   DATA -
    (RECSZ(200,200) -
    NAME (PROD.ZDEBUG.EQATITBL.DATA) -
    KEYS(11 0) -
    FREESPACE(10 10) -
    BUFFERSPACE (20000)) -
  INDEX -
    (NAME(PROD.ZDEBUG.EQATITBL.INDX))
/*

Edit the ZDEBUG.SEQASAMP(EQAWTIMS) member and submit it to link-edit the IMS Isolation exits by using the current level of IMS. The exits are placed in PROD.ZDEBUG.IMSISO.LOADLIB.


//EQAWTIMS JOB
// SET DTHLQ=ZDEBUG
// SET IMSHLQ=PROD.IMSV14
//*********************************************************************
//* Link-edit the EQATIEDT user exit (transaction message edit)       *
//*********************************************************************
//LINK1  EXEC  PGM=IEWL,COND=(4,LE),REGION=17M,
// PARM=('OPTIONS=OPTIONS')
//SYSUT1   DD UNIT=SYSVIO,SPACE=(TRK,(10,80))
//SYSPRINT DD SYSOUT=*
//SYSLMOD  DD DSN=PROD.ZDEBUG.IMSISO.LOADLIB,DISP=SHR
//SYSLIB   DD DSN=&DTHLQ..SEQAMOD,DISP=SHR 
//         DD DSN=&IMSHLQ..SDFSRESL,DISP=SHR 
//OPTIONS  DD * 
 LIST,XREF,LET,MAP 
//SYSLIN   DD *
  MODE AMODE(31),RMODE(ANY)
  INCLUDE  SYSLIB(DFSCSI00) 
  REPLACE  DFSCSII0
  INCLUDE  SYSLIB(EQATIEDT) 
  ENTRY    EQATIEDT 
  NAME     EQATIEDT(R) 
/* 
//********************************************************************* 
//* Link-edit the DFSMSCE0 user exit (transaction routing)            * 
//********************************************************************* 
//LINK2  EXEC  PGM=IEWL,COND=(4,LE),REGION=17M, 
// PARM=('OPTIONS=OPTIONS') 
//SYSUT1   DD  UNIT=SYSVIO,SPACE=(TRK,(10,80)) 
//SYSPRINT DD  SYSOUT=* 
//SYSLMOD  DD DSN=PROD.ZDEBUG.IMSISO.LOADLIB,DISP=SHR 
//SYSLIB   DD DSN=&DTHLQ..SEQAMOD,DISP=SHR 
//         DD DSN=&IMSHLQ..SDFSRESL,DISP=SHR 
//OPTIONS  DD  *
 LIST,XREF,LET,MAP 
//SYSLIN   DD  *
  MODE AMODE(31),RMODE(ANY)
  INCLUDE  SYSLIB(DFSCSI00)
  REPLACE  DFSCSIF0
  INCLUDE  SYSLIB(EQATIEXT)
  ENTRY    EQATIEXT 
  ALIAS    DFSMSCE0 
  NAME     EQATIEXT(R) 
/*

Edit the ZDEBUG.SEQASAMP(EQAOPTS) member and submit it to create the EQAOPTS load module:

Use Delay Debug in the private IMS message processing regions, with the naming pattern 'USR.userid.DLAYDBG.EQAUOPTS'.
Limit each IMS Isolation user to registering for four transactions.


//EQAOPTS JOB 5724-T07,MSGLEVEL=(1,1),MSGCLASS=A
//*PROC JCLLIB ORDER=(ASM.SASMSAM1)
// SET GPFMLIB=ZDEBUG.SEQASAMP
// SET GPFLMOD=PROD.ZDEBUG.IMSISO.LOADLIB
//*
//ASMGL EXEC ASMACL,REGION=6M,PARM.L='MAP,LET,LIST,XREF,RENT'
//C.SYSLIB  DD DSN=&GPFMLIB.,DISP=SHR 
//          DD DSN=SYS1.MACLIB,DISP=SHR 
//C.SYSIN   DD * 
EQAOPTS  CSECT , 
EQAOPTS  AMODE 31 
EQAOPTS  RMODE ANY 
         EQAXOPT DLAYDBGDSN,'USR.&&USERID.DLAYDBG.EQAUOPTS'   a 
         EQAXOPT MAXTRANUSER,4                                c  
         EQAXOPT END 
         END , 
//L.SYSLMOD DD DISP=SHR,DSN=&GPFLMOD.
//L.SYSIN DD *
   NAME EQAOPTS(R)
/*

Place the new data sets in the IMS control region JCL. The following customizations are required:
1. APF-authorize the customized IMS exit and EQAOPTS load library (PROD.ZDEBUG.IMSISO.LOADLIB).
2. Add the EQAOPTS load library to the STEPLIB concatenation. Ensure that the library is in the search path before the ZDEBUG.SEQAMOD data set.
3. Add a new DD card called EQATIVSM for the VSAM data set created in Step 1 (PROD.ZDEBUG.EQATITBL).
```
//IMSACTAM PROC SOUT=A,DPTY='(14,15)',RGN=0M
//IEFPROC EXEC PGM=DFSMVRC0,DPRTY=&DPTY,REGION=&RGN,
// PARM='&CTL,&RGSUF,&PARM1,&PARM2'
...
//STEPLIB  DD DISP=SHR,DSN=PROD.ZDEBUG.IMSISO.LOADLIB   b 
//         DD DISP=SHR,DSN=PROD.ZDEBUG.SEQAMOD
//         DD DISP=SHR,DSN=PROD.IMS.LOADLIB
...
//EQATIVSM DD DISP=SHR,DSN=PROD.ZDEBUG.EQATITBL         c 
...
```
As the client uses the DFSMSCE0 IMS exit in the development and test environment, one other customization is required to ensure that DFSMSCE0 of IBMz/OS Debugger takes the processing of the client exit into account. The client's DFSMSCE0 is in PROD.IMSEXIT.LOADLIB.
1. Ensure that PROD.IMSEXIT.LOADLIB does not appear in STEPLIB or JOBLIB or that it appears in the search path after the data set containing IBM z/OS Debugger's DFSMSCE0 exit, for example, PROD.ZDEBUG.IMSISO.LOADLIB.
2. Add a new DD card called EQAIMEXT to identify the client DFSMSCE0 exit to IBM z/OS Debugger.
```
//IMSACTAM PROC SOUT=A,DPTY='(14,15)',RGN=0M
//IEFPROC  EXEC PGM=DFSMVRC0,DPRTY=&DPTY,REGION=&RGN,
// PARM='&CTL,&RGSUF,&PARM1,&PARM2'
...
//EQATIVSM DD DISP=SHR,DSN=PROD.ZDEBUG.EQATITBL
//EQAIMEXT DD DISP=SHR,DSN=PROD.IMSEXIT.LOADLIB         b 
//*
```
Start the IMS control region by using the normal process.

A RACF® administrator uses the following commands to create a new facility for administering IMS Isolation, and gives the IMS administrator, whose ID is ADMINA, READ access:


RDEFINE FACILITY EQADTOOL.IMSTRANISOADMIN UACC(NONE)
PERMIT EQADTOOL.IMSTRANISOADMIN CLASS(FACILITY) ID(ADMINA) ACC(READ)
SETROPTS RACLIST(FACILITY) REFRESH

Then, the RACF administrator uses the following commands to authorize the EQANBSWT Batch Messaging Program (BMP) to execute the ASSIGN, DISPLAY, START, and STOP IMS commands:


ADDUSER EQANBSWT NOPASSWORD DFLTGRP(SYS1)
PERMIT ASS CLASS(CIMS) ID(EQANBSWT) ACC(UPDATE)
PERMIT DIS CLASS(CIMS) ID(EQANBSWT) ACC(UPDATE)
PERMIT STA CLASS(CIMS) ID(EQANBSWT) ACC(UPDATE)
PERMIT STO CLASS(CIMS) ID(EQANBSWT) ACC(UPDATE)
SETROPTS RACLIST(CIMS) REFRESH

When the control region is started, the IMS administrator needs to access ISPF panel EQAPMPDF by using z/OS Debugger Utilities option 4.6. On this panel, the IMS administrator selects the classes to be reserved for debugging, 131 - 140:


+--------------------------------------------------------------------------------+
| IMS debugging preferences                                Row 126 to 150 of 200 |
| Command ===>                                   Scroll ===> PAGE                |
|                                                                                |
| IMS system . . . . . . IMSA                                                    |
|                                                                                |
|  Place a / next to the message classes that you would like to                  |
|  reserve for the isolation of debug users in your IMS system.                  |
|                                                                                |
|  Data set name for stage-1 resource definitions:                               |
|  ________________________________________________________                      |
|  Data set name for type-2 commands:                                            |
|  ________________________________________________________                      |
|  Data set name for the IMS RESLIB:                                             |
|  ________________________________________________________                      |
|                                                                                |
| Sel Class number                                                               |
|  _  126                                                                        |
|  _  127                                                                        |
|  _  128                                                                        |
|  _  129                                                                        |
|  _  130                                                                        |
|  /  131                                                                        |
|  /  132                                                                        |
|  /  133                                                                        |
|  /  134                                                                        |
|  /  135                                                                        |
|  /  136                                                                        |
|  /  137                                                                        |
|  /  138                                                                        |
|  /  139                                                                        |
|  /  140                                                                        |
|  _  141                                                                        |
|  _  142                                                                        |
|  _  143                                                                        |
|  _  144                                                                        |
|  _  145                                                                        |
|  _  146                                                                        |
|  _  147                                                                        |
|  _  148                                                                        |
|  _  149                                                                        |
|  _  150                                                                        |
|                                                                                |
|  F1=Help    F3=Exit    F4=IMSIDLst   F7=Backward   F8=Forward   F12=Cancel     |
+--------------------------------------------------------------------------------+

After selecting the classes for debug, the IMS administrator customizes ZDEBUG.SEQASAMP(EQAWICRT) and uses it to generate a data set that contains type-2 commands. These commands can be used to define resources for IMS Isolation.


//EQAWICRT JOB
//*
// SET DTHLQ=ZDEBUG
//DELETE    EXEC PGM=IDCAMS,REGION=1M
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
 DELETE ADMINA.IMSISO.TYPE2
 SET MAXCC=0
/*
//CREATE EXEC PGM=EQANICRT,REGION=0M,
// PARM=('READMASK IMSA')
//EQATY2DS DD DSN=ADMINA.IMSISO.TYPE2,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(TRK,(20,20,0),RLSE),
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
//EQATISPT DD SYSOUT=*

Define the following IMS batch message program:

APPLCTN GPSB=EQANBSWT,LANG=ASSEM,PGMTYPE=(BATCH),               X
        SCHDTYP=PARALLEL
TRANSACT CODE=(EQANBSWT),AOI=TRAN,                              X
        MSGTYPE=(SNGLSEG,NONRESPONSE)

The IMS administrator creates a JCL deck to run the batch IMS SPOC utility (CSLUSPOC) to create the resources needed by IMS Isolation.


//SPOCBCH  JOB
//BATCH    EXEC PGM=CSLUSPOC,PARM='IMSPLEX=PLEX2,F=BYCOL'
//STEPLIB  DD DSN=PROD.IMSV14.SDFSRESL,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD DSN=ADMINA.IMSISO.TYPE2,DISP=SHR

The IMS administrator then makes the following ISPF customizations:

The client keeps all PROCs that are used to create dependent IMS regions in a PROCEDURE library named PROD.IMSV14.PROCLIB. To allow the IMS Isolation Facility to access this library to generate private message regions, the IMS administrator updates ZDEBUG.SEQATLIB(EQAZPROC) to add PROD.IMSV14.PROCLIB:
```
PROD.IMSV14.PROCLIB
SYS1.PROCLIB
```

The MVS system where IMSA executes has certain rules for jobs submitted to JES. To ensure that private message regions started by IMS Isolation conform to these rules, the IMS administrator updates PROD.ZDEBUG(EQAZDFLT) to specify overrides for various JOB parameters:


File  Edit  Edit_Settings  Menu  Utilities Compilers  Test Help
------------------------------------------------------------------------------
EDIT                         PROD.ZDEBUG(EQAZDFLT)      - 01.06    Columns 000
Command ===>                                                          Scroll =
000205 !us5adspc = ;                          ! Override for JOB parm ADDRSPC
000206 !us5bytes = ;                          ! Override for JOB parm BYTES
000207 !us5cards = ;                          ! Override for JOB parm CARDS
000208 !us5ccsid = ;                          ! Override for JOB parm CCSID
000209 !us5class = ;                          ! Override for JOB parm CLASS
000210 !us5cond = ;                           ! Override for JOB parm COND
000211 !us5group = ;                          ! Override for JOB parm GROUP
000212 !us5jeslg = ;                          ! Override for JOB parm JESLOG
000213 !us5lines = ;                          ! Override for JOB parm LINES
000214 !us5melim = ;                          ! Override for JOB parm MEMLIMIT
000215 us5msgcl = A ;                         ! Override for JOB parm MSGCLASS
000216 !us5msglv = ;                          ! Override for JOB parm MSGLEVEL
000217 us5notfy = &SYSUID. ;                  ! Override for JOB parm NOTIFY 
000218 !us5pages = ;                          ! Override for JOB parm PAGES 
000219 !us5paswd = ;                          ! Override for JOB parm PASSWORD 
000220 !us5perf = ;                           ! Override for JOB parm PERFORM 
000221 !us5prty = ;                           ! Override for JOB parm PRTY 
000222 !us5rd = ;                             ! Override for JOB parm RD 
000223 !us5regn = ;                           ! Override for JOB parm REGION 
000224 !us5rstrt = ;                          ! Override for JOB parm RESTART 
000225 !us5seclb = ;                          ! Override for JOB parm SECLABEL 
000226 !us5schen = ;                          ! Override for JOB parm SCHENV
000227 !us5sysaf = ;                          ! Override for JOB parm SYSAFF
000228 !us5systm = ;                          ! Override for JOB parm SYSTEM 
000229 us5time = 1440 ;                       ! Override for JOB parm TIME 
000230 !us5typrn = ;                          ! Override for JOB parm TYPRUN 
000231 !us5user = ;                           ! Override for JOB parm USER 
000232 
000233 
**********************************************************************