this information could include technical inaccuracies or ... · declare sqlcode integer default 0;...

© 2011 Themis, Inc. All rights reserved. 1

DB2 for z/OS Native SQL Procedures are quick and easy to develop, test, and debug. Native

SQLPL procedures have proven to be an invaluable tool for mid-tier developers with minimal

z/OS experience. They perform well and with a little forethought are easy to Deploy across

environments. This presentation takes a look at DB2 9 & 10 for z/OS Native SQL Procedures

development Lifecycle and our user clientele experiences in implementing Native SQLPL

Procedures. We will discuss SQLPLs strengths and limitations, best practices, and interfacing

with existing change management tools.

Disclaimer: This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be incorporated in

new editions of the publication. IBM may make improvements and/or changes in the product(s)

and/or the program(s) described in this publication at any time without notice.

This document contains references to several IBM products and names which are the property of

IBM, Inc.

All registered trademarks, trademarks, and service marks are the property of their respective

companies.

Outline:

• Native SQL procedure development Lifecycle

• Data Studio vs. Ad Hoc Tools

• Testing a native SQL procedure

• Deployment of a native SQL procedure

• DB2/DSN/SQL command changes

•User Experiences

• Field of Use

• Limitations and Strengths

• Best Practices

• Interfacing with existing change management tools

•Identify critical performance issues

•Recap


3

Stored procedures are user-written modules that are stored at the database server and can be

invoked by client applications using SQL statements. Stored procedures are predefined processes

that execute the DB2 server side of applications. They can be called locally, on the same system

where the application runs, or remotely from a different system. The SQL CALL statement is used

to invoke a stored procedure. A stored procedure can send and/or receive parameters from the

calling program.

The main goal of the stored procedure is the reduction of network message flow between the

requester (the application) and the data server (DB2) in a distributed environment. Another usage

of stored procedures is to have functions callable from any application on any platform.

Your programming productivity can be improved using stored procedures when you develop

client/server applications. Stored procedures are the easiest way to perform a remote call and to

distribute the logic of an application program.

© 2011 Themis, Inc. All rights reserved.

4

In previous releases of DRDA, the client system performed all application logic. The server was

responsible only for SQL processing on behalf of the client. In such an environment, all database

accesses must go across the network, resulting in poor performance in some cases.

Because the application logic runs only on the client workstations, additional network

input/output (I/O) operations are required for most SQL requests. These additional operations can

result in poor performance. This approach also requires the client program to have detailed

knowledge of the server¢ s database design. Thus, every change in the database design at the

server requires a corresponding change in all client programs accessing the database. Also,

because the programs run at the client workstations, it is often complicated to manage and

maintain the copies there.


5

Stored procedures enable you to encapsulate many of your application’s SQL statements into a

program that is stored at the DB2 server. The client can invoke the stored procedure by using only

one SQL statement, thus reducing the network traffic to a single send and receive operation for a

series of SQL statements. It is also easier to manage and maintain programs that run at the server

than it is to manage and maintain many copies at the client machines.


6

Stored procedures enable you to split the application logic between the client and the server. You

can use this technique to prevent the client application from manipulating the contents of sensitive

server data. You can also use it to encapsulate business logic into programs at the server.

The stored procedure can issue static or dynamic SQL statements. Data definition language

(DDL), most data manipulation language (DML), and data control language (DCL) statements

can be coded in a stored procedure.

Stored procedures also enable access to features that exist only on the database server. These

features include commands that run only on the server, software installed only on the server that

can be accessed by the stored procedure, and the computing resources of the server, such as

memory and disk space.

Because stored procedures are defined in DRDA, they also take advantage of DRDA features,

such as data transformation between platforms, database security and accounting, and two-phase

commit support.


1-8


1-9


1-11


1-12


1-13


DECLARE EXIT HANDLER FOR SQLEXCEPTION

BEGIN

GET DIAGNOSTICS CONDITION 1

LINE_NUM = DB2_LINE_NUMBER,

