Install the IMS module
With the IMS module, you can get observability for your IMS transactions and programs including IBM MQ and database calls.
Observability for | Including |
---|---|
Transactions
| Transactions initiated using
|
Database calls | Database calls with their SQL statements from IMS to Db2 and IMS DB via
|
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.
You must re-execute the injection job after each IMS restart. For more details, see the Injection notes.
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:
//S1 EXEC PGM=ZDTIINST,PARM='<IMS_Id>,<zDC_Id>'
//STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTAUTH
Sample JCL with keyword parameters:
//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:
// ... 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.
Symbol | Position | Keyword | Description | Required |
---|---|---|---|---|
| 1 | IMSID= | The four-character IMSID of the control region. This parameter is not needed when you're using the garbage collection function to reclaim ECSA storage that contains no longer used IMS modules. | required |
| 2 | ZDC= | The four-character zDCID used in the SUBSYSTEM_ID() parameter of the target zDC. This parameter is not needed when the requested target zDC is the DEFAULT zDC. In that case type in the asterisk ( | required |
| 3 | ACTION= | SIZE= | The one-character action code or the value for Action codeAction codes specify an action to be taken on the previously injected IMS module. An action code is not applicable to the initial injection of the IMS module and is mutually exclusive with the If a valid action code is specified, the injection program doesn't re-inject the IMS module and performs the specified action on the already injected module. This means that no new versions of the IMS modules will be loaded. Action codes are:
Table size valueThe The table size value can be expressed as SEGM=nnnn, where nnnn is up to a 4 digit number of 1-megabyte segments The actual number of usable entries may be higher, as the storage is allocated above the specified quota. The number of entries will be adjusted upwards to use all available allocated storage. If the parameter is omitted upon initial IMS module injection, a default of four segments (4 MB) is used. This provides space for 8,191 entries (approximately 2,048 entries per segment). The number of allocated entries should correspond to the expected number of IMS distributed traces during any one-minute interval. When the number of traced IMS transactions exceeds the number of available table slots, new distributed traces are not recorded. No third parameter specifiedIf no third parameter is set, the injection program injects the IMS module. You can also use this option to update the IMS module. In that case existing table size will remain intact. | optional |
| 4 | ZDCWAIT= | The wait time for the target zDC to initialize, in minutes (max two digits). The default value is 30 minutes. The target zDC must have been initialized at least once since the last system IPL before the IMS module can complete initialization. | optional |
| 5 | DUMP= | Indicates whether the IMS module should capture an SVC dump when ABEND recovery is driven. This parameter can be specified during initial injection of the IMS module or in conjunction with the The default value is | optional |
| 6 | SEGM= | The value that resizes This parameter is only applicable in conjunction with the | optional |
| 7 | PATHIMS= | The value (up to 4 characters) that specifies the IMSID for which the pathid table is to be resized. This parameter is only applicable in conjunction with the If an IMSID is specified, only the pathid table for that IMS is resized. | optional |
Fast Path transaction tracing
Symbol | Position | Keyword | Description | Required |
---|---|---|---|---|
n/a | n/a | FPATH= | Indicates whether to activate Fast Path transaction tracing:
Valid only as a SYSIN parameter and only for IMS Version 15 or later. If omitted or specified incorrectly, no action is taken. | optional |
n/a | n/a | FPATHSIZE= | The size of the Fast Path SMO (Shared Memory Object) for Fast Path transaction tracing, in 1 MB segments. The range is This value can be used on the initial injection of the IMS module, or in conjunction with a modify action statement ( Valid only as a SYSIN parameter and only for IMS Version 15 or later. | optional |
BMP transaction tracing
IMS module version 1.259+
Symbol | Position | Keyword | Description | Required |
---|---|---|---|---|
n/a | n/a | BMP= | Indicates whether to activate transaction tracing for BMP regions:
Valid only as a SYSIN parameter. If omitted or specified incorrectly, BMP transaction tracing will be disabled. | optional |
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:
//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:
-
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
<- changeDSN
to whereREXX
execZDTZLOGR
resides (see step 3)
//SZDTAUTH DD DISP=SHR,DSN=<hlq>.SZDTAUTH
<- changeDSN
to where programZDTZLOGS
resides -
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)
<- changeDSN
to where theZDTZLOGC
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
-
Update the injection job to point to the new
<hlq>.SZDTAUTH
. If you have defined an alias, redefine the alias. For example:DELETE 'DT.DYNTRC.SZDTAUTH' NOSCRATCH DEFINE ALIAS(NAME('DT.DYNTRC.SZDTAUTH') RELATE('DT.R12710.SZDTAUTH'))
-
Run the injection job without the action code to pick up the updated IMS module. For more details, see the Injection notes.