SQL-PL Array Processing in DB2

SQL-PL Array Processing in DB2

Tony Andrews [email protected]

Twitter

Questions?

• I will try my best to get to some questions towards the end of the webinar.

• You can submit questions by typing into the questions area of your webinar control panel.

• Any questions not answered due to time constraints can be answered afterward via an email.

2

Webinar Objectives

• Understand the key areas that can cause performance issues with DB2 queries and applications

• Better understand DB2 optimization• Understand how DB2 database design affects

performance • Understand DB2 data distribution statistics. How

does it affect performance • Understand SQL efficient coding

3

Webinar Objectives• Objective 1: To learn the rules of coding and defining SQL-

PL variable array data types.• Objective 2: To learn about the many array functions

(ARRRAY_AGG, ARRARY_DELETE, TRIM_ARRAY, UNNEST, CARDINALITY, and more).

• Objective 3: Learn uses of the Array Constructor. • Objective 4: Learn the basic array operations like (Sub-

Indexing, Cardinality, Trimming, etc)• Objective 5: Learn how to turn a result set into an array, an

array of elements into a table, etc.).• Get empowered! New as of Db2 LUW 9.5, Db2 for I 7.1,

and z/OS V11.

4

What is an Array ?

• An array is a user-defined data type that consists of an ordered set of elements of a single built-in data type.

• Array entries (elements) can be accessed and modified by their index position. Going beyond the max entry gets an SQLCODE=-20439 ‘An array index with value xx is null, out of range or does not exist’

• Must first create an array datatype and then use it to define a stored procedure parameter, SQL-PL declared variable, or global variable (V12).

Why Arrays ?

• Processing, passing, holding lists of data can often times be bulky and inefficient.

• Replaces the use of tables (either permanent or GTT)• Replaces the use of a string list variable, and then having to

unstring/decode through the list.• Replaces a long list of input/output parameters• The fact that arrays are quite common in most programming

languages. • Test have shown a performance improvement over GTTs,

Long Varchars, and returned results sets

SQL-PL Array Rules

• Arrays in SQL-PL are allocated and de-allocated dynamically. Memory allocation is based on the cardinality (# entries loaded into the array), and not on the possible maximum.

• All elements of array must have same data type• An array can contain a set of values, can contain no values (as

in null values), or the column with array data type can be null• Individual elements can contain a value or be null • The cardinality of the array is equal to the number of elements

in the array, not the max number that it can hold

SQL-PL Array Rules

• Can Java handle SQL-PL Arrays? Yes via the IBM Data Server Driver for JDBC and SQLJ type 4 driver). Some code later. This was a big request from the JAVA development community.

• Can COBOL handle SQL-PL arrays? No.

• Two types of arrays: Ordinary: where items are addressed by their ordinal position within the array). Associative: where items are ordered by a defined array index value.

SQL-PL Array Definition

• Arrays are created using the CREATE TYPE command (UDT):

CREATE TYPE name AS data_type ARRAY[size]

• Includes the name of the array, data_type ARRAY, and the number of occurrences.

• The number of occurrences can be fixed or open ended:

CREATE TYPE DEPT_ARRAY AS CHAR(3) ARRAY[5] ; CREATE TYPE DEPT_ARRAY AS CHAR(3) ARRAY[] ;

SQL-PL Array Functions

• ARRAY: Adds data elements to an array• ARRAY_AGG: Adds data elements to an by extracting data form a Db2

table • TRIM_ARRAY: Removes data elements from an array• DELETE_ARRAY: Deletes the array• UNNEST: returns a result table from the data elements in an array• CARDINALITY: Provides the number of data elements currently in an

array • MAX_CARDINALITY: Provides the maximum value specified in Create• ARRAY_FIRST: Returns the minimum array index value in the array• ARRAY_LAST: Returns the maximum array index value in the array• ARRAY_NEXT: Next element relative to current

SQL-PL ARRAY Function - Example 1

---- Load an ordinary array from hard coded values. Based on: -- CREATE TYPE DEPT_LIST AS CHAR(3) ARRAY[] ; Define the type-- DECLARE V_DEPT_LIST DEPT_LIST; Use the type

• SET V_DEPT_LIST = ARRAY[‘D01’, ‘D11’, ‘D21’];

Note: Square brackets, not parenthesis

• SET V_CARDINALITY = CARDINALITY (V_DEPTNO_LIST);

V_CARDINALITY would be 3.

SQL-PL ARRAY Function - Example 2

---- Load an ordinary array from variable fields--

SET V_DEPTNO_LIST = ARRAY [V_DEPTNO1, V_DEPTNO2, V_DEPTNO3];

SQL-PL ARRAY Function - Example 3

---- Use a SELECT with the ARRAY function --

SET V_DEPTNO_LIST = ARRAY[SELECT DEPTNO FROM EMP];

