IMS Agent injection and configuration

The IMS Agent must be injected into the Control Region of each IMS system for which you want to capture Purepaths. It consists of programs that capture data on various IMS transaction processing events, and forwards that information to the zDC.

The IMS Agent traces IMS transactions submitted from the IMS MQ Bridge or MQ Trigger Monitor, IMS TM Resource Adapter, the IMS SOAP Gateway, and the IMS Connect API.

Note

It is only necessary to inject the IMS Agent into the Control Region. This lets it be used by all message processing regions associated with the Control Region. The job to inject the IMS Agent must be re-executed after each IMS restart.

The following are the requirements for generating a PurePath for different application types.

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

Injecting the AppMon IMS Agent

To inject the AppMon IMS Agent, authorize hlq. LZDT610.SZDTIMSA by adding it to the APF list and then run the ZDTIINST job from the <HLQ>.SZDTSAMP PDS.

Sample JCL:

//S1       EXEC PGM=ZDTIINST,PARM='<IMS_Id>,<zDC_Id>'
//STEPLIB  DD DISP=SHR,DSN=<HLQ>.SZDTIMSA

Below is the complete list and description of the parameters to the IMS Agent injection program (ZDTIINST):

// ...    PARM='<IMS_Id>,<zDC_Id>,<E|D|G|M>|<PathTableSize>,
                <WaitZdcMin>,<Y|N>'

There are five positional parameters. 

Symbol Position Required Description
<IMS_Id> 1 Y The four-character IMSID of the control region. This parameter is always required except when using the garbage collection function to reclaim ECSA storage for replaced, no longer used agent programs. For that function the IMSID parameter is not used.
<zDC_Id> 2 Y The 4 character zDCID used in the SUBSYSTEM_ID() parameter of the target zDC. This parameter is always required except when the requested target zDC is the DEFAULT zDC. In that case supply an asterisk or omit the parameter. The default zDC, if one exists, will be selected.
<E|D|G|M>|<PathTableSize> 3   A one-character function parameter. A function parameter is optional and specifies an action to be taken on a previously injected (existing) IMS Agent. A function parameter is not applicable to the initial injection of an IMS Agent, and is mutually exclusive with the other form of the third positional parameter, <PathTableSize>. If a valid action code is specified, the injection program assumes that the action is to be taken on the currently injected IMS Agent. No attempt will be made to inject the agent or to update the current agent’s load modules (implement service). Function values are:
  • E - Enable (switch on) an injected IMS Agent that was previously disabled.
  • D - Disable (switch off) an injected IMS Agent. The IMS Agent will no longer be invoked. Use the E function to re-enable it.
  • G - Garbage collection. If new IMS Agent service updates (PTFs) are installed, ECSA storage for old (unused) IMS Agent load modules is reclaimed with this function. See the section below titled Garbage Collection Function Notes for details on using this function.
  • M - Modify the recovery option of an injected IMS Agent. This value is used in conjunction with Parameter #5.
  • No third parameter - Inject the IMS Agent. This also is used to dynamically install new IMS Agent service updates (PTFs).
  • <PathTableSize> - Up to a 9 digit number that specifies the minimum number of pathid table entries to be allocated. The actual number of entries may be higher since the storage is allocated above the bar in megabytes. The number of entries will be adjusted upwards to use the amount of storage available. This parameter is optional and specifies the maximum number of ’in-flight’ IMS transactions that the IMS Agent can track at one time. The default value is 4095. This value may only be specified when injecting the IMS Agent. It is mutually exclusive with the other form of the third positional parameter, <E|D|G|M>.
<WaitZdcMin> 4   Specifies a two char wait time for the target zDC to initialize in minutes. This parameter is optional. The default value is 30 minutes. The target zDC must have been initialized at least once since the last system IPL before the IMS Agent can complete initialization.
<Y|N> 5   A one-character value that indicates whether the IMS Agent should capture an SVC dump when ABEND recovery is driven. This parameter is optional and can be specified when the IMS Agent is initially injected, or specified in conjunction with the Modify or Enable function parameters to toggle dump capture during recovery on or off for a previously injected IMS Agent. The default value is N - dump capture is disabled.

Example 1: Inject the IMS Agent into IMS IB01 for zDC ZDC1. 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

Example 2: Disable the IMS Agent previously injected into IMSB for zDC ZDC1.

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

Example 3: Enable the previously injected, but disabled IMS Agent in IMSB for zDC ZDC1.

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

Example 4: Inject the IMS Agent into IMS IMSA for zDC ZDC1 and accept the defaults for Parameter#3 and Parameter#4 but specify that agent ABEND recovery should also capture an SVC dump. 

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

Example 5: Set agent ABEND recovery dump capture off for a previously injected IMS Agent.

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

Injection notes

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

