Debugging an SQL Stored ProcedureVersion 1

���

ii Debugging an SQL Stored Procedure

Contents

Before You Begin. . . . . . . . . . . 1

Step 1: Verify the status of the DB2KEEPDARI keyword . . . . . . . . . 3

Step 1.1: (Optional) Set StoredProcedure Builder .ini variables . . . . 5

Step 2. Create a new Stored ProcedureBuilder project . . . . . . . . . . . . 7

Step 3. Set up the build options . . . . 9

Step 4. Code a sample SQL storedprocedure . . . . . . . . . . . . . 11

Step 5: Build the stored procedure fordebug . . . . . . . . . . . . . . . 15

Step 6: Set and modify line andvariable break points . . . . . . . . 17

Step 7: Run in debug mode. . . . . . 19

Step 8: Revert back to release mode bycompiling in release (non-debug) mode 21

Summary. . . . . . . . . . . . . . 23

Additional information . . . . . . . . 25

iii

iv Debugging an SQL Stored Procedure

Before You Begin

Welcome to the Debugging an SQL stored procedure tutorial. We hope you find ithelpful and enjoyable. Good luck.

Objective:This tutorial’s objective is to guide you through the process of debuggingan SQL stored procedure using the integrated SQL debugger that isprovided with DB2 Stored Procedure Builder. After you have worked yourway through this brief tutorial, you should have the basic understandingrequired to debug your own stored procedures.

Duration:This tutorial should take 30—60 minutes for you to complete.

Prerequisites:You need to have the following prerequisites to complete this tutorial:v Stored Procedure Builderv DB2®for Windows (Other DB2 servers will work, but will require

different C-compilers and options)v Microsoft Visual C++ Version 6.0 (Other C-compilers are also

appropriate. However, the build options specified in this tutorial assumethis version of Microsoft Visual C++. For further information oncompiler options, see DB2 version 7.2 Release Notes, section 34.4.2)

Overview

The RECENTHIRE stored procedure created in this tutorial accesses theSAMPLE database. The stored procedure retrieves an employee’s recordfrom the STAFF table if the employee was hired less than five years ago.

The employee information, including the employee number, first name, lastname, salary, and years employed are returned to the client in the form ofoutput parameters.

This tutorial guides you through the steps required to code, build, debug,and deploy the RECENTHIRE stored procedure. Follow the eight steps inorder because later steps depend on tasks completed in earlier steps.

Conventions used in this tutorialThis tutorial uses typographical conventions in the text to help youdistinguish between the names of controls and text that you type. Forexample:v Menu items are in boldface font:

Click Menu —> Menu choice.v Text that you type is in example font on a new line:

This is the text that you type.

v File or directory names are in example font. Bold italics indicatescustomizable text:

.../ProgramFiles/SQLLIB/spb/projects/example.spp.

1

2 Debugging an SQL Stored Procedure

Step 1: Verify the status of the DB2 KEEPDARI keyword

For stored procedures, the DB2 keyword KEEPDARI has the default value yes.This keeps the stored procedure process alive.

To verify the value of the KEEPDARI keyword:1. Open a DB2 CLP window.2. Type:get dbm cfg.3. Scroll down to the KEEPDARI keyword to verify its setting.4. To update the value of the KEEPDARI keyword, type:update dbm cfg using

KEEPDARI yes. The database must be restarted for this command to take effect.

For more information on the DB2 KEEPDARI keyword, see the Database ManagerConfiguration Parameter Summary in the DB2 Administration Guide.

3

4 Debugging an SQL Stored Procedure

Step 1.1: (Optional) Set Stored Procedure Builder .inivariables

In the Stored Procedure Builder .ini file (db2spb.ini), you can set variables thatwill affect your debugger session. This file is located in .../SQLLIB/spb.

Note: These variables need to be set before you start Stored Procedure Builder. Ifyou change them during a Stored Procedure Builder session, your values will beoverwritten by the session values when you exit Stored Procedure Builder.

Debugger Variables

DEBUGGER_MAX_VAR_REPORT_SIZEThis variable will affect the length of the debugger report. The defaultvalue is 80 characters.

LOG_DEBUGGER_DATA_FLOWDefault for this variable is false. Setting it to true will cause two files tobe generated after your debug session in the .../SQLLIB/DB2 directory:db2psmdr.log and db2psmds.log.