REASON_CODE = DB2_REASON_CODE,

SQLCODE_OUT = DB2_RETURNED_SQLCODE,

ROW_NUM = DB2_ROW_NUMBER,

MSG_OUT = MESSAGE_TEXT;

CALL DB1029CL.SPXNER5

(PNAME,LINE_NUM, REASON_CODE, SQLCODE_OUT,

ROW_NUM, MSG_OUT,L_SUCCESS);

SET L_SUCCESS = SQLCODE;

END;


Native SQL procedures have been designed with the view of the application development

lifecycle in mind. You can create a version of an SQL procedure, debug it, replace it or add a new

version of the procedure, and finally deploy it into production. DB2 manages the various aspects

of the application development lifecycle in a consistent and integrated manner providing

enhanced security, including the source code for the native SQL procedures. Also native SQL

procedures offer application and tools support like SPUFI, DSNTEP2 on the server side, and the

Data Studio on the client side. Therefore, there are no load modules that need to be link-edited

and there are no WLM address spaces that need to be refreshed.


DSNTEP2 commonly used to interface with change management tools


With V9 new function mode, when you create a native SQL procedure, its procedural statements

are converted to a native representation that is stored in the DB2 catalog and directory, as it is

done with other SQL statements. The parameter list and procedure options are stored in the

database catalog tables as in the prior releases. When you CALL a native SQL procedure, DB2

loads the native representation from the directory and the DB2 engine executes the procedure.


From a performance point of view, converting your current critical SQL procedures to the new

format may take advantage of the native execution in DB2 reducing the usage of the WLM stored

procedure address spaces and increasing throughput.

The TEXT column of the SYSIBM.SYSROUTINES table points to the auxiliary table

SYSIBM.SYSROUTINESTEXT. This is required to hold the large object (LOB) data. The data

held in auxiliary table SYSIBM.SYSROUTINESTEXT is the character large object (CLOB) data

that is the source text of the CREATE or ALTER statement with the body for the routine. Define

the size of the SYSIBM.SYSROUTINESTEXT auxiliary table so that it is large enough to contain

the native SQL procedures in your environment.

The expanded size of native SQL procedures will impact your EDM pool, Catalog and the SPT01

space in your Directory. Review and size accordingly.

In DB2 V9, almost all of DDF runs in 64-bit mode and now uses above-the-bar storage in the

z/OS Shared Memory Facility. DDF has moved almost all of the control blocks from ECSA into

shared memory, freeing this system’s resource for other users.


Relieve 64GB limit for SPT01; PBG tablespace and added LOB column & allow compression


DB2 9 for z/OS now places portions of the bound/prepared DML statements (SQL statement text,

SQLDA for DESCRIBE output, part of the native SQL PL package, and some other areas) into

storage above the 2 GB bar. This should provide further virtual storage constraint relief below the

bar. The infrastructure is now in place to move other runtime structures above the bar in the

future.

In DB2 9 for z/OS the EDMPOOL plan and package skeletons (SKCT/SKPT) are now above the

2 GB bar. Also, static SQL sections (CT/PT) are split between above and below the 2 GB bar.

Some storage acquired for distributed applications and some storage acquired for dynamic SQL

statement execution also moved above the 2 GB bar (the Parse Trees and portion of Run Time

blocks moved above the 2 GB bar). The goal is to reduce virtual storage requirements below the 2

GB bar by 10 to 15% for both static SQL and dynamic SQL.

DB2 10 DBM1 address space uses 80 – 90% less virtual storage below the 2 GB bar.

30 © 2011 Themis, Inc. All rights reserved.

Efficiency enhancements with commonly used functions.

Improved code generation.

REGENERATE to take advantage of the improvements.


DB2 9 for z/OS is able to maintain multiple versions of native SQL procedures in the DB2 catalog

without having to vary the schema or collection ID.

VERSION routine-version-id

Specifies the version identifier for the first version of the procedure that is to be generated. V1 is