SQL-PL ARRAY Function - Example 4

---- Use a SELECT with the ARRAY --

SET V_DEPTNO_LIST = ARRAY[SELECT DEPTNO

FROM EMPORDER BY DEPTNOFETCH FIRST 3 ROWS ONLY];

SQL-PL ARRAY Function - Example 5

---- Can also use the word NULL, and a Scalar Fullselect--SET V_DEPTNO_LIST = ARRAY

[NULL, V_DEPTNO2, (SELECT DEPTNO

FROM DEPTWHERE DEPTNO LIKE ‘D%’FETCH FIRST 1 ROW ONLY)

];

SQL-PL ARRAY_AGG Function -Example 1

---- Load up the DEPTNO array with values from the EMP table-- using a SET statement --

SET V_DEPTNO_LIST = (SELECT ARRAY_AGG(DEPTNO ORDER BY

DEPTNO)FROM DEPTWHERE DEPTNO LIKE 'D%'FETCH FIRST 3 ROWS ONLY

);

SQL-PL ARRAY_AGG Function -Example 2

---- Distinct cannot be used directly in the ARRAY_AGG Set select --

SET V_DEPTNO_LIST = (SELECT ARRAY_AGG(DEPTNO ORDER BY

DEPTNO)FROM (SELECT DISTINCT DEPTNO

FROM THEMIS90.PROJWHERE DEPTNO LIKE 'D%'FETCH FIRST 3 ROWS ONLY)

);

SQL-PL ARRAY_AGG Function -Example 3

---- You can select directly into …. But with some exceptions …--

SELECT ARRAY_AGG(DEPTNO)INTO V_DEPTNO_LISTFROM DEPTWHERE DEPTNO LIKE 'D%'

SQL-PL ARRAY_AGG Function -Example 3

---- You cannot however do a fetch first ….--

SELECT ARRAY_AGG(DEPTNO)INTO V_DEPTNO_LISTFROM DEPTWHERE DEPTNO LIKE 'D%' FETCH FIRST 3 ROWS ONLY;

Deploy Error:

stored procedure returns SQLCODE: -490, SQLSTATE: 428B7.NUMBER 3 DIRECTLY SPECIFIED IN AN SQL STATEMENT IS OUTSIDE THE RANGE OF ALLOWABLE VALUES IN Deploy failed.

SQL-PL ARRAY_AGG Function -Example 4

---- You cannot however do an order by ….--

SELECT ARRAY_AGG(DEPTNO)INTO V_DEPTNO_LISTFROM DEPTWHERE DEPTNO LIKE 'D%' ORDER BY DEPTNO;

Deploy Error:

Create stored procedure returns SQLCODE: -390, SQLSTATE: 42887.THE OBJECT ARRAY_AGG, SPECIFIC NAME *N, IS NOT VALID IN THE CONTEXT WHERE IT IS USED. SQLCODE=-390, SQLSTATE=42887, Deploy failed.

SQL-PL ARRAY_AGG Function -Example 5

---- You can however code them in a table -- expression ….--

SELECT ARRAY_AGG(DEPTNO)INTO V_DEPTNO_LISTFROM

(SELECT DEPTNO FROM THEMIS90.DEPTWHERE DEPTNO LIKE 'D%'ORDER BY DEPTNO FETCH FIRST 3 ROWS ONLY)

Deployed !!!!

SQL-PL Emptying an array

---- To empty an array --

SET V_DEPTNO_LIST = NULL; Sets the variable to null SET V_CARDINALITY =

CARDINALITY (V_DEPTNO_LIST);

V_CARDINALITY is null not 0.

SET V_DEPTNO_LIST = ARRAY[]; Empties the variableSET V_CARDINALITY =

CARDINALITY (V_DEPTNO_LIST);

V_CARDINALITY = 0.

SQL-PL CARDINALITY

• CARDINALITY

SET DEPT_LIST [5] = ‘F22’; Sets the 5th element in arrayCARDINALITY would be 5.

SET V_DEPTNO = V_DEPT_LIST[6] Would get an error dueto that occurrence not existing yet. -20439 SQLCODE

What if? SET V_DEPT_LIST [7] = ‘G22’; and then …

SET V_DEPTNO = V_DEPT_LIST[6] V_DEPT set to nulls!

SQL-PL UNNEST Example 1The UNNEST treats the array like a table

SELECT COUNT(*) INTO P_OUT_COUNTFROM EMP WHERE DEPTNO IN

(SELECT IN.DEPT FROM UNNEST(P_DEPTNO_LIST) ASIN(DEPT))

;

SQL-PL UNNEST WITH ORDINALITYExample 2

CREATE TABLE DEPT_EMEA

( POSITION INT,DEPTNO CHAR(3)

) ;