db2psmdr.log shows a list of commands going from the user client to thedebugger.

db2psmds.log shows a list of commands going from the debugger to thefront end of the database.

5

6 Debugging an SQL Stored Procedure

Step 2. Create a new Stored Procedure Builder project

To create a new Stored Procedure Builder project:1. Start Stored Procedure Builder by clicking Start —> Programs —> IBM DB2

—> Stored Procedure Builder.2. In the new project window that opens, define the characteristics of the new

project as shown below.

3. Click OK. The project information appears in the Stored Procedure Builderproject tree.Tip: You can also open a new project by clicking File —> New Project from theStored Procedure Builder main menu.

7

8 Debugging an SQL Stored Procedure

Step 3. Set up the build options

Before you create and build the SQL stored procedure for this tutorial, you canspecify build options that are used for all SQL stored procedures on the DB2instance you are connected to.

To set up the build options:1. Right-click on the Stored Procedures folder in your project tree, and click SQL

Stored Procedure Build Options. A new window opens where you can specifythe build options. The Database Connection window opens (showing yourcurrent connection):

2. In the Compiler Environment field, type:C:\Microsoft Visual Studio\VC98\bin\vcvars32.bat.This should be the fully qualified path to the command file that sets up thecompiler environment variables. This sets the DB2 registry variableDB2_SQLROUTINE_COMPILER_PATH.

3. Keep the default in the Compiler Options field by leaving it blank.Default options are:cl -Ox -W2 /TC -D_X86_=1 -IC:\SQLLIB\include SQLROUTINE_FILENAME.c /link-dll -def:SQLROUTINE_FILENAME.def /out:SQLROUTINE_FILENAME.dllC:\SQLLIB\lib\db2api.lib

9

4. In the Precompiler Options field, type the SQL precompile options that youwant to use for building stored procedures, or leave the field blank to use thedefault options.For information about precompiler options, see the DB2 Command Reference.

5. Keep the default value of 120 seconds in the Debug time-out field. This setsthe timeout number of seconds before stored procedures run to completion ifthere is no user action.

6. Select the Keep files on server check box. This will keep intermediate filescreated during the SQL stored procedure build process on the database server.These files are located in:...SQLLIB\function\routine\sqlproc\database_name\schema_name\.

7. Click OK.

Notes:

v Replace C:\SQLLIB with the actual DB2 server install path.v The above options are the default compile commands if the

DB2_SQLROUTINE_COMPILE_COMMAND is not set. To return to the defaultcompiler options, set the value for the Compiler Command to blank.

v For more command options, refer to the Release Notes (release.txt) in yourDB2 install path.

10 Debugging an SQL Stored Procedure

Step 4. Code a sample SQL stored procedure

To code the RECENTHIRE stored procedure:1. Right-click the Stored Procedures folder in the project tree view.2. Click Insert —> SQL Stored Procedure Using Wizard.

3. On the Name page, type:RecentHire.

11

4. On the Pattern page, keep the default options.5. On the SQL Statement page, create the required SQL query. Click the SQL

Assist push button to use the SQL Assist wizard to graphically generate theSQL statement. The resulting SQL statement looks like this:

6. On the Options page, select Generate Only.

12 Debugging an SQL Stored Procedure

Note: If you select Generate and Build, also select the Enable Debuggingcheckbox. This will allow you to skip Step 5: Building the stored procedure fordebug.

7. Click Finish to generate the stored procedure.8. The stored procedure appears in the project tree.

Step 4. Code a sample SQL stored procedure 13

14 Debugging an SQL Stored Procedure

Step 5: Build the stored procedure for debug

To build the stored procedure for debug:1. Right-click the stored procedure in the project tree view.2. Click Build for Debug.

15

16 Debugging an SQL Stored Procedure

Step 6: Set and modify line and variable break points

In the output area you can modify breakpoints and variables, as well as change theview to see the state at different points on the call stack. The editor window showsyou the current line. Line breakpoints cause execution to pause when the indicatedline is reached. Line breakpoints can be set, modified, or removed by using eitherthe editor window, the breakpoint window on the debug tab, the toolbar, or thedebug menu items.

To set a line break point:1. Place the cursor next to a line in the editor window.2. Double-click to set a line break point at the desired line, click the toolbar icon,

