Install OneAgent on CTG and IMS SOAP gateway

Dynatrace supports CICS Transaction Gateway (CTG) and IMS SOAP Gateway running in a JVM on z/OS to collect path events. You need to download the OneAgent installer (oneagentjava4z.jar file) from the Dynatrace FTP site and follow the instructions to deploy it in your CTG or IMS SOAP Gateway.

Download OneAgent

Use the following JCL or the FTP program of your choice to download the oneagentjava4z.jar file as binary to the folder of your choice on OMVS.

If you're using a 32-bit JVM, use the agent/lib folder, rather than the agent/lib64 folder.

zos/jcl.txt
Download
//jobname  JOB ('ACCTINFO'),'User name or comment',NOTIFY=&SYSUID,
//             MSGLEVEL=(1,1),CLASS=A,MSGCLASS=X
//*
//* This job obtains OneAgent installer oneagent4z.jar file via
//* FTP.
//*
//* Change the JOB card and the PATH on the SET statement below to meet
//* site standards.
//*
// EXPORT SYMLIST=(PATH)
// SET PATH='/u/dt/agent/lib64'      <===== SET INSTALL PATH HERE
//*
//FTP     EXEC PGM=FTP,DYNAMNBR=20,PARM='(EXIT TIMEOUT 99)',TIME=5
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *,SYMBOLS=EXECSYS
us-et-ftp01.dynatrace.com
Dynatrace72
dynatrace72
binary
cd oneagentjava4z_7.2
lcd '&PATH'
get oneagentjava4z.jar
quit
/*
//

Add OneAgent to CTG environment

  1. Modify the CTGENV member and the CTGSTART_OPTS variable to include the following:
    -j-javaagent:/u/dt/agent/lib64/oneagentjava4z.jar=\
    zdc-name=<YOUR_ZDC_SYSID>,log-stderr=true
    
    Where <YOUR_ZDC_SYSID> is your zDC Subsystem ID, without the brackets, for example zdc-name=MEPC.
  2. Stop and restart your CTG. You should see the OneAgent start.

Add OneAgent to IMS SOAP Gateway

  1. Modify your IMS SOAP Gateway parameters to include the following new option zDT:
    zDT="-javaagent:/u/dt/agent/lib64/oneagentjava4z.jar=\
    zdc-name=<YOUR_ZDC_SYSID>,log-stderr=true
    
    Where <YOUR_ZDC_SYSID> is your zDC Subsystem ID, without the brackets, for example zdc-name=MEPC.
  2. Due to an issue with the IBM JIT, you must add the following as well:
    # OPTION: per Dynatrace - don't JIT this class
    IJO="$IJO -Xjit:exclude={com/ctc/wstx/sr/StreamScanner.parseLocalName*}"
    
  3. Finally, export the new Java options defined in the zDT variable so that IBM_JAVA_OPTIONS includes them.
    export IBM_JAVA_OPTIONS="$IJO $zDT $JAVA_OPTS"
    

JVM is executing in a program controlled environment

After starting CTG or IMS SOAP Gateway you may see Not Marked Program Controlled messages or see errors with the 139 return code:

BPXP015I HFS PROGRAM /tmp/liboneagentjava4z805526126412670287.so IS NOT MARKED PROGRAM CONTROLLED.

This usually means that OneAgent must be program controlled.

To configure OneAgent to be program controlled

Expand oneagentjava4z.jar that you downloaded into a program controlled folder.

Mark the appropriate .so file (31 or 64 bit) in the lib/zos-s390/ directory as program controlled.

Switch to the path that contains the .so files and issue the following command using the 31 or 64 bit file:

extattr +p liboneagentjava4z_64.so

In the -javaagent statement add:

,zdc-stub-library-override=<fullpath>/<file>.so

Where <fullpath> is the full path to the .so file and the <file>.so is the liboneagentjava4z_XX.so that you marked program controlled.

Restart the JVM.