Debugging stored procedures on DB2 for z/OS with Optim Development Studio, Part 2: Configure the stored procedure debug session manager on z/OS

Learn step-by-step how to configure the Unified Debugger session manager for use on a z/OS® system, and learn how to use routines to manage the session manager. Proper setup of the session manager on z/OS can facilitate using IBM Optim Development Studio to debug stored procedures on DB2® for z/OS servers. [24 Feb 2011: This update reflects the change from the Data Studio Developer product to the Optim Development Studio product.]

Share:

Hongdi Zhang (emilyz@us.ibm.com), Advisory Software Engineer, IBM

Emily ZhangHongdi Zhang is an advisory software engineer for IBM's Application Development Tooling organization at Silicon Valley Laboratory in San Jose, CA. She is a member of the development team for IBM Data Studio. Her areas of expertise include routine tooling development and unified debugger.



Tom Miller (millerrt@us.ibm.com), Senior Software Engineer, IBM

Tom MillerTom Miller is a senior software engineer at the IBM Silicon Valley Laboratory in San Jose and an IBM veteran since 1982. Since 2001, Tom has been a member of the DB2 for z/OS Development team, leading the SQL stored procedure technologies. Tom is a member if the IBM Unified Debugger development team, bringing the Unified Debugger technology to Java and SQL procedures on DB2 for z/OS. Prior to his current assignment, Tom was the QMF Architect.



24 February 2011 (First published 19 March 2009)

Also available in Chinese

Introduction

This article follows Part 1 about using the Unified Debugger from Optim Development Studio. That article, for simplicity, focused on a configuration in which the Unified Debugger session manager was configured on the client or on another server in the network. This article describes how to set up and operate the Unified Debugger session manager on the z/OS server, which can improve debugging performance.

Learning about the Unified Debugger session manager

This following section provides a quick introduction to the session manager, and it offers a quick review of debugging.

IBM Optim Development Studio incorporates a Unified Debugger client. It supports debugging both SQL and Java™ stored procedures. When you debug a stored procedure within Optim Development Studio, you use a technology called the Unified Debugger. The Unified Debugger has three components: the debug server, the debug client, and the session manager, as shown in Figure 1.

Figure 1. Unified Debugger framework
Shows components of the framework: DB2 server, session manager, and client debugger

In this framework, the debug client talks to the session manager, and the debug server talks to the session manager. The session manager is in the middle, facilitating communication between the separated client and server components to manage the overall debug session. For more information about the Unified Debugger, see Part 1.

The session manager is an important component central to the Unified Debugger framework. The session manager is a process that must be running somewhere in the network (at the client, at the connected DB2 server, or somewhere else in the network) before you can debug stored procedures with Optim Development Studio. When the session manager is running, it behaves like a network daemon, coordinating communication between a debug client and a DB2 server using TCP/IP connections. You have the flexibility to run it anywhere on the network. If you do not have the session manager set up correctly on z/OS, your debug experience with Optim Development Studio can be impacted, requiring additional manual intervention.

Understanding session manager capability and availability on DB2 for z/OS

The Unified Debugger is fundamentally a DB2 V9-based technology. Therefore, DB2 V9 servers can use the full range of the Unified Debugger capabilities, features, and components. The session manager is an independent Unified Debugger component, and it is distributed with the various new client and DB2 server products released since 2006. While the earlier DB2 V8 releases can use a subset of the Unified Debugger server component (known formerly in V8 as the SQL Debugger), DB2 V8 does not include the session manager, nor does it include the capability to launch the session manager.

Table 1 shows a summary of the Unified Debugger features and session manager availability on the different DB2 levels.

Table 1. Comparing features for different DB2 for z/OS versions
DB2 10 for z/OS, DB2 Version 9.1 for z/OS DB2 z/OS v8 (with PTF UK25860 applied)
The Unified Debugger can debug both LANGUAGE SQL and LANGUAGE JAVA stored procedures, as well as non-inline scalar user-defined functions on DB2 10 for z/OS.The Unified Debugger can debug LANGUAGE SQL stored procedures.
The Unified Debugger session manager program (db2dbgm.jar) is distributed along with the DB2 base feature.No session manager program is distributed on the platform. The session manager program can be copied to this platform from the debug client distribution and run manually.
The DBG_RUNSESSIONMANAGER support routine is provided (requires started task setup of the DB2UDSMD daemon).No support is available for debug clients to launch the session manager at the connected server.
This is similar to DB2 for Linux, UNIX, and Windows® V9 and DB2 for i V5R4.This is similar to DB2 for Linux, UNIX, and Windows V8 FP15.