or select Debug —> Add Breakpoint.Note: Line breakpoints are only valid on the first line of a statement.

To enable, disable, or remove a line break point: Click the break point icon in theeditor window, place the cursor at the desired line in the editor window and usethe toolbar icons, or click Debug —> Toggle Breakpoint or Debug —> RemoveBreakpoint.

Tip: All Debug menu items can also be accessed by right-clicking in the editorwindow.

Variable breakpoints cause execution to pause when the indicated variableÆs valuechanges. Variable breakpoints can be set, modified, or removed by using either thevariables or breakpoint window on the debug tab, the toolbar, or the debug menuitems.

Note: Variable breakpoints can only be set or modified while you are in a debugsession.

To set a variable breakpoint: Select the variable in the variable area of the debugtab, and use either the toolbar or the debug menu. Or, you can double-click in thecell next to the variable.

17

18 Debugging an SQL Stored Procedure

Step 7: Run in debug mode

To start your debugging session:1. Select the SQL stored procedure you want to debug.2. Click either the Run in Debug toolbar button icon or Selected —> Run in

Debug.Your debug session will begin. If there are any breakpoints set, execution willpause at the first breakpoint. If there are no breakpoints set, execution will stopat the first line.Note: You can also start the debugging session by invoking a Step Intocommand. This will start your debugging session and pause execution at thefirst line. Select Debug —> Step Into, or click the toolbar icon.

Toolbar and menu items allow you to control the execution of your debuggingsession. You can pause your session, continue execution or run to completion,ignoring all breakpoints. You can control the flow by selecting a variety of ways tostep through your code including, Step Into, Step Over, Step Out, Step Return,and Step to Cursor. These commands can be invoked through the Debug menu orfrom the toolbar.

Stepping Commands

Step Into/Step OverIf there are no call statements in the stored procedure, these twocommands both step to the next line in the code. If there is a call statementin the stored procedure, Step Into steps to the first line in the nested call,and Step Over steps to the first line after the call statement in the mainprocedure.

Step ReturnIf you are in a nested call, this command will step back to the linefollowing the nested call in the main procedure. If you are not in a nestedcall, this command will take you out of the session.

Step to CursorThis command will take you to the line where the cursor is placed. Thisallows you to stop execution at a particular line without setting a linebreakpoint.

To run your debug session to completion ignoring breakpoints: click Selected —>Run to Completion, or click the toolbar icon.

To pause your debug session: click Selected —> Pause Debug, or click the toolbaricon.

19

20 Debugging an SQL Stored Procedure

Step 8: Revert back to release mode by compiling in release(non-debug) mode

To revert back to release mode:1. Select the stored procedure in the project tree view.2. Click either the Build toolbar button icon or Selected —> Build.

3. Click either the Run toolbar button icon, or Selected —> Run.

21

22 Debugging an SQL Stored Procedure

Summary

Congratulations! You have finished the tutorial.

By going through this tutorial you completed the following tasks:v You verified and updated the status of the DB2 KEEPDARI keyword and Stored

Procedure Builder .ini variables.v You created a new Stored Procedure Builder project, set up build options, and

coded a sample SQL stored procedure.v You built the stored procedure for debug and ran the stored procedure in debug

mode, setting and modifying line and variable breakpoints.v You reverted back to release mode by compiling in release (non-debug) mode.

23

24 Debugging an SQL Stored Procedure

Additional information

The following resources can provide more information on this topic:v DB2 SQL Reference

(ftp://ftp.software.ibm.com/ps/products/db2/info/vr7/html/db2s0/frame3.htm#index)v DB2 Application Development Guide

(ftp://ftp.software.ibm.com/ps/products/db2/info/vr7/html/db2a0/frame3.htm#index)v DB2 Application Building Guide

(ftp://ftp.software.ibm.com/ps/products/db2/info/vr7/html/db2ax/frame3.htm#index)v DB2 Command Reference

(ftp://ftp.software.ibm.com/ps/products/db2/info/vr7/html/db2n0/frame3.htm#index)v DB2 Integrated Development Tools Website

(http://gwareview.software.ibm.com/software/data/db2/udb/ide/)v Application development with DB2 Universal Database (http://www-

4.ibm.com/software/data/db2/udb/ad/index.html)v DB2 Stored Procedure Builder Online Help

25