the default version identifier. However, if you are going to implement versioning do not take the

default.

The location is set to the value of the CURRENT SERVER special register.

The collection-id (schema) for the package is the same as the schema qualifier of the procedure.

This may cause you problems with your existing naming conventions if Schema and Collection-

ids are not the same

The package-id is the same as the specific name of the procedure.

If you want to change the collection-id for the name of the package, you need to make a copy of

the package.


ALTER PROCEDURE DBTHM.SP3N

ADD VERSION VR2

( IN DNUM CHAR(3)

, OUT DCOUNT SMALLINT )

ISOLATION LEVEL CS

VALIDATE BIND

PACKAGE OWNER ownerid

QUALIFIER THEMIS90

RESULT SETS 0

LANGUAGE SQL

P1: BEGIN

DECLARE SQLCODE INTEGER DEFAULT 0;

SELECT COUNT(*)

INTO DCOUNT

FROM EMP

WHERE DEPTNO >= DNUM;

END P1 #

When you add a new version of a procedure the data types, CCSID specifications, and character data attributes of the parameters must be the same as the attributes of the corresponding parameters for the currently active version of the procedure. The parameter names can differ from the other versions of the procedure. For options that are not explicitly specified, the system default values will be used.


ALTER PROCEDURE DBTHM.SP3N

REPLACE VERSION VR2

( IN DNUM CHAR(3)

, OUT DCOUNT SMALLINT

, OUT SUMSAL DEC(11,2) )

ISOLATION LEVEL CS

VALIDATE BIND

PACKAGE OWNER ownerid

QUALIFIER THEMIS90

RESULT SETS 0

LANGUAGE SQL

P1: BEGIN

DECLARE SQLCODE INTEGER DEFAULT 0;

SELECT COUNT(*),SUM(SALARY)

INTO DCOUNT, SUMSAL

FROM EMP

WHERE DEPTNO = DNUM;

END P1 #

---------+---------+---------+---------+---------+---------+---------+---

DSNT408I SQLCODE = -20314, ERROR: THE PARAMETER LIST DOES NOT MATCH THE

PARAMETER LIST FOR ALL OTHER VERSIONS OF ROUTINE DBTHM.SP3N


When you replace a procedure, the data types, CCSID specifications, and character data attributes

(FOR BIT/SBCS/MIXED DATA) of the parameters must be the same as the attributes of the

corresponding parameters for the currently active version of the procedure. For options that are

not explicitly specified, the system default values for those options are used, even if those options

were explicitly specified for the version of the procedure that is being replaced. This is not the

case for versions of the procedure that specified DISABLE DEBUG MODE. If DISABLE

DEBUG MODE is specified for a version of a procedure, it cannot be changed by the REPLACE

clause.


Note: REGENERATE is different from a REBIND PACKAGE in the sense that the

REBIND PACKAGE command implies the generation of possibly better access paths for the

embedded SQL statements. REGENERATE affects the SQL control statements in the procedure

definition. These stay the same for a REBIND PACKAGE.

If a remote bind is also needed, you must explicitly use the BIND PACKAGE COPY command

for all of the remote servers.


If you specify ACTION(ADD) for a version that does not exist at the target location, DB2 creates

or adds a new version of the native SQL procedure and its associated package while keeping the

source native SQL procedure’s logic. DB2 adds a new version if a native SQL procedure with the

same target name already exists.

If you specify ACTION(REPLACE), DB2 replaces the version specified in COPYVER. If you

specify REPLVER, the version ID must be the same as the COPYVER version ID or DB2 returns

TSO error message DSNE977E.

Notice that the schema name used becomes the collection-id of the package. At the same time the

procedure name also becomes the package-id itself. This is important in the following deployment

step.

The next step in the deployment process is to create a new SQL procedure for the production

environment on a remote DB2 subsystem, named CHICAGO.DBPROD.SP3N from the existing

SQL procedure that we have just created (that is, DBTHM.SP3N). Both procedures have the same

version