Debugging with Optim Development Studio

The previous article went into detail about debugging stored procedures. This section offers a brief review before delving into how to set up the session manager.

To debug stored procedures, the SQL or Java stored procedure must meet the following conditions:

  • It must be visible in the Data Project Explorer or the Data Source Explorer. To debug in the Data Project Explorer, you can create a new stored procedure in the Data Development project, or you can copy or drag a stored procedure from the Data Source Explorer (formerly known as the Database Explorer) to the Data Project Explorer.
  • It must be enabled for debugging.

To determine whether the stored procedure is enabled for debugging, right-click the stored procedure. The debug menu is available as an option, as shown in Figure 2.

Figure 2. Procedure with debug enabled
Screep cap: Debug appears in dropdown menu

If your server connection supports the Unified Debugger but the Debug menu option is grayed out, you must deploy the stored procedure with the debug option. Right-click the stored procedure, and select Deploy. When launching the Deploy Routines wizard, you need to check the Enable debugging checkbox on the Routine Options page, as shown in Figure 3.

Figure 3. Deploy Routines wizard
Routine Options screen with Enable Debugging checked

When you have this checkbox checked, a successful deployment causes the debug mode setting to be reflected in the DB2 catalog.

Two important points

  • If you plan to debug LANGUAGE JAVA stored procedures on a DB2 V9 server, use the same session manager for all the debug clients that will be debugging LANGUAGE JAVA stored procedures on that DB2 server. The default session manager location at the connected server is recommended in this case.
  • Always use single-member access when connecting Optim Development Studio to a data-sharing group server. This is particularly important when the checkbox for Use the session manager on each connected server is selected. Otherwise the host IP address of the server can vary, which adversely impacts the ability of Optim Development Studio to locate and manage the session manager at the server.

After you deploy for debugging, configure the IBM Routine Debugger preferences to set up debugger-related preferences, including the location of the session manager to use for debug sessions.

  1. Select Window > Preferences from the top menu bar.
  2. Expand Run/Debug.
  3. Select Routine Debugger, and select IBM.

If you select the checkbox for Run the session manager on each connected server, Optim Development Studio looks for a session manager running at the connected server. If ODS does not find a session manager, ODS requests a session manager to be run at that location (DB2 V9 for z/OS only). Alternatively, you can use the built-in session manager, or you can manually run a session manager somewhere and identify that location under the Use already running session manager section, as shown in Figure 4.

Figure 4. Debugger preference page
'Use the seesion manager on each connected server' is checked with Port 4553 and Timeout 30

As you can see, there are different ways to arrange a session manager to use for debugging. This article helps you further exploit these options on the z/OS platform.


Setting up the session manager as a daemon on a z/OS server

To seamlessly use the session manager with Optim Development Studio at a connected DB2 z/OS V9 server, you must define a daemon named DB2UDSMD to the z/OS system. On z/OS, a daemon is represented by a started task, which is a special type of task that can be launched with the z/OS system command START. The definition of the started task DB2UDSMD is like that of other familiar system daemons, such as FTPD and TELNETD. The started task has its own JCL to run the session manager Java program (db2dbgm.jar). The started task is also associated with a special security system definition that ties the JCL to a designated user ID.

Following are the steps to set up the started task.

Step 1: Define the started task JCL to RACF

Define the started task DB2UDSMD to the security system on z/OS using JCL. You will need to specify a user ID to be associated with the started task. In addition, because the started task will be running a Java program from OMVS, you must define an OMVS segment definition for that user, including user ID and home directory. Finally, you need to activate the started task definition in current memory. Listing 1 shows an example.