If the target zDC has not been up since the last IPL, the injection job will wait 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 the wait time limit expires then injection cannot proceed and the job terminates with user ABEND code 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 job completes with RC=4.

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

Using an automation facility like IMS Time-Controlled Operations (TCO) is recommended to execute the IMS Agent injection job.

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

//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 100. In most cases the cause of failure can be determined by prior diagnostic messages that have been written to the job log. A symptom dump may also be written to the job log, depending on your zOS system parameters, but a dump will not be 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)

Garbage collection function notes

If new IMS Agent service updates (PTFs) are installed, ECSA storage for old (unused) IMS Agent load modules can be reclaimed with this function. After the injection job is run using the libraries containing the service updates, IMS message region activity is necessary to update internal control blocks to point to the new modules. After that occurs, you can rerun the injection program using the ‘G’ function to mark those old unused modules as candidates for deletion. Then after at least 3 hours has elapsed, run the injection program a second time using the ‘G’ function to release the ECSA storage containing those marked modules. You can run the injection program using the ‘G’ function 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.

IMS SOAP gateway instrumentation

The IMS SOAP Gateway runs on z/OS, z/Linux and Windows. Modify your IMS SOAP Gateway startup script (iogstart.sh or iogstart.bat) to instrument the gateway with the AppMon Java Agent. Refer to Java Agent Configuration for more details.

Windows example iogstart.bat:

Set zDt=-agentpath:"C:\Program Files\dynaTrace\dynaTrace <dTMajor>.<dTMinorVersion>.0\agent
lib\dtagent.dll"=name=IMSGw,server=<dTServerName>:9998,transformationmaxavgwait=150"
start "IMS SOAP Gateway" "!\_RUNJAVA!" !JAVA_OPTS! !zDT! -classpath !CLASSPATH!
org.apache.catalina.startup.Bootstrap %* start

IMS Connect Job Modification

Add the authorized AppMon IMS Agent dataset <HLQ>.SZDTIMSA to the IMS Connect job STEPLIB to permit IMS Connect to load the AppMon 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.

Preparing your System Profile for IMS Agents

Add an IMS tier to the system profile that was created in the installation of the zDC. The wizard presents a number of tiers that are available. Select the IMS Agent. You may want to add a tier for the Control Region(s) and a separate tier for the Application Region(s). You should name your tier(s) appropriately.

Select the Tier Type

Select the Tier Type

AppMon System Profile - IMS Agent Groups

In the AppMon Client, edit the System Profile for the IMS Agent Groups.

Add or edit the IMS Agent Groups for the IMS Agent. You may choose to include all IMS Agents within a single Agent Group, or assign some IMS Agents to separate Agent Groups.

Within each IMS Agent Group, under Agent Mapping, you must specify an Agent Name. This assigns the IMS Agent(s) to the desired Agent Group. An Agent is assigned to the first Agent Group in the list for which the Agent Name satisfies the Agent Mapping criteria.  The following is an example of a name specification that you can use to map all IMS Control Regions to the Agent Group.

Control Region Agent Mapping

Control Region Agent Mapping

Within each IMS Agent Group, under Sensor Placement, select the IMS sensors to place.

Note

Click in the sensor list and click Ctrl-F [Find] IMS to view the IMS related sensor packs. You can use this functionality anywhere in the product

Agent Group Sensor Placement

Agent Group Sensor Placement

The IMS sensors that you can place are:

  • IMS Connect API
  • CICS/IMS Gateways
  • IMS Control Region
  • IMS Application Region

Within each IMS Agent Group, under Sensor Configuration, select properties for the IMS sensors. The Java sensors for IMS Connect API and IMS SOAP Gateway have no configuration options. You can configure sensor properties for the IMS Control Region and IMS Application Region sensors.

IMS sensor properties

Use the following settings to configure the IMS Control Region Agent:

Setting Default Value Remarks
Enable SOAP sensor enabled Enables/disables the SOAP Sensor. When disabled, AppMon does not trace transactions that start through the IMS SOAP Gateway. When enabled, all transactions that start through the IMS SOAP Gateway are traced.
Enable MQ sensor disabled  Enables/disables the MQ Sensor. When disabled, AppMon does not trace transactions that start through the IMS MQ Bridge. When enabled, AppMon traces all transactions that start through the IMS MQ Bridge.
Enable IMS TM Resource Adapter sensor enabled Enables/disables the IMS TM Resource Adapter Sensor. When disabled, AppMon does not trace transactions that start through the IMS TM Resource Adapter. When enabled, all transactions that start through the IMS TM Resource Adapter are traced.
Enable transaction start sensor disabled  Enables/disables the transaction start sensor. When disabled, AppMon ignores the Transaction filters, and only traces the transactions that start through SOAP (when SOAP sensor is enabled), MQ (when MQ sensor is enabled), ITRA (when IMS TM Resource Adapter sensor is enabled), or the IMS Connect API. This setting does not affect the transaction codes that other sensors trace. This setting does not have to be on to trace transactions that start through IMS program switches, if the originating transaction is traced. When enabled, Transaction filters determine if AppMon should trace a transaction, if it does not start through SOAP, MQ, ITRA, or IMS Connect API. This sensor can start a path to trace an IMS transaction that cannot link to previous activity outside of IMS. 
Transaction filters  empty A list of transaction code patterns to be traced. Each entry in the list may be a transaction code or a transaction code prefix with an asterisk at the end. The TX sensor ignores transactions with names that don’t match an entry in the list. If an entry has a single asterisk *, all IMS transactions are traced. We do not recommend this.