Tip: When you use the CURRENT ROUTINE VERSION special register to test a version of

one or more native SQL procedures, you should use a routine version identifier that is a value

other than the default value (V1) on the CREATE PROCEDURE statement. This will avoid

having the special register affect more procedures than you intend when testing a new version of a

procedure.

For ad hoc testing an application sets this register to an existing valid version, it temporarily

overrides the setting in column ACTIVE of the SYSIBM.SYSROUTINES catalog table. If the

provided value is not valid, the default catalog settings are used. The subsequent CALL to the

stored procedure has to be dynamically prepared, otherwise the register is not taken into account.

This is mainly because a static CALL to the native SQL procedure already has the version

identifier bound to in the respective package.


Specifies whether processing uses only committed data or whether it will wait for commit or

rollback of data that is in the process of being updated.

WAIT FOR OUTCOME

Specifies that processing will wait for the commit or rollback of data that is in the process of

being updated.

USE CURRENTLY COMMITTED

Specifies that processing use the currently committed version of the data when data that is in the

process of being updated is encountered. USE CURRENTLY COMMITTED is applicable on

scans that access tables that are defined in universal table spaces with row or page level lock

size. When there is lock contention between a read transaction and an insert transaction, USE

CURRENTLY COMMITTED is applicable to scans with isolation level CS or RS. Applicable

scans include intent read scans for read-only and ambiguous queries and for updatable cursors.

USE CURRENTLY COMMITTED is also applicable to scans initiated from WHERE

predicates of UPDATE or DELETE statements and the subselect of INSERT statements. When

there is lock contention between a read transaction and a delete transaction, USE CURRENTLY

COMMITTED is applicable to scans with isolation level CS and when CURRENTDATA(NO)

is specified.


An enhanced native SQL procedure can define a parameter or SQL variable as a distinct type,

define an SQL parameter or an SQL variable as an XML data type, and make limited use of

scrollable cursors.

An SQL table function is a function that is written exclusively in SQL statements and returns a

single table. You can use an SQL table function to:

- Define a parameter for a transition table (for example, the TABLE LIKE ... AS LOCATOR

syntax)

- Define a parameter as a built-in type or a distinct type

-Include a single SQL PL RETURN statement that returns a result table

Multiple assignments: If more than one assignment is included in the same assignment

statement, all expressions are evaluated before the assignments are performed. Thus, references to

an SQL variable or SQL parameter in an expression always use the value of the SQL variable or

SQL parameter prior to any assignment in the assignment statement.


This is an abbreviated version of the field of use document from one of our clients.


Tip: When you use the CURRENT ROUTINE VERSION special register to test a version of one

or more native SQL procedures, you should use a routine version identifier that is a value other

than the default value (V1) on the CREATE PROCEDURE statement. This will avoid having the

special register affect more procedures that you intend when testing a new version of a procedure.

For example, assume that you want to run version VER2 of procedure P1, and procedure P1

invokes another procedure, P2. If a version exists for both procedures P1 and P2 with the routine

version identifier VER2, that version will be used for both procedures.



BEGIN

GET DIAGNOSTICS CONDITION 1 MESSAGE_OUT = MESSAGE_TEXT;

SET SQLCODE_OUT = SQLCODE;

END;


BEGIN







END;


The following output parameters would to be added to your procedure.

,OUT LINE_NUM INTEGER

,OUT REASON_CODE INTEGER

,OUT SQLCODE_OUT INTEGER

,OUT ROW_NUM DECIMAL(31,0)

,OUT MSG_OUT VARCHAR(132)


~


BEGIN







ROLLBACK;

INSERT INTO ERRTBL

(MODNAME, E_LINE_NUM, E_REASON_CODE, E_SQLCODE_OUT, E_ROW_NUM, E_MSG_OUT)

VALUES('SPXNER2', LINE_NUM, REASON_CODE, SQLCODE_OUT, ROW_NUM, MSG_OUT);

COMMIT;

SET LOG_SUCCESS = SQLCODE;