Listing 1. Defining the started task to RACF
//UDBG1    JOB ('RACF'),CLASS=A,MSGCLASS=A,MSGLEVEL=1,                  
//         USER=********, PASSWORD=*******                               
//*--------------------------------------------------------------------
//* Define the Unified Debugger Session Manager Started Task to RACF.   
//* A security manager ID must be used to perform the definitions.     
//*                                                                     
//* The STARTED task is defined by a RACF profile named DB2UDSMD.**     
//* USRT005 will be the ID associated with this Started Task.           
//* Since the task will run a java program from OMVS, also assign an    
//* OMVS segment definition to the user (UID, home dir, etc.)          
//* Finally, activate the STARTED task definition in current memory.    
//*--------------------------------------------------------------------
//RACFDEF  EXEC TSOBATCH                                                
//SYSTSIN DD *                                                          
  ALTUSER USRT005 OMVS( UID(5) HOME('/u/usrt005') PROGRAM('/bin/sh') ) 
  RDEFINE STARTED DB2UDSMD.** STDATA(USER(USRT005))                     
  SETROPTS RACLIST(STARTED) REFRESH                                     
END

Step 2: Create the environment settings

Next, create a file in the HFS to hold the environment settings that are used when the Unified Debugger session manager runs as a started task on z/OS. Name the file something recognizable, such as DB2UDSMDenvironment.

Place the file DB2UDSMDenvironment in the home directory of the ID you selected for the started task in Step 1. At a minimum, this file must specify the values for ENV, PATH, and CLASSPATH. The default location for the session manager jar file in the HFS that is distributed with DB2 for z/OS V9 is /usr/lpp/db2910_base/classes/db2dbgm.jar.

Listing 2 shows the full contents of a sample file DB2UDSMDenvironment saved in USRT005's home directory. You can use this file as a template to write your own job.

Listing 2. Sample environment file settings for session manager
//UDBG2    JOB 'USER=$$USER','<USERNAME:JOBNAME>',CLASS=A,             
//         MSGCLASS=A,MSGLEVEL=(1,1), REGION=4096K,        
//         USER=USRT005,PASSWORD=*******                                  
//*--------------------------------------------------------------------
//* Create a file in the HFS to hold the Environment settings used when
//* the Unified Debugger Session Manager runs as a Started Task on z/OS
//*                                                                    
//* USRT005 is the ID associated with the Started Task.                
//* Place the file in that users home directory.                       
//* Name the file DB2UDSMDenvironment                                      
//*--------------------------------------------------------------------
//*--------------------------------------------------------------------
//* Create a file in the HFS from inline data using COPY               
//*--------------------------------------------------------------------
//OCOPY    EXEC PGM=IKJEFT01,DYNAMNBR=30                               
//SYSTSPRT DD SYSOUT=*                                                 
//HFSOUT   DD  PATH='/u/usrt005/DB2UDSMDenvironment',                      
//             PATHOPTS=(OWRONLY,OCREAT,OAPPEND,OTRUNC),               
//             PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH)                  
//INLINE   DD *                                                        
#----------------------------------------------------------------------
# Environment settings for running the Unified Debugger Session Manager
# * _BPX_BATCH_SPAWN=NO                                                
# * _BPX_SHAREAS=YES                                                   
#     Arrange for the JVM to run in the same address space. This avoids
#     launching 2 additional address spaces for the Started Task.      
# * ENV=                                                               
#     Reference this file. Insulates from PATH and CLASSPATH changes    
#     present in etc/profile.                                          
# * PATH=                                                              
#     The location of the desired JAVA release, and system binaries.   
# * CLASSPATH=                                                         
#     The location of the UDBG Session Manager jar file                
# * JAVA_COMPILER=NONE                                                 
#     Disable the JIT. The Started Task runs the Session Manager only  
#     one time, so disabling this saves space that will not be used.   
#----------------------------------------------------------------------
_BPX_BATCH_SPAWN=NO                                                    
_BPX_SHAREAS=YES                                                       
ENV=/u/usrt005/DB2UDSMDenvironment                                     
PATH=/usr/lpp/java150/J5.0/bin:/bin                                    
CLASSPATH=/usr/lpp/db2/db2910_base/classes/db2dbgm.jar                 
JAVA_COMPILER=NONE                                                     
//SYSTSIN DD *                                                         
OCOPY INDD(INLINE) OUTDD(HFSOUT) TEXT                                  
//