INSERT INTO DEPT_EMEA(DEPTNO, POSITION) SELECT * FROM UNNEST(V_DEPTNO_LIST) WITH ORDINALITYAS (DEPTNO, POSITION)

;

SELECT *FROM DEPT_EMEA;

POSITION DEPTNO------------- ----------

1 D012 D113 D21

SQL-PL UNNEST Example 3

SELECT P.PROJNO, P.PROJNAMEFROM PROJ P,

UNNEST(P_DEPTPNO_LIST) AS V(DEPTNO)WHERE P.DEPTNO = V.DEPTNO

SQL-PL Associative Arrays

• Arrays in SQL-PL that assign a unique key to a value • No maximum cardinality is defined (open ended)• Create statement needs to have index datatype specified

• Must be integer or varchar (or you get SQLCODE=-20436)• The associative array index values do not have to be ordered

• Can be sparse• Each element in the array can be referenced by an associated

index valueCREATE TYPE STATES_ARRAY AS VARCHAR(16)

ARRAY[VARCHAR(02)];

SQL-PL Associative Arrays

CREATE TYPE STATES_ARRAY AS VARCHAR(16)

ARRAY[VARCHAR(02)];

• The data type VARCHAR(16) after the AS keyword refers to the data values (in this case state names) stored in the array. Ex: ‘Ohio’, ‘Alabama’, etc..

• The ARRAY[VARCHAR(02)] indicates that this is an associative array and will contain the index values. For this example ‘OH’, ‘AL’, etc.

SQL-PL Associative Arrays

• The order in which values are assigned to array elements in an associative array does not matter, but they will be re-ordered in the order of the index values: For example:

DECLARE V_STATE_NAMES STATES_ARRAY;

SET V_STATE_NAMES['OH'] = 'Ohio';SET V_STATE_NAMES['AL'] = 'Alabama';SET P_STATE_INDEX = ARRAY_FIRST(V_STATE_NAMES);

P_STATE_INDEX will equal ‘AL’

SQL-PL Associative Arrays

• How do we get the state names out of the array after they are loaded? You need to have an index state code value, with hard coded or from a variable. For example:

DECLARE V_STATE_NAMES STATES_ARRAY;

SET V_STATE_NAMES['OH'] = 'Ohio';SET V_STATE_NAMES['AL'] = 'Alabama';

SET P_STATE_NAME = V_STATE_NAMES['OH'];

P_STATE_NAME will equal ‘Ohio’

SQL-PL Associative Arrays

• What if we try to set a variable or parameter with a value using and index value that does not exists in the table? For example:

SET P_STATE_NAME = V_STATE_NAMES[‘XX'];

SQLCODE -20439 AN ARRAY INDEX WITH VALUE XX IS NULL, OUT OF RANGE OR DOES NOT EXIST

SET P_STATE_NAME = V_STATE_NAMES[‘oh']; Note lowercase

SQLCODE -20439 AN ARRAY INDEX WITH VALUE oh IS NULL, OUT OF RANGE OR DOES NOT EXIST

SQL-PL Arrays and Java

• Java programs must accesses the DB2 for z/OS server via the IBM Data Server Driver for JDBC and SQLJ type 4 driver

• To pass an array to a stored procedure, use the createArrayOf() method of the Connection object• Creates a java.sql.Array object of the specified type

• Use the underlying datatype of the array element• Do not try to use the UDT name

• The first example that follows accepts an array as it's first parameter

• The example following that one returns an array as it's 2nd

parameter

SQL-PL V12 Enhancements z/OS

• Db2 11 provided support for the array data type• Db2 also allows for global variables, but not defined as an array• Db2 12 provides for using an associative array as an argument to

the ARRAY_AGG function

Thank you for allowing me and Themis to share some of our experience and

knowledge today!

Tony Andrews [email protected]

I hope that you learned something new today !!!!

The material in this presentation is further developed in the following Themis courses:

DB1029 – Exploiting SQL-PL Native Stored Procedures on z/OS

DB1028 – DB2 LUW SQL-PL Stored Procedure Development

DB1070 – Advanced Query, Native Stored Procedures, and Query Tuning on DB2 for z/OS

Links to these courses may be found at: www.themisinc.com

Tony’s Email: [email protected]: @ThemisTraining

Finally! A book of DB2 SQL tuning tips for developers, specifically designed to improve performance.

DB2 SQL developers now have a handy reference guide with tuning tips to improve performance in queries, programs and applications.

Education. Check out www.db2sqltuningtips.com

www.ibmpress.comwww.amazon.com

Education. Check Outwww.themisinc.com

• On-site and Public• Instructor -led• Hands-on• Customization • Experience• Over 30 DB2

courses• Over 400 IT courses

US 1-800-756-3000Intl. 1-908-233-8900