Install the zDC

The z/OS Data Collection subsystem (zDC) controls communication between the CICS/IMS code modules of OneAgent and the zLocal component. The zLocal component, hosted in z/OS Unix environment, runs as part of zDC. The zLocal handles the TCP/IP connection and transfers data between the mainframe and the distributed Dynatrace component called zRemote. You can enter Operator start, stop, and modify commands from a system console to control the zDC and the lifecycle of the zLocal.

Install the zDC

The zDC runs as an authorized z/OS process (typically as a system task). This means the programs must reside in an authorized library. It is intended to start automatically as a started task (STC) at a system IPL. This gives the zDC continuous availability to collect PurePath data from CICS and IMS code modules of OneAgent and forward it to Dynatrace.

The zDC can also be run as a batch job. The service class of the zDC must be high enough so that it is always available for keep-alive messages from the zRemote. The zDC should have a priority equal to or higher than the CICS application regions and the IMS dependent regions.

Download the OneAgent to the mainframe. Make a note of the high-level qualifier used in the download procedure.

Create the RACF user ID for the zDC process.

This ID must have a z/OS Unix segment. The recommended home directory name is /u/dt. If a directory other than /u/dt is used, update the DTAGTCMD argument in the zDC parameter file (the SYSIN DD of the proc) to specify the correct path to the dtzagent binary, which defaults to /u/dt/agent/lib64/dtzagent. Only the /u/dt/ part can be changed, because the path to the OneAgent binary must remain agent/lib64/dtzagent, regardless of the high-level qualifier used for this directory path. The /u/dt directory or the high-level qualifier that replaces it must be writeable by the zDC process. This is used for writing to /u/dt/agent/downloads/appmon/native/7.2.m.build, where m.build is the subversion of the release, to store the zLocal and to store the zDC and zLocal logs in /u/dt/log/dtxxx.log. If read/write fails, the /tmp/dynaTrace folder is used.

If the zDC is run as a started task, the ID must be capable of representing the zDC started task. Give the ID the same name as the zDC started task and add it to the access list of the RACF class STARTED with at least READ authority.

Change the dataset high-level qualifier represented by <hlq> in member COPYAGNT of SZDTSAMP to the value you used in the installation of the OneAgent for z/OS procedure.

Run the COPYAGNT job to create the required z/OS Unix subdirectories under the home directory of the zDC started task.

Copy the z/OS zLocal binary file from SZDTSAMP and set it to be executable.

If you're using the default home directory of /u/dt/, the resulting file is /u/dt/agent/lib64/dtzagent.

If the home directory has been changed, the paths in this job must be changed accordingly. File and directory names for zLocal are case-sensitive. The path names below the home directory cannot be changed.

The COPYAGNT job should run under the user ID that was created for the zDC process, so that user ID owns the dtzagent file. If this is inconvenient, you can also use the chown and chgrp commands to reset the owning user and group for the dtzagent file after running COPYAGNT.

Authorize <hlq>.SZDTAUTH where <hlq> is the high-level qualifier value you used in the installation of the OneAgent for z/OS procedure.

For example, create a member named SYS1.PARMLIB(PROGDT) containing:

APF FORMAT(DYNAMIC)
APF ADD DSNAME(<hlq>.SZDTAUTH) VOLUME(XXXXXX)

Then issue the console command:

SET PROG=DT

Copy the ZDCMEPC sample zDC started task procedure from SZDTSAMP to a system proclib used for started tasks.

The default name for the procedure is MEPC. Customize it as necessary for local standards. If a different subsystem name is chosen, change the SUBSYSTEM_ID() in the zDC SYSIN parameters to match. The proc and the two sysin members ZDCSYSIN and ZDCMEPCA that it uses contain dataset names that must be edited to replace <hlq>. with the appropriate high-level qualifiers.

Update the zDC startup parameters that are supplied through the SYSIN DD of the zDC proc, which defaults to the ZDCSYSIN member of SZDTSAMP.

  • DTAGTCMD(/u/dt/agent/lib64/dtzagent): Defines the path to the bootstrap OneAgent, dtzagent, if the default was not used.
  • nobootstrap=false: Defines the usage of the bootstrap OneAgent. Set false to use it or true to not use the bootstrap OneAgent. If not set, the default is to use the bootstrap OneAgent.
  • zremoteagent=<host>[:port]: Defines the IP address of the zRemote. The zRemote is a required parameter. The port is optional and defaults to 8898.

See the Failover processing for zDC/zRemote section for additional information on using the failover feature.

See the Non-bootstrap mode section for additional information on using zDC in non-bootstrap mode.

See zRemote for additional information on how to install and set up the zRemote.

Optional but recommended : Add a command to your system startup to automatically start the zDC subsystem at IPL.

Use the ZDCIVP procedure in SZDTSAMP to verify the zDC installation, deployment and zRemote connectivity.

Good test for the zRemote connectivity returns Connection timeout, as the zRemote does not support FTP protocol. If a zRemote connectivity problem exist, it is indicated by EDC8128I Connection refused. This implies that the zRemote is not listening on the expected port.