END;


With Data Studio 2.2.0 you can edit and save tailored fragments

With Data Studio 2.2.1 You can create or edit templates on the Routines > Templates Preferences

page.


When calling a native SQL procedure, the resolution is performed with the help of the schema

name, the procedure name, and the number of parameters. Parameter overloading is not

supported.

Once the correct procedure has been resolved, the current active version is determined. Only one

active version of a native SQL procedure exists at any point in time. By default the current active

version is the version that contains a flag Y in the ACTIVE column of the catalog table

SYSIBM.SYSROUTINES.


Unlike external stored procedures, native stored procedures do not execute in a WLM address

space. WLM is only required for debugging.

Native SQL procedure: everything runs under the caller’s task – when the stored procedure is

called, the caller’s DB2 thread just switches to the SP package; No queuing, no delays and

reduced dispatch overhead.

Native SQL procedures are zIIP-eligible when called via DRDA.

Work that runs on the zIIP does not incur software charges based on the service units consumed;

therefore it is a very attractive lower-cost alternative to running workloads on a general purpose

processor. With the zIIP capability, the System z9 or System z10 mainframes help minimize the

need to maintain duplicate copies of data. This eliminates the need to pass the data between

DBM1 and the DDF address space. For server threads that process SQL requests from

applications that access DB2 by TCP/IP, a portion of the SP executes under a dependent enclave

SRB if it processes on behalf of an application that originated from an allied address space, or

under an independent enclave SRB if the processing is performed on behalf of a remote

application that accesses DB2 by TCP/IP. Shared memory is a relatively new type of virtual

storage that allows multiple address spaces to easily address common storage that is introduced in

z/OS 1.5. It is similar to ECSA, since it is always addressable and no address register mode or

cross memory moves are needed. It is different from ECSA since it is not available to all address

spaces on the system. Only those that are registered with z/OS as being able to share this storage

have visibility to this storage. Shared memory resides above the 2 GB bar.


DB2 9 for z/OS remote native SQL procedures are described in this paper, showing scalability up

to 3193 transactions per second for SQL procedures and redirect to zIIP of over 40%.

Running SQL procedures in the DBM1 address space, avoids the overhead of starting new address

spaces for stored procedure invocations, and the cost of the round-trip communication between

the WLM and the DBM1 address space for each SQL call. Internal Throughput Ratio (ITR)

improvements of between 0 to 80% have been observed as compared to running an external SQL

procedure.

http://www.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/TD104524

Redbook – DB2 9 for z/OS Stored Procedures: Through the CALL and Beyond

Best practices when using Data Studio and Optim Development Studio with DB2 for z/OS


Linda F. Claussen

[email protected]

Biography

A frequent speaker at conferences and user groups, Linda's 30+ years of experience spans the

various roles of application developer, project manager, Data Base Administration and Systems

Programmer. She has frequently worked with new DB2 sites performing the initial DB2 install,

providing training and consulting to the Project Leaders, DBAs and Application staff responsible

for the initial DB2 pilot project and conducting performance design reviews to insure successful

project implementation. Linda is a past member of the IBM DB2 GOLD Consultants program and

past IDUG conference chair. Linda currently works for Themis, Inc. as a DB2 for z/OS consultant

and technical trainer and is a current member of the IBM Consultant Advisory Council.


David Simpson

[email protected]

Biography

David Simpson is currently a Senior Technical Advisor at Themis Inc. He teaches courses on

SQL, Application Programming, DB2 Administration as well as optimization, performance and

tuning. He has supported transactional systems that use DB2 for z/OS databases in excess of 10

terabytes. David has worked with DB2 since 1993 as an application programmer, DBA and

technical instructor. David is a certified DB2 DBA on both z/OS and LUW. David was voted Best

User Speaker and Best Overall Speaker at IDUG North America 2006. He was also voted Best

User Speaker at IDUG Europe 2006.


this information could include technical inaccuracies or ... · declare sqlcode integer default 0;...

Documents