Skip to main content

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

Emily Zhang (emilyz@us.ibm.com), Advisory Software Engineer, IBM
Emily Zhang
Emily 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 Miller
Tom 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.

Summary:  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 Data Studio Developer to debug stored procedures on DB2® for z/OS servers.

View more content in this series

Date:  19 Mar 2009
Level:  Intermediate PDF:  A4 and Letter (1376KB | 27 pages)Get Adobe® Reader®
Activity:  2025 views
Comments:  

Introduction

This article follows the previous article on using the stored procedure debugger from Data Studio Developer. 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.

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

Learning about the Unified Debugger session manager

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


Figure 1. Unified Debugger framework
Unified Debugger framework

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 the previous article.

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 Data Studio Developer. 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 Data Studio Developer can be impacted, requiring additional manual intervention.

Understanding session manager capability and availability on DB2 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 V9 for z/OS DB2 z/OS v8 (with PTF UK25860 applied)
The Unified Debugger can debug both LANGUAGE SQL and LANGUAGE JAVA stored procedures.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 Data Studio Developer

The previous article went into detail about debugging stored procedures. Here is 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. 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 if the stored procedure is enabled for debugging, right-click on the stored procedure. The debug menu is available as an option, as shown in Figure 2.


Figure 2. Procedure with debug enabled
Procedure with debug enabled

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 check box on the Routine Options page as shown in Figure 3.


Figure 3. Deploy Routines wizard
Deploy Routines wizard

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

After you deploy for debugging, configure the DB2 Stored Procedure Debugger preferences to set up debugger-related preferences, including the location of the session manager to use for debug sessions. To show the preferences page, select Window > Preferences from the top menu bar, then expand Run/Debug and select DB2 Stored Procedure Debugger.

One important point

If you plan to debug LANGUAGE JAVA stored procedures on a DB2 V9 server, you should 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.

If you select the checkbox for Run the session manager on each connected server, Data Studio Developer looks for a session manager running at the connected server, and if one is not found, it requests a session manager to be run at that location (DB2 V9 for z/OS only). Alternatively, you can manually run a session manager somewhere and identify that location under the Use already running session manager section.


Figure 4. Debugger preference page
Debugger preference page.

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 Data Studio Developer 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 by 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 to 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 UID 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.

In Listing 2 shows the full content 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 good 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 Data Studio Developer. 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
DBG procedures under SYSPROC schema in Database Explorer

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 Data Studio Developer. It requires no inputs, 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. This is 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

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

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
Unsuccessful ping of a session manager

An unsuccessful ping means that either no session manager is running at that IP 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

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
Run session manager result

This changes the display as shown in Figure 11.


Figure 11. Run session manager result Text mode display
Run session manager result Text mode display
  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”
Run session manager result Text mode display rc=”0”

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 it is now up and ready to service debug sessions, as shown in Figure 13.


Figure 13. Ping session manager after running session manager
Ping session manager after running session manager

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 a Data Studio Developer client. For greater flexibility, you will now see how to manually run the session manager on a z/OS system. It 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, a configuration where there is no session manager .jar file already distributed on the z/OS system.

To get started, gather the following things:

  • A copy of the session manager .jar file, db2dbgm.jar. You can use the copy distributed with Data Studio Developer.

  • The path to the Java JRE binaries on the target z/OS system. Use the same value you used in Step 2 of the started task setup. It should be the same for all users of any given z/OS system. Ultimately, 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 V8 DB2 server has been performed.

  • Have 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

Figure 14 shows the series of FTP commands to copy the db2dbgm.jar file to z/OS.


Figure 14. FTP to transfer db2dbgm.jar to server
FTP to transfer db2dbgm.jar to server

Step 2: Using telnet, logon to your user ID 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 Figure 15.

Figure 15. Telnet to server
Telnet to server

Step 3: Manually run the session manager Java program.

You can run db2dbgm.jar by issuing one long command. It is probably more familiar to see into delivered in several separate commands, as shown here:

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 Data Studio Developer 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.


Figure 16. Telnet run session manager
Telnet run session manager

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 wish to log off.

Consider writing a shell script to make execution of the session manager from your ID easier. You can approach this easily by using a text editor at your workstation to write the script file content and giving 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 5 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 5. 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 Data Studio Developer to configure the stored procedure debugger preferences by clicking Window > Preferences. Then expand the Run/Debug menu, and select DB2 Stored Procedure Debugger, as shown in Figure 17.


Figure 17. Set up debug preferences
Set up debug preferences

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. Just 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.


Summary

Debugging stored procedures using Data Studio Developer 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 Data Studio Developer.

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 yourself using the session manager support routines at the connected DB2 server, people doing stored procedure debugging can use either of the following options listed on the Data Studio Developer Debug preferences:

  • Run the session manager on each connected server. Data Studio Developer 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 here the host IP address obtained from DBG_LOOKUPSESSIONMANAGER and the port value used with DBG_RUNSESSIONMANAGER, Data Studio Developer 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 yourself 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 working with you on a problem.

Acknowledgments

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


Resources

Learn

Get products and technologies

Discuss

About the authors

Emily Zhang

Emily 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

Tom 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.

Comments



Trademarks  |  My developerWorks terms and conditions

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=376821
ArticleTitle=Debugging stored procedures on DB2 z/OS with Data Studio Developer, Part 2: Configure the stored procedure debug session manager on z/OS
publish-date=03192009
author1-email=emilyz@us.ibm.com
author1-email-cc=
author2-email=millerrt@us.ibm.com
author2-email-cc=

My developerWorks community

Tags

Help
Use the search field to find all types of content in My developerWorks with that tag.

Use the slider bar to see more or fewer tags.

Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).

My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).

Use the search field to find all types of content in My developerWorks with that tag. Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere). My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).

Special offers