Step 3: Create the started task JCL

Create the started task JCL for the Unified Debugger session manager, and place it in the system proclib. This JCL must be named DB2UDSMD. This JCL runs the Unified Debugger session manager on z/OS in response to a START command. In the example, USRT005 is the ID associated with this started task, as defined in the RACF started class profile DB2UDSMD.**. Listing 3 shows an example of the started task JCL.

Listing 3. Sample job to create the started task JCL
//UDBG3    JOB 'USER=$$USER','<USERNAME:JOBNAME>',CLASS=A,              
//         MSGCLASS=A,MSGLEVEL=(1,1), REGION=4096K,         
//         USER=********,PASSWORD=*******                               
//*--------------------------------------------------------------------
//* Create the Started Task JCL for DB2UDSMD. A START command will then
//* be able to launch the Unified Debugger Session Manager on z/OS.
//* USRT005 is the ID associated with the Started Task, as defined in  
//* the RACF STARTED class profile DB2UDSMD.**                          
//*--------------------------------------------------------------------
//*--------------------------------------------------------------------
//* Use IEBUPDTE to write a JCL member into SYS1.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                                    
//*                                                                     
//*    DB2 Unified Debugger Session Manager DAEMON FOR OPENEDITION      
//*                                                                     
//*    This JCL assumes no .profile exists for the user.              
//*  
//* Environment settings (PATH, CLASSPATH) come from STDENV file.  
//*                                                                   
//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/usrt005/DB2UDSMDenvironment',                 
//             PATHOPTS=ORDONLY                                       
//             PATHOPTS=ORDONLY                                         
./  ENDUP                                                               
/*

You can use the code in Listing 3 to create your file by following these steps:

  1. Replace the STDOUT, STDERR, and STDENV paths. Note that STDENV refers to the HFS file created in Step 2.
  2. Ensure the ID assigned to the started task in Step 1 has the proper privileges to read and write the files for STDOUT and STDERR.
  3. Change the default values for PORT and TIMEOUT.

Step 4: Test

You can test the completion of Steps 1-3 by issuing this START command at the z/OS console: START DB2UDSMD,TIMEOUT=1 Wait a couple of minutes to allow sufficient time for the started task to launch, the session manager program to initialize, and a minute of inactivity before it shuts down. After the started task DB2UDSMD ends, review the contents of the HFS file specified in STDOUT in the started task JCL. Listing 4 shows an example of successful results.

Listing 4. Example of successful HFS file results
Mon Mar 2 12:48:32 PST 2009
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.88.135 - port: 4553
idleTimeOut: 1
Mon Mar 2 12:49:37 PST 2009

Using the session manager support routines

The Unified Debugger provides the following DB2 stored procedures for supporting session manager operations:

DBG_LOOKUPSESSIONMANAGER
Discover the default session manager network address.
DBG_PINGSESSIONMANAGER
Detect an active session manager somewhere on the network.
DBG_RUNSESSIONMANAGER
Launch a session manager at the connected DB2 server system using the started task definitions described earlier.

These stored procedures are installed during Unified Debugger setup on a DB2 z/OS server by running the DB2 provided post-installation job DSNTIJSD. After installation, you can view and run these stored procedures using Optim Development Studio. The procedures are listed under the SYSPROC schema in the Data Source Explorer, as shown in Figure 5.

Figure 5. DBG procedures under SYSPROC schema in Data Source Explorer
Stored procedures under SYSPROC schema, lookup, ping, and run highlighted

The following sections describe the procedures in more detail.

DBG_LOOKUPSESSIONMANAGER

DBG_LOOKUPSESSIONMANAGER is used to show the default session manager network address from the perspective of the DB2 server. This is a convenient routine to call from Optim Development Studio. It requires no input, and it always returns the IP address of the server and the default session manager listening port for every call. The Unified Debugger assigns 4553. Figure 6 shows the information you need to manage a session manager at the connected DB2 server using other Unified Debugger support routines.

Figure 6. Look up the default session manager address
Look up the default session manager address, success message

DBG_PINGSESSIONMANAGER

DBG_PINGSESSIONMANAGER is used to test for the existence of a running session manager. It is an active routine that contacts or pings a session manager at the specified IP address and listening port. This can be any session manager running on the network, not just the one running at the connected DB2 server.

This is the most important session manager support routine, because it validates actual communication with a session manager across the network from the perspective of the DB2 server. This is the same communication pathway that is exercised during debugging of stored procedures.

Figure 7 shows how to use DBG_PINGSESSIONMANAGER to test for a running session manager at the default host address and port obtained using DBG_LOOKUPSESSIONMANAGER.

Figure 7. Specify parameters of DBG_ PINGSESSIONMANAGER
Specify parameters of DBG_ PINGSESSIONMANAGER, Host, varchar, IP address

After running this procedure successfully, check the Parameters tab in the SQL Results view. If the output parameter XMLREPLY has no value, the ping to that host IP failed, as shown in Figure 8.

Figure 8. Unsuccessful ping of a session manager
Success message but no value for Value (OUT)

An unsuccessful ping means that either no session manager is running at that IP address listening on that port, or there is a network connectivity issue reaching that IP address. Because the example involves pinging a session manager at the same IP address as the connected DB2 server, you can rule out network connectivity issues. So, you can determine with certainty if there is a session manager running at the connected DB2 server, listening on the designated port.

DBG_RUNSESSIONMANAGER

DBG_RUNSESSIONMANAGER is used to launch the session manager at the connected DB2 server. It is an active routine that uses the local operating system facilities to start the session manager as a new system task. On z/OS, a START command performs this event but requires definition of the DB2UDSMD started task.

The inputs to DBG_RUNSESSIONMANAGER are the desired listening port and a time interval for the session manager to remain active while waiting for a debug session to manage. The example in Figure 9 shows use of the default listening port value 4553 and 30 minutes of idle wait time. (Note that the IP address is implied, which is the same host address that DBG_LOOKUPSESSIONMANAGER returned.)

Figure 9. Specify parameters of DBG_RUNSESSIONMANAGER
Specify parameters of DBG_RUNSESSIONMANAGER, Idletimeout is 30

On z/OS, the DBG_RUNSESSIONMANAGER stored procedure is really just a vehicle to issue the system command START DB2UDSMD. The return code from the START command is buried within the BLOB output parameter XMLREPLY. (This output is intended for programs rather than direct user consumption. If you want, you can dig for the return code specification in the hexadecimal notation, starting at position 141. Look for 72633D223022, which reflects the six binary characters of rc=“0”.)

To see enough characters to discover the return code, complete the following steps:

  1. Switch to Display result in text mode by clicking on the icon shown in Figure 10.
Figure 10. Run session manager result
Page icon highlighted at top of screen

This changes the icons at the top of the display, as shown in Figure 11.

Figure 11. Run session manager result Text mode display
Icons at top of screen now missing
  1. Scroll to the right to get to the correct position (141) to see the return code, as shown in Figure 12.
Figure 12. Run session manager result Text mode display rc=”0”
72633D223022 circled with the 30 circled twice for emphasis

Getting a zero return code from the START command is important, but it is not an indication of a running session manager. Issuing the START command is like pressing the launch button for a rocket. If everything is in good working order, the engines ignite, the rocket leaves the launch pad, and the rocket delivers the satellite into orbit where the satellite unfurls its antenna and begins communication. Similarly, the session manager is not assured to be ready for use immediately after calling DBG_RUNSESSIONMANAGER. It takes a period of time for the new system task to start, for the Java environment to be established, and for the session manager program to load and initialize.

If all systems are in good working order, the launch progresses through all these stages without hesitation. The amount of time this takes can vary widely based on other activity on the z/OS system, but it should ordinarily be a matter of seconds. To tell if the session manager came up, call DBG_PINGSESSIONMANAGER again. Wait 5 to 30 seconds before making that second call, looking for any value returned in the output parameter XMLREPLY that indicates that the session manager launch was successful and is now up and ready to service debug sessions, as shown in Figure 13.

Figure 13. Ping session manager after running session manager
Value (OUT) for XMLReply is 3C3F786D6C2076

Running the session manager manually on a z/OS system

This article described how to set up the session manager on a z/OS system, defining it as an ordinary network daemon capable of being started by system facilities and capable of being managed at the connected DB2 server by an Optim Development Studio client. This article now describes how to manually run the session manager on a z/OS system for greater flexibility. The process is similar to running the session manager manually anywhere on the network, including on your own workstation.

The session manager is a Java program (db2dbgm.jar), so it can be executed anywhere a suitable Java runtime environment exists. A z/OS system with Java JRE 1.5 is ideal. The example here is based on a z/OS system with DB2 for z/OS V8 installed and a configuration where there is no session manager .jar file already distributed on the z/OS system.

To get started, obtain the following:

  • A copy of the session manager .jar file, db2dbgm.jar. You can use the copy distributed with Optim Development Studio.
  • The path to the Java JRE binaries on the target z/OS system. Use the same value you used in Step 2: Logon to your user ID using telnet to verify the copied session manager .jar file and Java availability. of the started task setup. It should be the same for all users of any given z/OS system. In a production environment, you need to get this directory from the z/OS system administrators.
  • The IP address of the target z/OS system. You can get this by running SYSPROC.DBG_LOOKUPSESSIONMANAGER at the DB2 for z/OS V8 server. Obtaining the IP address this way can also validate that the required Unified Debugger setup on the DB2 V8 server has been performed.
  • An ID with a home directory that can log on to the z/OS UNIX® System Services (USS) environment. The example uses usrt003.
  • A terminal session to log on to the z/OS UNIX System Services environment. The example uses telnet from a workstation command window.

Complete the following steps to run the session manager manually.

Step 1: Use FTP to transfer a binary copy of the session manager .jar file to your home directory

Listing 5 shows the series of FTP commands to copy the db2dbgm.jar file to z/OS.

Listing 5. FTP to transfer db2dbgm.jar to server
Command Prompt - ftp 9.30.113.18
C:\>cd C:\Program Files\IBM\ODS2.2\dsdev\bin

C:\Program Files\IBM\ODS2.2\dsdev\bin>dir
 Volume in drive C is C_Drive
 Volume Serial Number is A6DE-9985

 Directory of C:\Program Files\IBM\ODS2.2\dsdev\bin

09/22/2010  10:10 AM    <DIR>          .
09/22/2010  10:10 AM    <DIR>          ..
05/30/2007  09:43 PM               698 db2dbgm.bat
07/21/2010  12:41 PM            61,346 db2dbgm.jar
09/23/2010  04:53 PM               795 manageRepository.bat
               3 File(s)         62,839 bytes
               2 Dir(s)  33,040,637,952 bytes free

C:\Program Files\IBM\ODS2.2\dsdev\bin>ftp 9.30.113.18
Connected to 9.30.113.18.
220-FTPD1  IBM FTP CS V1R7 at XXXXXXXXXXXXXXX, 21:25:38 on 2010-09-24.
220 Connection will close if idle for more than 5 minutes.
User (9.30.113.18:(none)): usrt003
331 Send password please.
Password:  XXXXXX
230 USRT003 is logged on. Working directory is "USRT003.".
ftp> cd /u/usrt003
250 RFS directory /u/usrt003 is the current working directory.
ftp> binary
200 Representation type is Image
ftp> put db2dbgm.jar
200 Port request OK.
125 Storing data set /u/usrt003/db2dbgm.jar
250 Transfer completed successfully.
ftp: 61346 bytes sent in 0.01Seconds 4089.73Kbytes/sec.
ftp> quit

Step 2: Logon to your user ID using telnet to verify the copied session manager .jar file and Java availability.

  1. Enter telnet <server-ip>. Note that some installations might require a second parameter on the telnet command. Specify the telnet listening port if it is not the default value 23 on the z/OS system.
  2. Enter your user ID and password when prompted.
  3. Change to your home directory, and verify that the session manager .jar file is there.
  4. Enter the command to have Java identify itself, specifying the full directory pathway to the Java JRE along with the fullversion option, as shown in Listing 6.
Listing 6. Telnet to server
Telnet 9.30.113.18
EZYTE27I  login:  usrt003
EZYTE28I  usrt003 Password:  XXXXXXX
IBM
Licensed Material - Property of IBM
5694-A01 (C) Copyright IBM Corp. 1993, 2005
(C) Copyright Mortice Kern Systems, Inc., 1985, 1996.
(C) Copyright Software Development Group, University of Waterloo, 1989.
All Rights Reserved.

U.S. Government users - RESTRICTED RIGHTS - Use, Duplication, or 
Disclosure restricted by GSA-ADP schedule contract with IBM Corp.

IBM is a registered trademark of the IBM Corp.

$ cd /u/usrt003
$ ls -la
total 160
drwxr-xr-x    2 USRT003   SYS1      8192 Sep 24 14:41 .
drwxr-xr-x   29 OMVSKERN  OMVSGRP   8192 Jul  7  2005 ..
-rw-------    1 USRT003   SYS1        25 Sep 24 14:41 .sh_history
-rw-r-----    1 USRT003   SYS1     61346 Sep 24 14:26 db2dbgm.jar
$ /usr/lpp/java150/J5.0/bin/java -fullversion
java full version "J2RE 1.5.0 IBM z/OS build pmz31devifx-20100215 (SR11 FP1 )"
$

Step 3: Manually run the session manager Java program.

While you can run the db2dbgm.jar using one long command, it is easier to see it delivered in several separate commands, as shown in Listing 7.

Listing 7. Running the session manager Java program
export PATH=/usr/lpp/java150/J5.0/bin:$PATH
export CLASSPATH=./db2dbgm.jar
java com.ibm.db2.psmd.mgr.Daemon –port 4554 –timeout 1

The example shows a timeout value of 1 second for the verification step. Normally you would use a larger value, such as 30 seconds (or 0 for infinity) so you can return to Optim Development Studio to debug stored procedures and use the session manager that is already running. As long as you remain logged on to your UNIX® System Services ID, you can run the session manager again if it times out by reentering the Java command. Run the session manager, as shown in Listing 8.

Listing 8. Telnet to server
Telnet 9.30.113.18
EZYTE27I  login:  usrt003
EZYTE28I  usrt003 Password:  XXXXXXX
IBM
Licensed Material - Property of IBM
5694-A01 (C) Copyright IBM Corp. 1993, 2005
(C) Copyright Mortice Kern Systems, Inc., 1985, 1996.
(C) Copyright Software Development Group, University of Waterloo, 1989.
All Rights Reserved.

U.S. Government users - RESTRICTED RIGHTS - Use, Duplication, or 
Disclosure restricted by GSA-ADP schedule contract with IBM Corp.

IBM is a registered trademark of the IBM Corp.

$ cd /u/usrt003
$ ls -la
total 160
drwxr-xr-x    2 USRT003   SYS1      8192 Sep 24 14:41 .
drwxr-xr-x   29 OMVSKERN  OMVSGRP   8192 Jul  7  2005 ..
-rw-------    1 USRT003   SYS1        25 Sep 24 14:41 .sh_history
-rw-r-----    1 USRT003   SYS1     61346 Sep 24 14:26 db2dbgm.jar
$ /usr/lpp/java150/J5.0/bin/java -fullversion
java full version "J2RE 1.5.0 IBM z/OS build pmz31devifx-20100215 (SR11 FP1 )"
$ export PATH=/usr/lpp/java150/J5.0/bin:$PATH
$ export CLASSPATH=./db2dbgm.jar
$
$ java com.ibm.db2.psmd.mgr.Daemon -port 4554 -timeout 1
args[0]: -port
args[1]: 4554
args[2]: -timeout
args[3]: 1
Debug Session Manager started on IP: 9.30.113.118 - port: 4554
Host address: 9.30.113.18

To interrupt or cancel the running session manager, use Ctrl-C. You might need to do this if you entered an infinite time out (-timeout 0) and then need to log off.

Consider writing a shell script to make execution of the session manager from your ID easier. You can use a text editor at your workstation to write the script file content and give it an appropriate file name, such as runsm.sh. Then use FTP to transfer that text file to your z/OS USS home directory.

Listing 9 shows a sample shell script. Be sure to specify the proper path to the Java JRE binaries as they exist on your z/OS system.

Listing 9. Sample shell script (runsm.sh)
#! /bin/sh 
# Script to manually run the Unified Debugger Session Manager
# when located in the current directory
#   Syntax:  
#     . runsm.sh   port  timeout  log 
#   Defaults are: 
#     . runsm.sh   4554  30       /dev/null
# 
# Locate Java on the system from environment variable JAVA_HOME
export JAVA_HOME=${JAVA_HOME:-/usr/lpp/java150/J5.0/bin}
#
# Start with an empty log file, when specified 
if test "${3:-/dev/null}" != "/dev/null"
then if test -f $3
  then if test -w $3
    then echo Removing existing logfile "$3"
         rm -f $3  
    fi
  fi
fi
echo 'Running Unified Debugger Session Manager (use Ctrl-C to cancel)'
date
$JAVA_HOME/java -cp ./db2dbgm.jar com.ibm.db2.psmd.mgr.Daemon \
-port ${1:-4554} -timeout ${2:-30} -log ${3:-/dev/null}
date
# end script

When the session manager is active, return to Optim Development Studio to configure the stored procedure debugger preferences by clicking Window > Preferences. Then expand the Run/Debug menu, and select Routine Debugger, as shown in Figure 14.

Figure 14. Set up debug preferences
Preferences screen with 'Use an already running session manager' selected

Even though you manually ran the session manager on z/OS, because you did it at the same z/OS system where your connected DB2 server is installed, you can use either setting on the stored procedure debugger preferences. Be sure to properly identify the actual port and IP address displayed by your manually started session manager.

Click OK to close the preferences page. You are ready to start debugging.


Gathering a session manager trace for IBM Service

The session manager has a trace capability that IBM Service might ask you to capture to help diagnose problems while debugging stored procedures with the Unified Debugger. The session manager trace file is activated by specifying a file name for the log option when the session manager Java program is executed. The log option requires a file name. In the example, the log option is specified, but with a special file name (/dev/null) that is a placeholder for no real file at all. (You can also remove the log option entirely from the Java command line to prevent any trace file activity. Do not leave the log option on the command line without a filename. Remove both parts.)

To activate the session manager trace for IBM Service, you need to add or change the log option to reference a readable and writeable file on the system. The session manager appends trace records to the log file as long as it is running, so plan your adjustment carefully. You should initiate tracing with a new or relatively empty file, and limit the active trace to only the period of time needed to capture the activity for diagnosis. Thus it might be easiest to gather a session manager trace from a manually started session manager, rather than a session manager running from the formal started task JCL. However, the trace facility can be activated from either venue.


Conclusion

Debugging stored procedures using Optim Development Studio can be done easily with the Unified Debugger technology. The session manager is the central component of the debug technology, so running it on your terms will improve your productivity. You can choose where and how to use the session manager on z/OS with Optim Development Studio.

This article described how to set up and operate the debug session manager on z/OS. Because the example showed you how to launch the session manager using the session manager support routines at the connected DB2 server, users doing stored procedure debugging can use either of the following options listed on the Optim Development Studio Debug preferences:

  • Use the session manager on each connected server. Optim Development Studio discovers the session manager you launched at the connected DB2 server the same way you confirm the successful launch: by using the DBG_PINGSESSIONMANAGER routine.
  • Use the already running session manager. By specifying the host IP address obtained from DBG_LOOKUPSESSIONMANAGER and the port value used with DBG_RUNSESSIONMANAGER, Optim Development Studio uses the session manager you launched yourself, after using DBG_PINGSESSIONMANAGER to confirm that the specified session manager location is responding to communication.

This article also described how to manage the session manager on the z/OS system by writing a shell script that contains the appropriate commands.

Finally, this article described how to specify a log file for session manager trace, in case you need to provide it to IBM Service while troubleshooting.

Acknowledgments

We would like to thank Kathy Zeidenstein, Tina Chen, and other reviewers for their help during review of this article.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=376821
ArticleTitle=Debugging stored procedures on DB2 for z/OS with Optim Development Studio, Part 2: Configure the stored procedure debug session manager on z/OS
publish-date=02242011