Information Management
© 2003 IBM Corporation
Developing DB2 stored procedures using Developer Workbench
Marichu ScanlonIBM Silicon Valley LabSan Jose, CA, [email protected]
Information Management
© 2003 IBM Corporation2
Agenda
Overview
Basic Eclipse concepts
DWB concepts
SQL tools
Stored procedure and UDF development
Ad-hoc database development
SQLJ development
Advanced Topics
Information Management
© 2003 IBM Corporation3
IBM Developer Workbench (DWB)
Data application development tool– User-defined functions– Stored procedures– SQL scripts– Develop, deploy, test, debug
Integration tool– Data objects with Java applications
Eclipse based– Common team support interface– Common user experience model
Runs on Windows or Linux workstations Connects to DB2 UDB for z/OS
– Works also with DB2 UDB for iSeries and LUW, as well as Derby – Connect to DB2 for z/OS V9 currently in Beta
Information Management
© 2003 IBM Corporation4
Activities and benefits of DWB
Builds, parses and runs SQL statements
Visually explains execution of SQL statements
Guides developing of stored procedures and user defined functions
Deploys stored procedures and user defined functions
Provides a single debugger for SQL and Java SPs
Helps keep track of history
Information Management
© 2003 IBM Corporation5
Activities and benefits of DWB
Increases code reuse
– Access supporting Java jars during development
Makes development of SQLJ applications easier
Creates modules for binary deployment
Supports runtime binding of package variations for stored procedures
Helps working with XML
Maps XML schemas (XSD) to relational schemas
Information Management
© 2003 IBM Corporation6
Eclipse
A consortium of companies developing open source development platforms
– Initiated by IBM
– Currently most successful open source project by number of contributing participants
The major delivery is the Eclipse Integrated Development Environment (IDE)
– Defines extensibility interfaces and integration points
– Several specialized projects extend the basic IDE (Web Tools Project – WTP, Data Tools Project – DTP)
Information Management
© 2003 IBM Corporation7
Eclipse concepts
Workspace
– The space to save all user metadata – scripts, XSD, configuration
– Implemented by root directory on the filesystem
– Can not be nested
– Can be shared
– User works in exactly one workspace at a certain point of time
– Set when starting the environment
Information Management
© 2003 IBM Corporation8
Eclipse concepts
Project– A logical storage concept used to store related user metadata
– Assigned to one workspace
– Implemented as a directory in a workspace
– Can be shared
– User can work in any number of projects at the same time
– Can be dynamically opened and closed
View– A visual tool providing defined functionality that can be placed
on the user interface
– Examples are: property view, error log view, data output view, project explorer
Information Management
© 2003 IBM Corporation9
Eclipse concepts
Editor
– A visual tool assigned to a specific type of element (SQL script, project, XSD) able to modify the element
Perspective
– Saved configuration of views, editors, and menus typically used to realize specific activities (for example SQLJ development)
– One perspective is active
– Any number of perspectives can be defined
– User can change perspectives
Information Management
© 2003 IBM Corporation10
Most important Eclipse concepts
Database view
Project view
Editor
Properties view
Perspec-tive
Output view
Information Management
© 2003 IBM Corporation11
DWB concepts
Data Project Explorer view
– Displays projects and is starting point for development features
– Development objects are saved independently of the database
– Deployment and execution assigned with the database
Database Explorer view
– Defines Connections to databases using JDBC interface
– Ad-hoc features for stored procedures, user defined functions and SQL
Information Management
© 2003 IBM Corporation12
DWB concepts
Data output view
– Reporting of execution related activities and results
Data perspective
– Tools for development of SQL applications
– Default perspective
Java perspective
– Tools for development of SQLJ applications
Note: to change perspectives, click on
– Window > Open Perspective
Information Management
© 2003 IBM Corporation13
Database connection
Defined in the Database Explorer
– Type of the database
– Server address
– Port
– JDBC driver
Context dependent start of ad-hoc functions
Database explorer is “reverse-engineered” catalog of objects saved in databases
– Filtering of objects available
Information Management
© 2003 IBM Corporation14
Data Development Project
Assigned to database connection
– Capabilities dependent on the type of the database
Functions dependent on objects being manipulated
Logical folders for object types
– SQL scripts
– Stored Procedures
– User-Defined Functions
– XML Schema Documents (XSD)
Contains objects being developed
– Everything created in the database explorer must be saved in a project
Information Management
© 2003 IBM Corporation15
SQL Tools
SQL builder
– User interface to visually build and edit SQL-DML statements
– Syntax and some semantic validation (e.g. table/column resolution, correlation ids)
– Possibility to omit specified schema from generated SQL for portability
– Launch Visual Explain and Actual Costing (z/OS)
– Keyword highlighting and content assist
Information Management
© 2003 IBM Corporation16
SQL Tools
SQL editor
– Supports multiple statements with configurable statement terminator
– Supports execution of any valid SQL statement
– Keyword highlighting and content assist
SQL wizard– Launched from or embedded within other wizards to assist
with SQL creation
Information Management
© 2003 IBM Corporation17
SQL builder Guided statement creation
Three pane editor
– SQL statement
– Graphical description
– Statement options
You can parse and save SQL statements in your project for re-use or further development
You can execute the SQL statement and view the results in the Data Output View
Information Management
© 2003 IBM Corporation18
SQL editor
Edit any SQL statement
Execute the content of the editor (even without saving)
Format SQL
Content tip
Content assist
Information Management
© 2003 IBM Corporation19
Stored procedure and UDF development
Display existing routines from a database server
Create a new DB2 or Derby routine via a wizard
Import a routine source file or copy an existing procedure into the development project
Edit the procedure source and properties with the routine editor
Information Management
© 2003 IBM Corporation20
Stored procedure and UDF development
Build and deploy the procedure to a database
Export procedures for IDE independent batch deployment
Run a routine
Debug stored procedures (SQL and Java for DB2, Java for Derby)
Drag and drop routines from a database connection to the project
Information Management
© 2003 IBM Corporation21
Creating stored procedure or UDF
The New action launches a multi-page wizard that allows you to customize the generated stored procedure
The first page allows the selection of the language: Java using JDBC, Java using SQLJ and SQL
Information Management
© 2003 IBM Corporation22
Creating stored procedure and UDF
The SQL page of the wizard allows you to import existing SQL statements, write your own with the SQL wizard or manually type or paste it in
Information Management
© 2003 IBM Corporation23
Store procedure and UDF – actual cost
Actual cost of running the SQL statement can be invoked from the SQL Statement page of the create procedure wizard. Only available for projects connected to a DB2 z/OS
Information Management
© 2003 IBM Corporation24
Stored procedure and UDF – visual explain
You can invoke Visual Explain for the given SQL statement from within the wizard. You can also invoke it from within the routine editor for SQL routines.
Visual Explain is available for DB2 z/OS V8 (windows clients) and DB2 LUW.
Information Management
© 2003 IBM Corporation25
Stored procedure and UDF – import
The import action launches a multi-page wizard that allows you to create a stored procedure or UDF by importing a routine source file or by selecting an existing routine from another project .
In a source file with multiple routines, only one routine can be imported at a time
Information Management
© 2003 IBM Corporation26
Stored procedure and UDF – editor and actions
Routine editor supports both the project and Database Explorer
Actions available on a stored procedure in your project
Results of execution displayed in the Data Output view
Information Management
© 2003 IBM Corporation27
Stored procedure and UDF – deployment, execution Develop on one database, deploy it
to a different database server (e.g. develop on DB2 LUW and deploy to DB2 z/OS)
Specify the schema qualifier during deploy
The Run action executes a call of the stored procedure
Run asks for input parameter values
Information Management
© 2003 IBM Corporation28
Stored procedure and UDF – export and deploy
Export to file system
– Generates DB2 script file, for Java an ANT script and a properties file for customization
– Allows deployment of the stored procedure independent of the IDE
Batch Deploy for Java and external SQL SPs
– Properties file for customized settings
• Target database, username and password, procedure options like WLM environment
• To deploy run from command prompt: ant -buildfile [filename].xml
Batch deploy for native SQL routines on z/OS V9 or SQL routintes on LUW
– Customize the DB2 script file directly
Information Management
© 2003 IBM Corporation30
SQLJ database development functions New SQLJ File Wizard
– Generates code based on IBM or user customized templates
SQLJ Editor
– SQLJ clause highlighting
– Syntax errors within SQLJ statements and Java code are flagged in the editor and task view
– Code assist for Java statement
– Wizards provided to insert new SQLJ clauses
SQLJ translation
Information Management
© 2003 IBM Corporation31
SQLJ database development functions
Customize/Bind of SQLJ Profiles
– Generates Ant scripts to customize SQLJ profiles and bind packages to the target database
Debugging
– Supports using the .sqlj file as the source file during debugging
Information Management
© 2003 IBM Corporation32
Stored Procedure and UDF development tooling: Language and Server Support
Stored Procedures User Defined Functions
DB2 zOS V7 – V9 Java (JDBC and SQLJ) and SQL
Not supported before v8 new-function mode; no table UDFs
DB2 iSeries: V5R1,V5R2 - V5R3 -
SQLJava (JDBC and SQLJ) and SQL
Not supported
DB2 LUW V8 – V9 Java (JDBC and SQLJ) and SQL
SQL (scalar and table), special table UDFs (MQSeries)
Derby (IBM Cloudscape)
Java Not supported
Information Management
© 2003 IBM Corporation33
SQL Tools
Database Server
SQL builder Any database that DWB supports
SQL editor Any database that DWB supports
Information Management
© 2003 IBM Corporation34
Stored Procedure/UDF tooling and SQL statements: Special Features Support
Special Feature Database Server
Visual Explain DB2 LUW and DB2 z/OS (Client Windows platform)
Statement Cost from routine wizard
DB2 z/OS
Routine debugging Java and SQL procedures for DB2 v9 and
Java procedure for Derby (IBM Cloudscape)
Routine development tooling in Data Development Project
DB2 (LUW, iSeries, z/OS) and Derby (IBM Cloudscape)
Information Management
© 2003 IBM Corporation35
SQLJ Tooling
Database Server
SQLJ translation Any supported DWB database given a valid sqlj.jar for the target database.
SQL customization DB2 v8 and v9 for z/OS and LUW, V5 for iSeries
Information Management
© 2003 IBM Corporation
Additional Features for DB2 for z/OSin Developer Workbench
Marichu ScanlonIBM Silicon Valley LabSan Jose, CA, [email protected]
Information Management
© 2003 IBM Corporation37
Agenda
V8 and V9:
– Enhanced deploy functions for stored procedures
– Package variation for SQL and SQLJ stored procedures
– Unified Debugger for SQL and Java stored procedures
V9 only:
– Native SQL stored procedures
– Multiple jar support for Java stored procedures
– XML Support
V8 only
– DC Project Migration
Information Management
© 2003 IBM Corporation38
Enhanced deploy functions in DWB
Deploy SQL and Java stored procedures to unlike servers
– DB2 for LUW to DB2 for iSeries
– DB2 for LUW to DB2 for z/OS
– DB2 Cloudscape (Java only) to DB2 LUW
Deploy DB2 for LUW, iSeries and z/OS Java stored procedures from an exported file using ant script
Deploy DB2 for z/OS SQL Stored Procedures from an exported file using ant script
Binary Deploy of DB2 for LUW and DB2 for z/OS stored procedures to a like server
– Optionally copy the source as well
Information Management
© 2003 IBM Corporation39
Deploy Wizard external changes
User needs to enter the target dataset for the load module
Specify “Deploy usingbinaries if available in the database”
Information Management
© 2003 IBM Corporation40
Binary Deploy of DB2 for z/OS stored procedures
Requirements / Restrictions
– External SQL stored procedures• Need to customize z/OS enablement stored procedure job, DSNTIJCC• Setup authorization for z/OS enablement stored procedures• Target load library needs to be preallocated
– Java stored procedures• Connect to target z/OS server with IBM DB2 Universal Driver• Cannot binary deploy Java stored procedures originally built using
DSNTJSPP
– Native SQL stored procedures• Only the following bind options are valid for binary deploy of native SQL
stored procedures– target COLLECTION ID– QUALIFIER – OWNER
Information Management
© 2003 IBM Corporation41
Package Variation - overview
Create variations of packages with different bind options for SQL and SQLJ java stored procedures on a DB2 z/OS system.
Display the packages under the Package folder in the Database Explorer.
Allow users to select the package of their choice before executing the stored procedure using Collection ID field in Run Settings Options panel.
Allow users to view the properties of these packages in the Properties View.
Allow users to drop these packages from the Database Explorer.
Available from the Database Explorer as packages are associated only with the DB2 server.
Information Management
© 2003 IBM Corporation42
Package Variation Usage
Initially deploy a SQL or SQLJ stored procedure on a DB2 z/OS server using NO COLLID option– Allows the user to select the collid at
runtime.
Bind the collid you want the new package to reside in using com.ibm.db2.jcc.DB2Binder, otherwise will get -805 at execution time.
In Database Explorer, create new package variation– Right-click on Stored Procedure ->
Packages -> New
Specify bind options for Bind Copy in the Package Variations wizard.
Click Finish to deploy the new package to the server.
Information Management
© 2003 IBM Corporation43
Package Variation – executing the stored procedure
Select another collection id
– Right-click on Stored procedure > Run Settings > Options tab > Collection ID > Browse button
Displays list of collection Ids associated with this package.
Right-click on Stored procedure > Run to execute this package.
Information Management
© 2003 IBM Corporation44
Package Variation - properties
Select specific package from the Database Explorer
Select Package tab to view the properties in the Properties View
Information Management
© 2003 IBM Corporation45
Native SQL Stored Procedures
DB2 for z/OS V9 now supports 2 kinds of SQL SPs:
– External or Generated-C SQL stored Procedure
• User specifies FENCED or EXTERNAL keywords in the Create Procedure DDL
– Native SQL stored procedure
Features of Native SQL stored procedures:
– Ability to version a stored procedure
– Ability to “activate” a particular version of a stored procedure
Information Management
© 2003 IBM Corporation46
Native SQL stored procedures - Versioning
SAME schema, procedure name, number of parameters, and parameter type
Allows difference in procedure body, parameter names and options
Only one version is ACTIVE
– When routine is first created, the initial version is activated
– “Activate” a version by right-click on stored procedure > Set Active
Create additional versions from the Database Project Explorer only
– Right-click on specific stored procedure > Add Version
Information Management
© 2003 IBM Corporation47
Create new Native SQL SP
Create using the Create SP wizard
– Right-click on Stored Procedure > New
DWB Version default = VERSION1
Versions show in same level as the first version in the Data Project Explorer
Information Management
© 2003 IBM Corporation48
Adding a Version
To create a new version of a SP: Right-click on SP > New Version
Versions must have the same SP name and number of parameters and parameter types
– Can change some parm attribute, e.g. VARCHAR(20) to VARCHAR(200)
Body of the procedure can be changed
Procedure options can be changed (e.g. ISOLATION CS to ISOLATION RR)
Can set ALLOW and DISALLOW debug
Information Management
© 2003 IBM Corporation49
Native SQL SP – Procedure options
WLM environment can be specified only when “Enable for debugging” is checked
– Click “Advanced” button
Procedure options specified in the Create Procedure DDL
Collection ID is initially set to schema; specify different collection id in PACKAGE bind option
Build owner set through CURRENT SQLID field in project properties
Information Management
© 2003 IBM Corporation50
Native SQL SP – Migration / Fallback issues
When DB2 for z/OS server migrates to V9 new function mode
– External stored procedures without FENCED or EXTERNAL1
keywords can be “converted” to native SQL stored procedures by redeploying the routine. DB2 assigns a version of V1.
When DB2 for z/OS server re-enters V9 compatibility mode
– Disallow changes to native SQL stored procedures
– Allow Run capabilities only
– Disallow drag and drop of native sql stored procedures to a project associated with a connection in compatibility mode.
Information Management
© 2003 IBM Corporation51
Multiple Jar Support
Allows users to reference classes in other jar files installed in the server
Exploits the SQLJ.ALTER_JAVA_PATH function
– Java stored procedures can reference classes that are neither in the CLASSPATH of the associated Java stored procedure WLM proc, OR in the jar that the stored procedure resides in.
Ability to associate an installed jar file with a Java path
Information Management
© 2003 IBM Corporation52
Multiple Jar Support – Database Explorer View / browse all jars installed on the server
View jars that are dependent on a particular jar
Drop supporting jars
– A “supporting jar” is a jar that will be referenced by another jar at runtime.
Drag and drop/paste a supporting jar from the Database Explorer to a Database Development project for use by one or more routines
View the catalog data and Java path in the Property Browser for each jar
Information Management
© 2003 IBM Corporation54
Multiple Jar Support - Data Project Explorer
Add supporting jars to a stored procedure via:
– Import Wizard - imports a jar from the file system • This creates a Jar node in the Stored Procedure folder
– Drag and drop from Database Explorer
Deploy one or multiple supporting jars to the server using the Deploy Jar wizard.
Ability to drop or replace the jar if already installed in the server; or to exit deployment.
Edit the supporting jar characteristics, such as Java path during deploy.
Deploy Java stored procedure and all its supporting jars into the same jar file
Information Management
© 2003 IBM Corporation55
DB2 Unified Debugger
Development Center v8.2 had SQL Debugger for debugging DB2 for z/OS external SQL stored procedures; no support for debugging Java stored procedures.
DB2 9 One debugger for multiple platforms. Shipped with:
– DB2 for LUW V9
– DB2 for zSeries V8 and V9, and
– DB2 for iSeries V5R4
DWB is the client front end that:
– allows users to remotely debug server side SQL and Java stored procedures.
– allows users to perform source-level debugging using the Debug Perspective
Information Management
© 2003 IBM Corporation56
DB2 for z/OS V9 Unified Debugger Features
Stand alone mode support– Debugging a single a SQL/Java procedure
– Debugging a nested SQL/Java procedures
Cross-language application support– Nested SQL/Java procedures
– C#/VB application calling SQL procedures
Cross-platform support– DB2 for z/OS v8/v9, DB2 for LUW v8/v9, DB2 for iSeries v5r4
Client or Server-side Session Manager
– for .Net, Session Manager is only on Server
Information Management
© 2003 IBM Corporation57
DB2 Unified Debugger features
For V9, supports debugging a specific version of a native SQL stored procedure
CREATE / ALTER options
– Specify DISALLOW / ALLOW / DISABLE DEBUG MODE
– WLM ENVIRONMENT FOR DEBUG (for Native PSM)
New column in SYSIBM.SYSROUTINES: DEBUG_MODE
Session Manager can be on the client or server.
– If on the client, user can point to any z/OS system to debug.
Information Management
© 2003 IBM Corporation58
Unified Debugger - Preferences
Select where Session Manager will be launched
Session Manager on DB2 V9 for LUW can be started when DB2 starts
– Need to setup port in the services file
WLM Environment to be used by the stored procedure when debugging can be specified in the Preferences >
Session Manager on DB2 for z/OS started by issuing console command:
– START DB2UDSMD
Information Management
© 2003 IBM Corporation59
Unified Debugger – Debug Perspective
DWB leverages the Debug Perspective of Eclipse
Has all of standard debug views (source code, variables, call stack, and break points)
Supports all standard debug commands (step into, step over, set break point, update variable…)
Information Management
© 2003 IBM Corporation60
Unified Debugger – Debug Perspective
variables
source
Debug commands
Information Management
© 2003 IBM Corporation62
Query building – specifying representative documents for the XML Query builder
Information Management
© 2003 IBM Corporation63
Query building – XML Query builder – associating documents with XML columns to query against
Information Management
© 2003 IBM Corporation65
Query building – stepping into and out of resources in the XML Query builder
Information Management
© 2003 IBM Corporation68
Migrating a Development Center Project to DWB
Reuse projects created in DC; continue work in DWB
Existing projects can exploit DWB functions
Migrate projects using the Migrate DC Project wizard
Wizard allows creating new connections if an existing connection is not found
Information Management
© 2003 IBM Corporation69
Migrate DC Project wizard
Input DC project must be a .dcp file
Point to the .dcp file using a File Browser
Once project is loaded, all DC project connections are shown
– DC projects allowed multiple connections; DWB projects only have one
DWB will attempt to match the selected connection to existing connections in the Database Explorer.
Information Management
© 2003 IBM Corporation70
References IBM Redbook, “DB2 for z/OS Stored Procedures: Through the
Call and Beyond”, SG24-7083-00
– http://publib-b.boulder.ibm.com/abstracts/sg247083.html?Open
“Build once, deploy everywhere: Binary deploy of DB2 for z/OS stored procedures”;
– http://www-128.ibm.com/developerworks/db2/library/techarticle/dm-0607scanlon/index.html
“Create package variations for z/OS DB2 stored procedures”
– http://www-128.ibm.com/developerworks/db2/library/techarticle/dm-0608parmeshwar.html
Information Management
© 2003 IBM Corporation71
References
“DB2 Developer Workbench, Part 1: Developer Workbench concepts and basic tasks”;
– http://www-128.ibm.com/developerworks/edu/dm-dw-dm-0608eaton-i.html
“DB2 Developer Workbench, Part 2: Developer Workbench and stored procedures”;
– http://www-128.ibm.com/developerworks/edu/dm-dw-dm-0609eaton-i.html
“DB2 Developer Workbench, Part 3: Developer Workbench and XML”;
– http://www-128.ibm.com/developerworks/edu/dm-dw-dm-0610eaton-i.html