Free trial

Deploy OneAgent on IMS

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 DESK 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.

Note

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.

Requirements

IMS MQ Bridge application
  • OneAgent deployed on the front-end application.
  • OneAgent deployed on the target IMS system.
IMS SOAP application
  • OneAgent deployed on the front-end application.
  • OneAgent deployed on the target IMS system.
  • Either a DESK exit added to IMS Connect or the SOAP gateways configured to insert a tracking ID or both.
IMS TM resource adapter application
  • OneAgent deployed on the front-end application with a Java application server tier that uses the IMS TM Resource Adapter protocol.
  • OneAgent deployed on the target IMS system.
IMS connect API application
  • A DESK exit added to IMS Connect.
  • OneAgent deployed on the target IMS system.
IMS MQ Trigger monitor application
  • OneAgent deployed on the target IMS system.

The following sections provide additional details about the instrumentation process. Detail information on the parameters can also be found in the ZDTINST PDS member.

OneAgent injection

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.

Sample JCL:

//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.

Symbol Position Required Description
<IMS_Id> 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.
<zDC_Id> 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 (*) or omit the parameter.
<ActionCode>|<PathTableSize> 3 optional The one-character action code or the value for pathid table size.

Action code

Action 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 pathid table size value.

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:
  • E: Enable (switch on) an injected OneAgent that was previously disabled.
  • D: Disable (switch off) an injected OneAgent. The OneAgent is no longer invoked. Use the E action code to re-enable it.
  • G: Garbage collection. If an OneAgent service updates (PTFs) have been installed and injected, ECSA storage for the old (unused) load modules of the OneAgent is reclaimed with this function. See the Garbage collection notes section for more information.
  • M: Modify the recovery option of the injected OneAgent when this value is used in conjunction with the fifth parameter, <Y|N>. Alternatively, modify the size of any previously allocated path tables, when used in conjunction with the sixth parameter <PathTableSegm>, and optionally the seventh parameter <PathTableIms>.
  • F: Free all resource locks and reset the pathid table pointers. This action code should never be used unless the E action has failed because a OneAgent resource is locked or as directed by DESK support.

Table size value

The pathid tables size value is used for the initial OneAgent injection and is mutually exclusive with actions codes. If the OneAgent is already injected, the table size value is ignored.

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 specified

If 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.
<WaitZdcMin> 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.
<Y|N> 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 M or E action codes (parameter number 3) to toggle on/off the dump capture during recovery for the previously injected OneAgent.

The default value is Y, which means dump capture is enabled.
<PathTableSegm> 6 optional The value that resizes pathid tables.

This parameter is only applicable in conjunction with the M action code (parameter number 3). The format of value is SEGM=nnnn, where nnnn is the number (up to 4 digits) of 1-megabyte segments.
<PathTableIms> 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 M action code (parameter number 3) and the <PathTableSegm> value (parameter number 6).

'If an IMSID is specified, only the pathid table for that IMS is resized.
If the parameter is omitted, only the pathid table for the local IMS (specified as parameter number 1) is resized.
If the asterisk (*) is specified, the pathid table for the local IMS and pathid tables allocated locally for all remote IMSIDs are resized.

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.

Injection notes

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 RC=4.

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:

  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 SZDTIMSA must be changed.
    //SYSEXEC DD DISP=SHR,DSN=<hlq>.SZDTSAMP <- change DSN to where REXX exec ZDTZLOGR resides (see step 3)
    //SZDTIMSA DD DISP=SHR,DSN=<hlq>.SZDTIMSA <- 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)

  3. 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 DESK OneAgent dataset <HLQ>.SZDTIMSA to the IMS Connect job STEPLIB to permit IMS Connect to load the DESK 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.