Use the following settings to configure the IMS Application Region Agent:

Setting Default value Remarks
Enable DB2 sensor enabled Enables/disables the DB2 Sensor. When disabled, AppMon does not capture DB2 calls from the application region. When enabled, AppMon captures all DB2 calls (see Capture DB2 fetches).
Enable aggregation  enabled  Enables/disables the aggregation of DB2 calls by call type in the UI. When disabled, each DB2 call is a separate node in the PurePath. When enabled, AppMon summarizes each recurring DB2 call as a single node in the PurePath.  
Capture DB2 fetches  disabled  Enables/disables the capture of DB2 fetches. When disabled, DB2 fetches from the application region are not included in the captured DB2 calls. When enabled, DB2 fetches from the application region are included.
Enable DL/I sensor enabled  Enables/disables the DL/I Sensor. When disabled, AppMon does not capture DL/I calls from the application region. When enabled, it captures all DL/I calls.
Enable aggregation  enabled  Enables/disables the aggregation of DL/I calls by call type in the UI. When disabled, each DL/I call is a separate node in the PurePath. When enabled, AppMon summarizes each recurring DL/I call as a single node in the PurePath. 
Enable MQ sensor disabled Enables/disables the MQ Sensor. When disabled, AppMon does not capture MQ API calls from the application region and cannot start traces in the application region when an MQGET occurs, such as transactions that start through the IMS MQ Trigger Monitor. When enabled, AppMon captures all MQ API calls and can start traces. A trace in the application region is only started when the transaction issuing the MQGET is not already being traced by another sensor and the queue name passes the MQ queue name include/exclude filtering.
MQ queue include filters empty A list of queue name patterns to be included for potentially starting a trace when an MQGET occurs. Each entry in the list may be a queue name or a queue name prefix with an asterisk at the end. The MQ sensor will never start a trace on an MQGET from queues whose names do not match an entry in the list. By default, all queue names are enabled for tracing. This list is has no effect on the normal capture of MQ calls from the application region when another sensor is tracing the transaction.
MQ queue exclude filters empty A list of queue name patterns to be excluded from potentially starting a trace when an MQGET occurs. Each entry in the list may be a queue name or a queue name prefix with an asterisk at the end. The MQ sensor will never start a trace on an MQGET from queues whose names match an entry in the list. If a particular queue name matches both the include and exclude lists, the exclude list takes priority. This list is has no effect on the normal capture of MQ calls from the application region when another sensor is tracing the transaction.
Enable node limit  disabled Enables/disables node limit truncation. When disabled, AppMon ignores the associated specified value and does not restrict the number of nodes in the subpath. When enabled, AppMon truncates the subpath when it reaches the specified number of nodes. 

IMS Agent sensor notes

Agent initialization

Program ZDTIINST injects the IMS Agent into an IMS system, but the Control Region agent is not fully initialized until the IMS system receives an input message (it need not be for a transaction that will be tracked). Until this occurs, the application (dependent) region ADK and MQ sensors will not function. Similarly, an IMS application region is not fully initialized until some IMS work is scheduled in it.

Until the Control Region sensor configuration is obtained from the AppMon Server, no Control Region paths will be started. Until the dependent region sensor configuration is obtained, all sensors are assumed to be disabled.

Therefore, it is expected that until the agent is fully initialized and the sensor configuration is known, there may be some missed or incomplete PurePaths.

MSC considerations

The IMS agent can generate a PurePath that spans IMS Control Region hops across MSC connections on the same or different LPARs, provided that the IMS agent is injected into all participating IMS systems, and the applicable IMS Control region sensor is enabled for all participating IMS Control Regions. For example, if a transaction is submitted to IMSA from the MQ Bridge and that sensor is enabled for the IMSA Control Region, a path will be started. If that transaction, or any switched to transaction, is MSC routed to IMSB, the MQ sensor must be enabled for the IMSB Control Region as well in order to continue the path.

ADK or MQI get (Trigger Monitor) started transactions cannot be traced across MSC connections. Any transactions that are started due to program switches after the path is started will be included in the path, provided they execute on the local IMS system.