The IMS code module of OneAgent traces IMS transactions submitted from IMS MQ Bridge or MQ Trigger Monitor, IMS TM Resource Adapter, IMS SOAP Gateway, 3270 TX Transactions or IMS Connect API. It supports DB2, DL/I and MQ API calls tracing, as well as any programs invoked using LE dynamic call. You may also need to modify your IMS Connect Job JCL to allow IMS Connect to load the Dynatrace exit HWSTECL0.
You need to inject OneAgent into the Control Region of each IMS system where you want to capture PurePaths. OneAgent captures data on various IMS transaction processing events and forwards that information to the zDC.
It is only necessary to inject the OneAgent into the Control Region. This is enough to cover all message Processing Regions associated with the Control Region. The injection job must be re-executed after each IMS restart.
|IMS MQ Bridge application||
|IMS SOAP application||
|IMS TM resource adapter application||
|IMS connect API application||
|IMS MQ Trigger monitor application||
The following sections provide additional details about the instrumentation process. Detail information on the parameters can also be found in the ZDTINST PDS member.
To inject the OneAgent, authorize <hlq>.SZDTIMSA by adding it to the APF list and then run the ZDTINST job from the <hlq>.SZDTSAMP PDS.
//S1 EXEC PGM=ZDTIINST,PARM='<IMS_Id>,<zDC_Id>' //STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTIMSA
The OneAgent injection utility (ZDTIINST) supports changing the size of
pathid tables without requiring an IMS restart and re-injection of the OneAgent. 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 parameters to the injection utility. All parameters must be upper case:
// ... PARM='<IMS_Id>,<zDC_Id>,<ActionCode>|<PathTableSize>, <WaitZdcMin>,<Y|N>,<PathTableSegm>,<PathTableIms>'
There are seven positional parameters.
||1||required||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 OneAgent IMS code modules.
||2||required||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 (
||3||optional||The one-character action code or the value for
Action codeAction codes specify an action to be taken on the previously injected OneAgent. An action code is not applicable to the initial injection of the OneAgent and is mutually exclusive with the
If a valid action code is specified, the injection program doesn't re-inject OneAgent and performs the specified action on the already injected OneAgent. This means that no new versions of OneAgent IMS code 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 on the initial injection of the OneAgent, the default of 2 segments (2 megabytes) is used. It provides space for 8191 entries (approximately 4095 entries per segment).
The number of allocated entries should correspond to the expected number of IMS Purepaths during any one-minute interval. When the number of traced IMS transactions exceeds the number of available table slots, new PurePaths are not recorded.
No third parameter specifiedIf no third parameter is set, the injection program injects the OneAgent.
You can also use this option to install OneAgent service updates (PTFs). In that case existing table size will remain intact.
||4||optional||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 OneAgent can complete initialization.
||5||optional||The one-character value that indicates whether the OneAgent should capture an SVC dump when ABEND recovery is driven.
This parameter can be specified during initial injection of OneAgent or in conjunction with the
The default value is
||6||optional||The value that resizes
This parameter is only applicable in conjunction with the
||7||optional||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.
If the parameter is omitted, only the
If the asterisk (
Accept the default
PathTableSize and wait for up to 20 minutes for ZDC1 to initialize. Note that the third positional parameter was not specified.
//S1 EXEC PGM=ZDTIINST,PARM='IB01,ZDC1,,20' //STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTIMSA
//S1 EXEC PGM=ZDTIINST,PARM='IMSB,ZDC1,D' //STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTIMSA
//S1 EXEC PGM=ZDTIINST,PARM='IMSB,ZDC1,E' //STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTIMSA
Accept the defaults for Parameter#3 and Parameter#4 but specify that code module ABEND recovery should also capture an SVC dump.
//S1 EXEC PGM=ZDTIINST,PARM='IMSA,ZDC1,,,Y' //STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTIMSA
//S1 EXEC PGM=ZDTIINST,PARM='IMSA,ZDC1,M,,N' //STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTIMSA
//S1 EXEC PGM=ZDTIINST,PARM='IMSA,ZDC1,M,,,SEGM=3' //STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTIMSA
//S1 EXEC PGM=ZDTIINST,PARM='IMSA,ZDC1,M,,,SEGM=1,IMSB' //STEPLIB DD DISP=SHR,DSN=<hlq>.SZDTIMSA
Garbage collection notes
When updating OneAgent you can reclaim ECSA storage used by the old version of OneAgent.
After injection job for updated OneAgent is run, IMS Message Region activity is necessary to update internal control blocks to point to the new version OneAgent. After that you can re-run the injection job with the
G action code set in parameter number 3. This marks old version of OneAgent as 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 OneAgent.
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 elapsing between the first and second invocation.
Start the zDC at least once after the system IPL before executing the OneAgent 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
Start and fully initialize the IMS system before you execute the OneAgent 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.
The OneAgent injection job is also used to implement service updates (PTFs) to the OneAgent. To implement a service update on a previously injected (existing) OneAgent, do not specify an action code in the parameter number 3.
We recommend to use an automation facility like IMS Time-Controlled Operations (TCO) to execute the OneAgent injection job.
All OneAgent 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 (OneAgent injection utility) and ZDTIDIAG (OneAgent 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 SZDTIMSA must be changed.
//SYSEXEC DD DISP=SHR,DSN=<hlq>.SZDTSAMP<- change
ZDTZLOGRresides (see step 3)
//SZDTIMSA DD DISP=SHR,DSN=<hlq>.SZDTIMSA<- change
DSNto where program
Both sample members ZDTINST and ZDTIDIAG contain a JCLLIB statement that must be changed and the ZDTZLOGC proc step must have the
JCLLIB ORDER=(<hlq>.SZDTSAMP)<- change
DSNto where the
ZDTZLOGCJCL proc resides (see step 1)
//ZDTZLOGC EXEC ZDTZLOGC,ZDC='<ZDC Id>',COND=(EVEN)<- change ZDC Id (for example,
*for default ZDC)
Copy the supplied REXX program from sample member to the designated SYSEXEC library. No modification is required. In order for the REXX program to be able to locate and copy the job spool, there are some SDSF security and customization considerations. It is generally easier to ensure that the userID of the submitter matches the prefix of the jobname. If that is not feasible, consider granting the submitter universal SDFS read access. For SDSF and RACF considerations, see IBM documentation (for example., SA23-2274-09 z/OS SDSF Operation and Customization v2r2).
IMS Connect Job Modification
Add the authorized Dynatrace OneAgent dataset
<HLQ>.SZDTIMSA to the IMS Connect job STEPLIB to permit IMS Connect to load the Dynatrace exit HWSTECL0. If IMS Connect Extensions is in use, concatenate SZDTIMSA after the IMS Connect Extensions library, If a locally developed HWSTECL0 exit is in use, concatenate SZDTIMSA 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 where the SOAP Gateway has not been configured to insert a tracking ID using the
iogmgmt tracking command.