Installing the Unified Debugger session manager on a z/OS system

The session manager can handle communications between a debug client, such as the debug client of IBM Data Studio, and a Db2 for z/OS data server. The session manager can run on the client on which the Unified Debugger is installed, or on a z/OS system. For better performance when you debug Db2 for z/OS routines, you can install the session manager on a z/OS system.

Before you begin

Ensure that the session manager file, db2dbgm.jar, was installed on the z/OS system during the Db2 for z/OS installation process. It should be in following HFS directory: /usr/lpp/db2c10/base/lib.

About this task

The session manager that you install on a z/OS system is compatible with all currently supported versions of Db2 for z/OS. However, this could change in the future.

Procedure

To install the session manager on a z/OS system, follow these steps:

  1. Create the JCL for a started task that runs the session manager, in a member named DB2UDSMD in the system PROCLIB. See the comments in the example for the values that you need to change.
    Important: The started task must be named DB2UDSMD.
    //UDBG3 JOB CLASS=A,
// MSGCLASS=H,MSGLEVEL=(1,1), REGION=4096K,
// USER=STDTSKID,PASSWORD=STDTSKPW
//*--------------------------------------------------------------------
//* This job creates the started task JCL for DB2UDSMD. You can then 
//* launch the Unified Debugger session manager on z/OS with a 
//* START command.
//* - Change STDTSKID and STDTSKPW to the user ID and password that
//*   are associated with the started task.
//*   The ID that is associated with the started task is defined in
//*   the RACF STARTED class profile DB2UDSMD.**
//*--------------------------------------------------------------------
//*--------------------------------------------------------------------
//* This step uses IEBUPDTE to write a JCL member into your system 
//* PROCLIB.
//* - Change SYS1.PROCLIB to the name of your system PROCLIB.
//*--------------------------------------------------------------------
//WRITEJCL EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSUT2 DD DISP=SHR,DSN=SYS1.PROCLIB
//SYSIN DD DATA
./ ADD NAME=DB2UDSMD
//DB2UDSMD PROC PORT=4553,TIMEOUT=60
//*
//* DB2UDSMD starts the Unified Debugger session manager daemon for 
//* UNIX System Services.
//* Change the default PORT and TIMEOUT values to valid values
//* for your z/OS system. You can override these values when 
//* you issue the START command for the DB2UDSMD started task.
//*
//* This JCL assumes that no .profile file exists for the user
//* ID under which the started task runs.
//*
//* Environment settings (PATH, CLASSPATH) come from the
//* file that is specified by the STDENV DD statement.
//* - Change /u/stdtskid/DB2UDSMDenvironment to the path and   
//*   file name for the environment file.
//* - Change the paths in the STDOUT and STDERR to the appropriate
//*   paths for your UNIX System Services installation.
//*   Ensure that the user ID under which the started task runs
//*   has the privileges to write to STDOUT and STDERR.
//DB2UDSMD EXEC PGM=BPXBATCH,DYNAMNBR=128,REGION=0M,TIME=1440,
// PARM='SH date;java com.ibm.db2.psmd.mgr.Daemon -timeout
// &TIMEOUT -port &PORT -log /dev/null;date'
//STDOUT DD PATH='/tmp/DB2UDSMD.stdout',
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND,OTRUNC),
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)
//STDERR DD PATH='/tmp/DB2UDSMD.stdout',
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND,OTRUNC),
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)
//STDENV DD PATH='/u/stdtskid/DB2UDSMDenvironment',
// PATHOPTS=ORDONLY
// PATHOPTS=ORDONLY
./ ENDUP
/*
  2. Define the DB2UDSMD started task to RACF, by customizing and running JCL similar to this example: 
    //UDBG1 JOB ...
//*------------------------------------------------------------------
//* A security administrator runs this job to define the started task 
//* for the Unified Debugger session manager to RACF. The job  
//* performs these steps:
//* 1. Defines an OMVS segment for the user ID that is associated
//*    with the started task. This step is necessary because the
//*    started task runs a Java program from OMVS. In the ALTUSER
//*    statement:
//*    - Change STDTSKID to the user ID that is associated with
//*      the started task.
//*    - Change /u/stdtskid to the current working directory for 
//*      the user's process when the started task issues the OMVS
//*      command.
//* 2. Adds a profile for the started task, which is named
//*    DB2UDSMD.** to the RACF database.
//*    In the RDEFINE statement, change STDTSKID to the user ID
//*    that is associated with the started task. 
//* 3. Activates the started task definition in current memory.
//*------------------------------------------------------------------
//RACFDEF EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=A
//SYSTSIN DD *
ALTUSER STDTSKID OMVS( UID(5) HOME('/u/stdtskid') PROGRAM('/bin/sh') )
RDEFINE STARTED DB2UDSMD.** STDATA(USER(STDTSKID))
SETROPTS RACLIST(STARTED) REFRESH
END
  3. Create the file in the home directory of the user ID under which the DB2UDSMD started task runs. The file must specify at least the settings for the ENV, PATH, and CLASSPATH parameters. 
    //UDBG2 JOB ...
//*--------------------------------------------------------------------
//* Create a file in HFS to hold the environment settings that are used
//* when the Unified Debugger session manager runs as a started task 
//* on z/OS.
//*
//* Replace /u/stdtskid with the path that is associated with the 
//* home directory of the user ID under which the started task runs.
//* You can use DB2UDSMDenvironment for the environment file name, 
//* or change the name to something else. The environment file path  
//* and name need to be the same as those specified in the JCL for 
//* the session manager started task.
//*--------------------------------------------------------------------
//OCOPY EXEC PGM=IKJEFT01,DYNAMNBR=30
//SYSTSPRT DD SYSOUT=*
//HFSOUT DD PATH='/u/stdtskid/DB2UDSMDenvironment',
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND,OTRUNC),
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)
//INLINE DD *
#----------------------------------------------------------------------
# Environment settings for running the Unified Debugger session manager:

# The _BPX_BATCH_SPAWN=NO and _BPX_SHAREAS=YES settings
# cause the JVM to run in the same address 
# space as the z/OS UNIX shell. Doing this avoids launching two
# additional address spaces for the started task.
# 
# The ENV variable value identifies the file that contains the 
# location of the environment variable settings. For the session
# manager, set the location to this file. Replace 
# /u/stdtskid/DB2UDSMDenvironment with the path and file name
# for this file.
#
# The PATH variable value identifies the path name where 
# the Java runtime environment binaries and the system binaries
# are located.
#
# The CLASSPATH variable value identifies the location of the 
# session manager db2dbgm.jar file.
# 
# The JAVA_COMPILER=NONE setting disables the JIT compiler.
# The started task runs the session manager only once, so 
# disabling the JIT compiler saves space.
#----------------------------------------------------------------------
_BPX_BATCH_SPAWN=NO
_BPX_SHAREAS=YES
ENV=/u/stdtskid/DB2UDSMDenvironment
PATH=/usr/lpp/java170/J7.0/bin:/bin
CLASSPATH=/usr/lpp/db2c10/base/lib/db2dbgm.jar
JAVA_COMPILER=NONE
//SYSTSIN DD *
OCOPY INDD(INLINE) OUTDD(HFSOUT) TEXT
  4. Start the session manager on z/OS to ensure that it was installed correctly, by completing the following steps:
    1. Issue the following command on the z/OS console. 
      START DB2UDSMD,TIMEOUT=1
    2. Wait several minutes. During that time, the following events occur:
      1. The started task is launched.
      2. The session manager program begins.
      3. The session manager waits for activity for one minute.
      4. The session manager shuts down.
  5. Review the contents of the HFS file that is assigned to STDOUT in the started task JCL.
    The following example shows output when the test is successful. The args array contains three keyword and value pairs that indicate:
    • The period after which the session manager times out if there is no activity
    • The port number of the session manager's network address
    • The path name of the file that contains the session manager trace, the timeout, port values, and the location of the log.
    args[0]: -timeout
args[1]: 1
args[2]: -port
args[3]: 4553
args[4]: -log
args[5]: /dev/null
Code Level: 070418
Debug Session Manager started on IP: 9.30.114.205 - port: 4553
idleTimeOut: 1
  6. Specify in the IBM Data Studio routine debugger preferences that you want to use the session manager that is on the z/OS system by selecting the option "Run the session manager on each connected server."

    The port number must match the port number that you specify when you start the DB2UDSMD started task. If you do not specify a port number when you start DB2UDSMD, the port number that you specify in the routine debugger preferences must match the default port number in the DB2UDSMD started task JCL.

    The port number can identify a session manager anywhere on the network. A session manager is associated with a z/OS system or LPAR, and not with a specific Db2 for z/OS subsystem or data sharing group.

  7. Optional: Set up additional session managers.

    A single debug session can connect to only a single session manager. However, you can follow these steps to connect to another session managers on the same z/OS system.

    1. In the IBM Data Studio routine debugger preferences, specify a different port to which you want the Unified Debugger to connect.
    2. Start DB2UDSMD with the port number that you specified in the previous step. 
      START DB2UDSMD,PORT=4558

    To set up additional session managers on different LPARs, follow these steps:

    1. Create the JCL for a started task that runs the session manager, in a member named DB2UDSMD in the system PROCLIB of the LPAR.
    2. In the IBM Data Studio routine debugger preferences, specify a port to which you want the Unified Debugger to connect.
    3. Start DB2UDSMD with the port number that you specified in the previous step.