Upgrading zOS Agents


Upgrade AppMon Servers, Collectors, Agents and Performance Warehouse

Before starting any migration action for your z/OS Agents, read the general Upgrade to 7.0 guide and create a detailed plan for the upgrade of your AppMon Servers, Collectors, other Agents, and the Performance Warehouse and other components. For less maintenance overhead coordinate these upgrades to coincide with application restarts.


The z/OS Agent can't directly connect to an AppMon Collector without first going through a zRemote Agent. Using the zRemote Agent reduces CPU consumption on z/OS. If your current pre-6.2 z/OS Agent deployment omitted the zRemote Agent, you must install it as a part of your upgrade. See zRemote Agent for more information.


You need valid licenses for the AppMon Server. See License Upgrade for more information. Although z/OS Agents are licensed MSU-based, the AppMon Server enforces the number of current connected CICS and IMS regions. See Prepare to Upgrade and License Upgrade for more information.

Upgrade procedure

Upgrade the AppMon Server and Collector as described in Upgrade to version 7.0 prior to upgrading the mainframe components. While newer zOS Agents are generally not compatible with older AppMon Collectors or Servers, newer AppMon Collectors or Servers usually work with older zOS Agents.

Follow the standard Agent installation process. This consists of running the JCL to download the agent distribution file and running SMP/E to populate the target datasets for the new release. See Download and SMP/E install of the z/OS Agent Components for more information.

Do one of the following:

  • Stop your current zDC and update the zDC authorized libraries to the version 7.0. Before you restart the z/DC, you should ensure that the zDC parm DTMSG_SMOSIZE has been uncommented and that parm DTMSG_QSIZE has been deleted. These parameters control whether messages are queued in the zDC dataspace or in the zDC 64-bit shared memory object (SMO) pending their writing to the AppMon Agent.
    The use of dataspaces has been deprecated. If you customize the ZDCSYSIN sample contained in the 5.6 version, you can skip this step because the sample already incorporates this change. After the zDC has been started, the CICS and IMS agents should register within 5 minutes. - OR -
  • Create a parallel 7.0 environment for the zDC and zLocal (formerly USS) Agent. Follow instructions in Installing the zDC. With a parallel 7.0 environment, you can continue running the old z/DC while you migrate individual CICS regions and IMS control regions over to the new zDC. You can also test regions before upgrading the default zDC. If multiple zDCs are running, the one that specifies DEFAULT(YES) is chosen unless an INITPARM parameter in the CICS or IMS system initialization parameters specifies that it must connect to a zDC with a particular name: INITPARM=(ZDTPLT6x='xxxx').


  • There can be only one zDC per LPAR with the DEFAULT (YES) option.
  • The SUBSYSTEM_ID must be unique to each zDC.
  • The library used in the zDC STEPLIB must be authorized.

The bootstrap Agent automatically upgrades the zLocal Agent when it first connects to an upgraded AppMon Collector/Server. Since the zLocal Agent is not part of the SMP/E install on the mainframe, for the initial install, the zLocal Agent must be bootstrapped. To do so. set the nobootstrap parameter as false in member ZDTINST (this is set to false by default).

Also, the automatic Agents update must be enabled:

  1. In the Client, click Settings > Dynatrace Server > Updates.
  2. Select the Automatically update Agents to latest version checkbox.

After the initial install, these settings can be reset to disallow agent bootstrapping. See Installing the zDC for more information on the mainframe install.

Because the AppMon new version zDC is compatible with older CICS and IMS Agents, you don't need to upgrade all CICS regions and IMS control regions at once. However, if you monitor transactions cross CICS regions or IMS control regions, those related regions should be at the same Agent version otherwise incomplete PurePaths occur. Consequently, upgrading CICS regions and IMS control regions should be done with consideration to application groupings. Plan on upgrading all of your CICS regions and IMS control regions as soon as possible to take advantage of the features that come with the new AppMon version.

  • To upgrade your CICS regions, replace the DFHRPL concatenation of the old PDS (or its contents) with the new PDS (or its contents). For example:

  • To upgrade your IMS control regions, replace the STEPLIB PDS (or its contents) in the JCL that executes the IMS Agent injection program, ZDTIINST, with the new PDS (or its contents). // DD DISP=SHR,DSN=<hlq>.LZDT700.SZDTAUTH


The library used in the STEPLIB must be authorized.

See Migration Troubleshooting for the AppMon component compatibility table.