Install the IMS module

With the IMS module, you can get observability for your IMS transactions and programs including IBM MQ and database calls.

Installation

The IMS module captures data on various IMS transaction processing events and forwards monitoring data to the zDC subsystem via shared buffers.

You need to install the IMS module into the control region of each IMS system that you want to monitor. This is enough to cover all message processing regions associated with the control region.

You need to add the Dynatrace exit to each IMS Connect that you want to monitor.

You need to add the z/OS Java module to each IMS SOAP Gateway you want to monitor.

IMS Connect

Add the authorized Dynatrace dataset <hlq>.SZDTAUTH to the IMS Connect job STEPLIB to permit IMS Connect to load the Dynatrace exit HWSTECL0.

• If you use IMS Connect Extensions, concatenate SZDTAUTH after the IMS Connect Extensions library.
• If you use a locally developed HWSTECL0 exit, concatenate SZDTAUTH ahead of the dataset that contains the local exit.

The IMS Connect exit is required to support the IMS Connect API protocol and to support the IMS SOAP Gateway in cases when the SOAP Gateway has not been configured to insert a tracking ID using the iogmgmt tracking command.

IMS Control region

To install the IMS module into the control region, authorize <hlq>.SZDTAUTH by adding it to the APF list and then run the ZDTINST job from the <hlq>.SZDTSAMP PDS.

Detail information on the parameters can also be found in the ZDTINST PDS member.

Sample JCL with positional parameters:

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST,PARM='<IMS_Id>,<zDC_Id>'
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH

Sample JCL with keyword parameters:

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=<IMS_Id>
ZDC=<zDC_Id>

The injection utility (ZDTIINST) supports changing the size of pathid tables without requiring an IMS restart and re-injection of the module. A path table size can be changed by using the M action code with a path table segment specification as the sixth parameter and, optionally, the target IMSID as the seventh parameter.

Below is the complete list and description of the positional parameters of the injection utility. All parameters must be upper case:

plaintextcopydownload
// ...    PARM='<IMS_Id>,<zDC_Id>,<ActionCode>|<PathTableSize>,
                <WaitZdcMin>,<Y|N>,<PathTableSegm>,<PathTableIms>'

The injection utility parameters can be specified as either positional or keyword parameters. There are seven positional parameters. Keyword parameters must be specified in a SYSIN file. The positional parameters on the EXEC JCL statement are still valid, however any new parameters added in the future will only be added as SYSIN keyword values. If an EXEC PARM parameter value is found, no SYSIN parameters will be considered. The recommended method is to use a SYSIN file and keyword parameters.

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST,PARM='IB01,ZDC1,,20'
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IB01
ZDC=ZDC1
ZDCWAIT=20

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST,PARM='IMSB,ZDC1,D'
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSB
ZDC=ZDC1
ACTION=D

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST,PARM='IMSB,ZDC1,E'
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSB
ZDC=ZDC1
ACTION=E

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST,PARM='IMSA,ZDC1,,,Y'
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
DUMP=Y

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST,PARM='IMSA,ZDC1,M,,N'
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
ACTION=M
DUMP=N

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST,PARM='IMSA,ZDC1,M,,,SEGM=3'
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
ACTION=M
SEGM=3

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST,PARM='IMSA,ZDC1,M,,,SEGM=1,IMSB'
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
ACTION=M
SEGM=1
PATHIMS=IMSB

Fast Path transaction tracing

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
FPATH=Y

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
FPATH=N

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
FPATH=Y
FPATHSIZE=8

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
ACTION=M
FPATHSIZE=2

BMP transaction tracing

IMS module version 1.259+

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
BMP=Y

plaintextcopydownload
//S1       EXEC PGM=ZDTIINST
//STEPLIB  DD DISP=SHR,DSN=<hlq>.SZDTAUTH
//SYSIN DD *
IMSID=IMSA
ZDC=ZDC1
BMP=N

Garbage collection notes

When updating the IMS module you can reclaim ECSA storage used by the old version of the IMS module.

After the injection job for the updated IMS module is run, IMS Message Region activity is necessary to update internal control blocks to point to the new version of the IMS module. After that, you can re-run the injection job with the G action code set in parameter number 3. This marks the old version of the IMS module as a candidate for deletion.

After at least 3 hours, run the injection job with the G action code set in parameter number 3 once again. This releases the ECSA storage containing the old version of the IMS module.

You can run the injection job with the G action code set in parameter number 3 repeatedly; there is no negative side effect to doing so. But in order to have the garbage collection process reclaim unused module storage, the process must be invoked at least twice after an IPL, with at least 3 hours between the first and second invocation.

Injection notes

Start the zDC at least once after the system IPL before executing the IMS module injection job.

