Java Stored Procedures in DB2

for OS/390

Open, Portable Application Logic

Julian StuhlerDB2/CICS/IMS GUIDEMay 2000

Topics Introduction Java Stored Procedures – An

OverviewEnvironment Set-upDeveloping & Testing JSPsUsage ConsiderationsSummary

Introduction

IntroductionDB2 consultant with Triton

Consulting, based in the UK14 years DB2 experience

Database Administration Systems Programming Application Development

IBM Gold ConsultantRedbook – DB2 Network

Computing Enhancements & Java Stored Procedures

JSPs – An Overview

What’s a Stored Procedure?

A program or routine executed by the database server in response to an SQL CALL statement issued by a client

Can receive and return parameters from / to calling client

Can enhance performance by replacing multiple SQL client calls

Can promote code re-use and consistency

Can improve security

Supported Languages

Can be written in a wide variety of languages Cobol C/C++ Assembler PL/1 REXX*

PSM*

Java*

* Needs additional APAR support for V5 and V6

Java Stored Procedures

Prerequisites OS/390 Unix System Services (USS) OS/390 Recoverable Resource Services

(RRS) and Workload Manager (WLM) DB2 For OS/390 V5 or V6 (with

necessary additional APARs) Enterprise Toolkit for OS/390 (part of

VisualAge for Java)Features

Open and fully portable code High Performance Java support JDBC (dynamic) and SQLJ (static)

support

High Performance Java

HPJ compiler (part of ET/390) compiles Java into standard OS/390 machine code

Advantages Very high performance Retain code portability Allows WLM-managed stored procedures

address space to run Java SPs without JVM support

Disadvantages More complex program preparation

process

Java TerminologyClass

Equivalent to a module in traditional programming

Method Equivalent to an entry point in

traditional programmingPackage

A collection of related Java classes, “packaged” as a single unit

Not to be confused with a DB2 package!

Environment Overview

OS/390

USS

SourceCode

Links

SerialisedProfiles

WLM

ExecutingSP

DBRMLibrary

LoadLibrary

Runtime Environment

PROCEDURE RUNOPTS WLM_ENV ...

ADD_CUSTOMER ACMESOS/Add_customer.add_customer WLMJAVA

ProgramPreparation

Process

...CALL ADD_CUSTOMER (FIRSTNAME, ....)...

Client

SYSPROCEDURES (V5)

SYSROUTINES (V6)

JAVAENVDataset

1

2

USS Directory

ACMESOSPDSE Link

3

WLMJAVASP WLM Address Space

ADD_CUSTOMER5

via STEPLIB

via JAVAENV DD

ACMESOS4

HPJ load modulePDSE dataset

Via collection

bound in

client's plan

ACMESOS1 ACMESOS2 ACMESOS3 ACMESOS4

DB2 Packages

ACMESOS/Add_customer.sqlj

SQLJ Source

NAME SPECIFICNAME WLM_ENV ...

ADD_CUSTOMER ACMESOS/Add_customer.add_customer WLMJAVA

via CLASSPATH

via PDSE link 6

Environment Set-Up

Environment Set-UpComplex environmentPlenty of pre-requisites

OS/390 DB2

Allow plenty of time to install all pre-requisites and get sample applications working

Good communications needed between DB2 and USS systems support staff

Set-Up Tasks - 1Design library naming standards

USS High Performance Java (HPJ) libraries SQLJ/JDBC libraries Links directory Serialised profiles directory

OS/390 HPJ SQLJ load library Application stored procedure load library JAVAENV dataset DBRM library

Set-Up Tasks - 2Create .profile script

Probably subsystem-specificSet up new WLM environment for

JSPs Needs RRS enabled

Create HPJ versions of JDBC/SQLJ drivers

Create JAVAENV datasetTailor SQLJ properties and cursor

files, if necessary

Developing & Testing

CodingMost standard Java constructs can

be usedSpecial code needed for null

handling E.g. to pass null input parameter from

JDBC client to a stored procedureSpecific code to handle SQLJ

iterators and result setsRefer to SC26-9018, Application

Programming Guide and Reference for Java

Program Prep - JDBC

Can run on any JDKplatform

Run on S/390 platform

prog.JAVA

Source

Java Compiler (JAVAC) prog.CLASS

JavaBytecode

JAR

Other CLASS files

.JAR file

Optional Step

DB2 Catalog

HPJ Compiler

JLL in PDSE

ExternalLink

1

3

2

4

CREATE PROCEDURE

orINSERT into

SYSPROCEDURES

Program Prep - SQLJ

SQLJ Translatorprog.SQLJ

SQLJSource

prog.JAVA

prog_SJProfile0.ser

ModfiedSource

Java Compiler (JAVAC) prog.CLASS

JavaBytecode

JAR

Other CLASS files

.JAR file

Optional Step

Profile Customiser

(DB2PROFC)

DB2 BIND PACKAGE

DB2 Catalog

HPJ Compiler

JLL in PDSE

ExternalLink

Can run on any JDKplatform

Run on S/390 platform

1

3

2

4

5

6

SerialisedProfile

prog_SJProfileKeys.class

DBRMDBRM

CREATE PROCEDURE

orINSERT into

SYSPROCEDURES

7

Error Handling & Debugging

Include provision for passing back results from SP in return parameters Consider passing back meaningful

message if problem encountered ( e.printStackTrace() )

As for other types of stored procedures, debugging can be a problem Output of Java println commands routed

to JSPDEBUG in WLM SP JCL Stored Procedure Builder and ET/390

Debugger tool provide additional facilities

Usage Guidelines

Naming IssuesSource files

One stored procedure (Java application class) per source file

Source file named after DB2 SP name Java package name

One to one relationship with HPJ load module

Use same name for PDS/E member name Group all related source files in single

USS directory named after packageMany others to be considered

Java class name, Java method, DB2 packages, JAR files, etc

DB2 CollectionsEach SQLJ SP has 4 packages

associated with it (one for each isolation level)

Collection containing these SPs must appear in package list for client issuing SP CALL

Use one collection for each Java package, with same name as the package

For JDBC, collection named in client’s package list must contain 4 generic JDBC packages Collection name must match Java

package name

Case SensitivityUse upper case only for Java

package names on S/390 Ditto for other environments if

portability is important JDBC or SQLJ Java client calling a

stored procedure must code SP name in upper case

SQLJ stored procedure must refer to DB2 object names in upper case (else –204)

PackagingCarefully consider number of SPs to

group in a single Java package Large number will result in large HPJ load

module for the package, which may need excessive WLM storage

Small number will result in many DB2 collections to manage

Rules of thumb Group together small, frequently used SPs Keep larger SPs in their own Java package Package remainder along application lines

PortabilityNo code changes necessary to port

JSP source files from one platform to another (e.g. Windows NT to OS/390)

Some changes may be required when porting client code Class.forName (name of driver to be

loaded) Connection URL

Beware issues with ASCII/EBCDIC translation of Java curly brackets ({})

PerformanceSignificant overhead on first use

of a given module Consider pre-staging critical

modules and keeping them in storage

Once in storage, performance on a par with other methods

Use different WLM application groups to correctly prioritise workload

Summary

Summary JSPs for DB2 for OS/390 provide

an open, scaleable, high-performance way of encoding an application’s business logic

Tread carefully in the short term; Complex environment set-up New application development skills DB2 code base still maturing

Questions?

For more information…

Triton ConsultingThe Royal

25 Bank PlainNorwich NR2 4SFUnited Kingdom

email:julian.stuhler@triton.co.ukhttp://www.triton.co.uk

Tel: +44 (0) 870 2411550Fax: +44 (0) 870 2411549