Debugging stored procedures on DB2 z/OS with
     Data Studio Developer, Part 2: Configure the
     stored procedure debug...
developerWorks®                                                                           ibm.com/developerWorks



     I...
ibm.com/developerWorks                                                             developerWorks®



     Data Studio Dev...
developerWorks®                                                                           ibm.com/developerWorks



     T...
ibm.com/developerWorks                                                                     developerWorks®



     Figure ...
developerWorks®                                                                           ibm.com/developerWorks



     s...
ibm.com/developerWorks                                                              developerWorks®




     Setting up th...
developerWorks®                                                                           ibm.com/developerWorks



     N...
ibm.com/developerWorks                                                            developerWorks®




       used.
       ...
developerWorks®                                                                           ibm.com/developerWorks




     ...
ibm.com/developerWorks                                                            developerWorks®




               • DBG...
developerWorks®                                                                           ibm.com/developerWorks




     ...
ibm.com/developerWorks                                                              developerWorks®



     to call from D...
developerWorks®                                                                           ibm.com/developerWorks




     ...
ibm.com/developerWorks                                                                developerWorks®



     DBG_RUNSESSI...
developerWorks®                                                                           ibm.com/developerWorks




     ...
ibm.com/developerWorks                                                              developerWorks®




     Getting a zer...
developerWorks®                                                                           ibm.com/developerWorks




     ...
ibm.com/developerWorks                                                               developerWorks®




               • ...
developerWorks®                                                                           ibm.com/developerWorks



     S...
ibm.com/developerWorks                                                              developerWorks®




       export PATH...
developerWorks®                                                                           ibm.com/developerWorks



     w...
ibm.com/developerWorks                                                            developerWorks®




     Even though you...
developerWorks®                                                                           ibm.com/developerWorks




     ...
ibm.com/developerWorks                                                                 developerWorks®



                ...
developerWorks®                                                                           ibm.com/developerWorks




     ...
ibm.com/developerWorks                                                            developerWorks®



     Emily Zhang
    ...
Upcoming SlideShare
Loading in...5
×

Debugging stored procedures on DB2 z/OS with Data Studio ...