If the target zDC has not been up since the last IPL, the injection job waits for it to come up. The wait time defaults to 30 minutes but can be set by the <WaitZdcMin> parameter. If the zDC is still not up after this time then injection cannot proceed and the injection job terminates with user ABEND code of 100.

If the zDC has been up at least once since the last system IPL, the injection job can complete even when the zDC is not currently up. In this case warning messages are issued indicating that the zDC is not started and data collection is not available, and the injection job completes with RC=4.

Start and fully initialize the IMS system before you execute the IMS module injection job. If you stop and start the IMS system, the injection job must be re-run. If you start a new IMS-dependent region or stop and restart one, no action is required.

When the IMS module is updated in a previously injected IMS, re-execute the IMS module injection job to pick up the updated IMS module load modules. Do not specify an action code for the injection job in parameter number 3. The IMS does not require a restart after the IMS module update.

We recommend that you use an automation facility like IMS Time-Controlled Operations (TCO) to execute the IMS module injection job.

All IMS module injection messages are written to the job log. You can control the level of messages by including specific DDNAMEs in the injection job JCL. If no DDNAMEs are included, the default is level 4 for informational messages. The specific DDNAMEs and message levels are the following:

• //DTMSGLV0 DD SYSOUT=* For finest level 0 DEBUG messages and above
• //DTMSGLV2 DD SYSOUT=* For fine level 2 DEBUG messages and above
• //DTMSGLV4 DD SYSOUT=* For informational level 4 messages and above
• //DTMSGLV5 DD SYSOUT=* For warning level 5 messages and above

Injection job failures typically result in a user ABEND code of 100. In most cases, the cause of failure can be determined by prior diagnostic messages that have been written to the job log.

Depending on your z/OS system parameters, a symptom dump may also be written to the job log, but a dump is not captured unless one of the following DDNAMEs is included in the injection job JCL:

plaintextcopydownload
//SYSABEND DD SYSOUT=*
//SYSMDUMP DD DSN=DT.IMSAGENT.INJECT.SDUMP,DISP=(OLD,KEEP,KEEP)

Both sample JCL members ZDTINST (injection utility) and ZDTIDIAG (diagnostic utility) contain a final step to execute procedure ZDTZLOGC. The function of the ZDTZLOGC step is to copy the job's spool output to an HFS log file so that it will automatically be included in a support archive. There is a new JCL procedure (ZDTZLOGC), REXX program (ZDTZLOGR), and assembler program (ZDTZLOGS) included for this function. To implement it do the following:

1. Copy sample JCL member ZDTZLOGC to a PDS to contain the modified JCL. Within the JCL PROC the DSN for the DD names SYSEXEC and SZDTAUTH must be changed.
   //SYSEXEC DD DISP=SHR,DSN=<hlq>.SZDTSAMP <- change DSN to where REXX exec ZDTZLOGR resides (see step 3)
   //SZDTAUTH DD DISP=SHR,DSN=<hlq>.SZDTAUTH <- change DSN to where program ZDTZLOGS resides

2. Both sample members ZDTINST and ZDTIDIAG contain a JCLLIB statement that must be changed and the ZDTZLOGC proc step must have the <ZDC Id> supplied.
   JCLLIB ORDER=(<hlq>.SZDTSAMP) <- change DSN to where the ZDTZLOGC JCL proc resides (see step 1)
   //ZDTZLOGC EXEC ZDTZLOGC,ZDC='<ZDC Id>',COND=(EVEN) <- change ZDC Id (for example, MEPC or * for default zDC)

Logging

There are two sets of IMS module logs.

• The first set of IMS messages comes from the IMS injection job. These are messages that occur during injection of the module into the IMS control region. These messages only appear in the job spool of the IMS module injection job.
• The second set of IMS messages comes from the IMS module as it monitors IMS activity. These messages are sent to the zDC and then are routed to the zRemote.

You can access the IMS module logs via the zRemote logs.

Update without region restart

To update your IMS module to a newer version without restarting the region

1. Download z/OS product datasets and extract them.

2. Update the injection job to point to the new <hlq>.SZDTAUTH. If you have defined an alias, redefine the alias. For example:

   plaintextcopydownload
   DELETE 'DT.DYNTRC.SZDTAUTH' NOSCRATCH
   DEFINE ALIAS(NAME('DT.DYNTRC.SZDTAUTH') RELATE('DT.R12710.SZDTAUTH'))

3. Run the injection job without the action code to pick up the updated IMS module. For more details, see the Injection notes.

Troubleshooting

plaintextcopydownload
ZDTI032W Recovery routine entered.
ZDTI036W ZDTIII15 0000000 20221103 10.51 VER 1.255.0 ABEND at offset 007874.
ZDTI033W Successful ABEND recovery, agent disabled.

plaintextcopydownload
severe  [native] IMS14CR1[asid = 108] is trying to initialize with an invalid protocol version number : x.xxx.xx