2,585

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
2,585
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
18
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Transcript of "Debugging stored procedures on DB2 z/OS with Data Studio ..."

  1. 1. Debugging stored procedures on DB2 z/OS with Data Studio Developer, Part 2: Configure the stored procedure debug session manager on z/OS Skill Level: Intermediate Emily Zhang (emilyz@us.ibm.com) Advisory Software Engineer IBM Tom Miller (millerrt@us.ibm.com) Senior Software Engineer IBM 19 Mar 2009 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. 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 1 of 27
  2. 2. developerWorks® ibm.com/developerWorks 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 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 Configure the stored procedure debug session manager on z/OS Page 2 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  3. 3. ibm.com/developerWorks developerWorks® 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 The Unified Debugger can debug both LANGUAGE SQL and LANGUAGE SQL stored LANGUAGE JAVA stored procedures. procedures. The Unified Debugger session No session manager program is manager program (db2dbgm.jar) distributed on the platform. The is distributed along with the DB2 session manager program can be base feature. copied to this platform from the debug client distribution and run manually. The No support is available for debug DBG_RUNSESSIONMANAGER clients to launch the session support routine is provided manager at the connected server. (requires started task setup of the DB2UDSMD daemon). This is similar to DB2 for Linux, This is similar to DB2 for Linux, UNIX, and Windows® V9 and UNIX, and Windows V8 FP15. DB2 for i V5R4. 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. Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 3 of 27
  4. 4. developerWorks® ibm.com/developerWorks 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 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. Configure the stored procedure debug session manager on z/OS Page 4 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  5. 5. ibm.com/developerWorks developerWorks® Figure 3. 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 5 of 27
  6. 6. developerWorks® ibm.com/developerWorks 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 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. Configure the stored procedure debug session manager on z/OS Page 6 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  7. 7. ibm.com/developerWorks developerWorks® 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 7 of 27
  8. 8. developerWorks® ibm.com/developerWorks 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 Configure the stored procedure debug session manager on z/OS Page 8 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  9. 9. ibm.com/developerWorks developerWorks® 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), Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 9 of 27
  10. 10. developerWorks® ibm.com/developerWorks // 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: Configure the stored procedure debug session manager on z/OS Page 10 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  11. 11. ibm.com/developerWorks developerWorks® • 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 11 of 27
  12. 12. developerWorks® ibm.com/developerWorks 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 Configure the stored procedure debug session manager on z/OS Page 12 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  13. 13. ibm.com/developerWorks developerWorks® 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 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 13 of 27
  14. 14. developerWorks® ibm.com/developerWorks 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 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 Configure the stored procedure debug session manager on z/OS Page 14 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  15. 15. ibm.com/developerWorks developerWorks® 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 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 15 of 27
  16. 16. developerWorks® ibm.com/developerWorks This changes the display as shown in Figure 11. Figure 11. Run session manager result Text mode display 2. 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” Configure the stored procedure debug session manager on z/OS Page 16 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  17. 17. ibm.com/developerWorks developerWorks® 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 17 of 27
  18. 18. developerWorks® ibm.com/developerWorks 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. Configure the stored procedure debug session manager on z/OS Page 18 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  19. 19. ibm.com/developerWorks developerWorks® • 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 19 of 27
  20. 20. developerWorks® ibm.com/developerWorks 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 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: Configure the stored procedure debug session manager on z/OS Page 20 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  21. 21. ibm.com/developerWorks developerWorks® 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 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 Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 21 of 27
  22. 22. developerWorks® ibm.com/developerWorks 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 Configure the stored procedure debug session manager on z/OS Page 22 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  23. 23. ibm.com/developerWorks developerWorks® 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. Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 23 of 27
  24. 24. developerWorks® ibm.com/developerWorks 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 Configure the stored procedure debug session manager on z/OS Page 24 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  25. 25. ibm.com/developerWorks developerWorks® 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. Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 25 of 27
  26. 26. developerWorks® ibm.com/developerWorks Resources Learn • Use an RSS feed to request notification for the upcoming articles in this series. (Find out more about RSS feeds of developerWorks content.) • Refer to the IBM Data Studio product page. • Review Debugging DB2 for z/OS SQL stored procedures with IBM Data Studio Developer, the first article in this series, to understand how debugging works, mostly from the developer point of view. • Take the Tutorial: Get Started with Data Studio Developer (IBM Database Magazine, Q3 2007) for a great overview of Data Studio Developer. • Look for Redbooks: DB2 9 for z/OS Stored Procedures: Through the CALL and Beyond • Learn more about Information Management at the developerWorks Information Management zone. Find technical documentation, how-to articles, education, downloads, product information, and more. • Stay current with developerWorks technical events and webcasts. Get products and technologies • Download Data Studio Developer Trial Version. • Download More Data Studio products. • Build your next development project with IBM trial software, available for download directly from developerWorks. Discuss • Participate in the discussion forum for this content. • Read the Data Studio Forum on developerWorks. • Check out the Data Studio Community Space on developerWorks. • Follow the Data Studio Team Blog on developerWorks. • Learn more from the IBM Unified Debugger Space on developerWorks. • Check out the developerWorks blogs and get involved in the developerWorks community. About the authors Configure the stored procedure debug session manager on z/OS Page 26 of 27 © Copyright IBM Corporation 2009. All rights reserved.
  27. 27. ibm.com/developerWorks developerWorks® 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. Trademarks IBM, developerWorks, DB2, z/OS are trademarks of IBM Corporation in the United States, other countries, or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. Configure the stored procedure debug session manager on z/OS © Copyright IBM Corporation 2009. All rights reserved. Page 27 of 27

×