MQND display queue(’In Q’) curdepth 5. - Student · PDF file5. Look at the Backout queue and find the original message by using the WebSphere MQ sample program CSQ4BCJ1. Note:

4. Display the number of messages that remain on the input queue to verify that

the message has been removed. Issue the following command from a z/OS

console:

/-MQND display queue(’In_Q’) curdepth

5. Look at the Backout queue and find the original message by using the

WebSphere MQ sample program CSQ4BCJ1.

Note: In this example, if a request message with added options for ’exception

report’ is sent (the Report option is specified for ’Message Descriptor’), an

exception report is sent to reply queue and original message is sent to the

deadletter queue.

Chapter 34. WebSphere MQ with DB2 1067

1068 Application Programming and SQL Guide

Chapter 35. Using DB2 as a web services consumer and

provider

Web services are a set of resources and components that applications can use over

HTTP. You can use DB2 as a web services provider and a web services consumer.

DB2 as a web services consumer

DB2 can act as a client for web services, which enables you to be a consumer of

web services in your DB2 applications. web services employs Simple Object Access

Protocol (SOAP). SOAP is an XML protocol that consists of the following

characteristics:

v An envelope that defines a framework for describing the contents of a message

and how to process the message

v A set of encoding rules for expressing instances of application-defined data types

v A convention for representing SOAP requests and responses

The SOAPHTTPV and SOAPHTTPC user-defined functions

DB2 provides user-defined functions with which you can work with SOAP and

consume web services in SQL statements. The user-defined functions are two

varieties of SOAPHTTPV for VARCHAR data and two varieties of SOAPHTTPC

for CLOB data. The user-defined functions perform the following actions:

1. Compose a SOAP request

2. Post the request to the service endpoint

3. Receive the SOAP response

4. Return the content of the SOAP body

When a consumer receives the result of a web services request, the SOAP envelope

is stripped and the XML document is returned. An application program can

process the result data and perform a variety of operations, including inserting or

updating a table with the result data.

SOAPHTTPV and SOAPHTTPC are user-defined functions that enable DB2 to

work with SOAP and to consume web services in SQL statements. These functions

are overloaded functions that are used for VARCHAR or CLOB data of different

sizes, depending on the SOAP body. Web services can be invoked in one of four

ways, depending on the size of the input data and the result data. SOAPHTTPV

returns VARCHAR(32672) data and SOAPHTTPC returns CLOB(1M) data. Both

functions accept either VARCHAR(32672) or CLOB(1M) as the input body.

Example: The following example shows an HTTP post header that posts a SOAP

request envelope to a host. The SOAP envelope body shows a temperature request

for Barcelona.

POST /soap/servlet/rpcrouter HTTP/1.0

Host: services.xmethods.net

Connection: Keep-Alive User-Agent: DB2SOAP/1.0

Content-Type: text/xml; charset="UTF-8"

SOAPAction: ""

Content-Length: 410

<?xml version=’1.0’ encoding=’UTF-8’?>

© Copyright IBM Corp. 1983, 2007 1069

<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/

xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/

xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance

xmlns:xsd=http://www.w3.org/2001/XMLSchema >

<SOAP-ENV:Body>

<ns:getTemp xmlns:ns="urn:xmethods-Temperature">

<city>Barcelona</city>

</ns:getTemp>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Example: The following example is the result of the preceding example. This

example shows the HTTP response header with the SOAP response envelope. The

result shows that the temperature is 85 degrees Fahrenheit in Barcelona.

HTTP/1.1 200 OK

Date: Wed, 31 Jul 2002 22:06:41 GMT

Server: Enhydra-MultiServer/3.5.2

Status: 200

Content-Type: text/xml; charset=utf-8

Servlet-Engine: Lutris Enhydra Application Server/3.5.2

(JSP 1.1; Servlet 2.2; Java™ 1.3.1_04;

Linux 2.4.7-10smp i386; java.vendor=Sun Microsystems Inc.)

Content-Length: 467

Set-Cookie:JSESSIONID=JLEcR34rBc2GTIkn-0F51ZDk;Path=/soap

X-Cache: MISS from www.xmethods.net

Keep-Alive: timeout=15, max=10

Connection: Keep-Alive

<?xml version=’1.0’ encoding=’UTF-8’?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/

xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance

xmlns:xsd=http://www.w3.org/2001/XMLSchema >

<SOAP-ENV:Body>

<ns1:getTempResponse xmlns:ns1="urn:xmethods-Temperature"

SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/ >

<return xsi:type="xsd:float">85</return>

</ns1:getTempResponse>

</SOAP-ENV:Body></SOAP-ENV:Envelope>

Example: The following example shows how to insert the result from a web

service into a table

INSERT INTO MYTABLE(XMLCOL) VALUES (DB2XML.SOAPHTTPC(

’http://www.myserver.com/services/db2sample/list.dadx/SOAP’,

’http://tempuri.org/db2sample/list.dadx’

’<listDepartments xmlns="http://tempuri.org/db2sample/listdadx">

<deptno>A00</deptno>

</ListDepartments>’))

SQLSTATEs for DB2 as a web services consumer

Table 213 shows the possible SQLSTATE values that DB2 returns for error

conditions related to using DB2 as a web services consumer.

Table 213. SQLSTATE values that DB2 returns for error conditions related to using DB2 as a

web services consumer

SQLSTATE Description

38301 An unexpected NULL value was pass as input to the function.

38302 The function was unable to allocate space.

38304 An unknown protocol was specified ion the endpoint URL.

38305 An invalid URL was specified on the endpoint URL.


Table 213. SQLSTATE values that DB2 returns for error conditions related to using DB2 as a

web services consumer (continued)

SQLSTATE Description

38306 An error occurred while attempting to create a TCP/IP socket.

38307 An error occurred while attempting to bind a TCP/IP socket.

38308 The function could not resolve the specified host name.

38309 An error occurred while attempting to connect to the specified server.

38310 An error occurred while attempting to retrieve information from the

protocol.

38311 An error occurred while attempting to set socket options.

38312 The function received unexpected data returned for the web service.

38313 The web service did not return data of the proper content type.

38314 An error occurred while initializing the XML parser.

38315 An error occurred while creating the XML parser.

38316 An error occurred while establishing a handler for the XML parser.

38317 The XML parser encountered an error while parsing the result data.

38318 The XML parser could not convert the result data to the database code

page.

38319 The function could not allocate memory when creating a TCP/IP socket.

38320 An error occurred while attempting to send the request to the specified

server.

38321 The function was unable to send the entire request to the specified server.

38322 An error occurred while attempting to read the result data from the

specified server.

38323 An error occurred while waiting for data to be returned from the specified

server.

38324 The function encountered an internal error while attempting to format the

input message.

38325 The function encountered an internal error while attempting to add

namespace information to the input message.

38327 The XML parser could not strip the SOAP envelope from the result

message.

38328 An error occurred while processing an SSL connection.

DB2 as a web services provider

You can enable your DB2 data and applications as web services through the Web

Services Object Runtime Framework (WORF). You can define a web service in DB2

by using a Document Access Definition Extension (DADX). In the DADX file, you

can define web services based on SQL statements and stored procedures. Based on

your definitions in the DADX file, WORF performs the following actions:

v Handles the connection to DB2 and the execution of the SQL and the stored

procedure call

v Converts the result to a web service

v Handles the generation of any Web Services Definition Language (WSDL) and

UDDI (Universal Description, Discovery, and Integration) information that the

client application needs

Chapter 35. Using DB2 as a web services consumer and provider 1071

For more information about using DB2 as a web services provider, see DB2

Information Integrator Application Developer’s Guide.


Chapter 36. Programming techniques: Questions and answers

This chapter answers some frequently asked questions about database

programming techniques. It contains the following topics.

Providing a unique key for a table

Question: How can I provide a unique identifier for a table that has no unique

column?

Answer: Add a column with the data type ROWID or an identity column. ROWID

columns and identity columns contain a unique value for each row in the table.

You can define the column as GENERATED ALWAYS, which means that you

cannot insert values into the column, or GENERATED BY DEFAULT, which means

that DB2 generates a value if you do not specify one. If you define the ROWID or

identity column as GENERATED BY DEFAULT, you need to define a unique index

that includes only that column to guarantee uniqueness.

For more information about using DB2-generated values as unique keys, see

Chapter 11, “Using DB2-generated values as keys,” on page 313.

Scrolling through previously retrieved data

Question: When a program retrieves data from the database, how can the program

scroll backward through the data?

Answer: Use one of the following techniques:

v Use a scrollable cursor.

v If the table contains a ROWID or an identity column, retrieve the values from

that column into an array. Then use the ROWID or identity column values to

retrieve the rows in reverse order.

These options are described in more detail in “Using a scrollable cursor” and

“Using a ROWID or identity column” on page 1074.

Using a scrollable cursor

Using a scrollable cursor to fetch backward through data involves these basic steps:

1. Declare the cursor with the SCROLL keyword.

2. Open the cursor.

3. Execute a FETCH statement to position the cursor at the end of the result table.

4. In a loop, execute FETCH statements that move the cursor backward and then

retrieve the data.

5. When you have retrieved all the data, close the cursor.

You can use code like the following example to retrieve department names in

reverse order from table DSN8910.DEPT:

/**************************/

/* Declare host variables */

/**************************/

EXEC SQL BEGIN DECLARE SECTION;

char[37] hv_deptname;

EXEC SQL END DECLARE SECTION;


/**********************************************************/

/* Declare scrollable cursor to retrieve department names */

/**********************************************************/

EXEC SQL DECLARE C1 SCROLL CURSOR FOR

SELECT DEPTNAME FROM DSN8910.DEPT; .../**********************************************************/

/* Open the cursor and position it after the end of the */

/* result table. */

/**********************************************************/

EXEC SQL OPEN C1;

EXEC SQL FETCH AFTER FROM C1;

/**********************************************************/

/* Fetch rows backward until all rows are fetched. */

/**********************************************************/

while(SQLCODE==0) {

EXEC SQL FETCH PRIOR FROM C1 INTO :hv_deptname;

...}

EXEC SQL CLOSE C1;

Using a ROWID or identity column

If your table contains a ROWID column or an identity column, you can use that

column to rapidly retrieve the rows in reverse order. When you perform the

original SELECT, you can store the ROWID or identity column value for each row

you retrieve. Then, to retrieve the values in reverse order, you can execute SELECT

statements with a WHERE clause that compares the ROWID or identity column

value to each stored value.

For example, suppose you add ROWID column DEPTROWID to table

DSN8910.DEPT. You can use code like the following example to select all

department names, then retrieve the names in reverse order:

/**************************/


/**************************/


SQL TYPE IS ROWID hv_dept_rowid;



/***************************/

/* Declare other variables */

/***************************/

struct rowid_struct {

short int length;

char data[40]; /* ROWID variable structure */

}

struct rowid_struct rowid_array[200];

/* Array to hold retrieved */

/* ROWIDs. Assume no more */

/* than 200 rows will be */

/* retrieved. */

short int i,j,n;

/***********************************************/

/* Declare cursor to retrieve department names */

/***********************************************/

EXEC SQL DECLARE C1 CURSOR FOR

SELECT DEPTNAME, DEPTROWID FROM DSN8910.DEPT; .../**********************************************************/

/* Retrieve the department name and ROWID from DEPT table */

/* and store the ROWID in an array. */

/**********************************************************/


EXEC SQL OPEN C1;

i=0;

while(SQLCODE==0) {

EXEC SQL FETCH C1 INTO :hv_deptname, :hv_dept_rowid;

rowid_array[i].length=hv_dept_rowid.length;

for(j=0;j<hv_dept_rowid.length;j++)

rowid_array[i].data[j]=hv_dept_rowid.data[j];

i++;

}

EXEC SQL CLOSE C1;

n=i-1; /* Get the number of array elements */

/**********************************************************/

/* Use the ROWID values to retrieve the department names */

/* in reverse order. */

/**********************************************************/

for(i=n;i>=0;i--) {

hv_dept_rowid.length=rowid_array[i].length;

for(j=0;j<hv_dept_rowid.length;j++)

hv_dept_rowid.data[j]=rowid_array[i].data[j];

EXEC SQL SELECT DEPTNAME INTO :hv_deptname

FROM DSN8910.DEPT

WHERE DEPTROWID=:hv_dept_rowid;

}

Scrolling through a table in any direction

Question: How can I fetch rows from a table in any direction?

Answer: Declare your cursor as scrollable. When you select rows from the table,

you can use the various forms of the FETCH statement to move to an absolute row

number, move ahead or back a certain number of rows, to the first or last row,

before the first row or after the last row, forward, or backward. You can use any

combination of these FETCH statements to change direction repeatedly.

You can use code like the following example to move forward in the department

table by 10 records, backward five records, and forward again by three records:

/**************************/


/**************************/




/**********************************************************/

/* Declare scrollable cursor to retrieve department names */

/**********************************************************/

EXEC SQL DECLARE C1 SCROLL CURSOR FOR

SELECT DEPTNAME FROM DSN8910.DEPT; .../**********************************************************/

/* Open the cursor and position it before the start of */

/* the result table. */

/**********************************************************/

EXEC SQL OPEN C1;

EXEC SQL FETCH BEFORE FROM C1;

/**********************************************************/

/* Fetch first 10 rows */

/**********************************************************/

for(i=0;i<10;i++)

{

EXEC SQL FETCH NEXT FROM C1 INTO :hv_deptname;

}

/**********************************************************/

/* Save the value in the tenth row */

/**********************************************************/

Chapter 36. Programming techniques: Questions and answers 1075

tenth_row=hv_deptname;

/**********************************************************/

/* Fetch backward 5 rows */

/**********************************************************/

for(i=0;i<5;i++)

{

EXEC SQL FETCH PRIOR FROM C1 INTO :hv_deptname;

}

/**********************************************************/

/* Save the value in the fifth row */

/**********************************************************/

fifth_row=hv_deptname;

/**********************************************************/

/* Fetch forward 3 rows */

/**********************************************************/

for(i=0;i<3;i++)

{

EXEC SQL FETCH NEXT FROM C1 INTO :hv_deptname;

}

/**********************************************************/

/* Save the value in the eighth row */

/**********************************************************/

eighth_row=hv_deptname;

/**********************************************************/

/* Close the cursor */

/**********************************************************/

EXEC SQL CLOSE C1;

Updating data as it is retrieved from the database

Question: How can I update rows of data as I retrieve them?

Answer: On the SELECT statement, use the FOR UPDATE clause without a column

list, or the FOR UPDATE OF clause with a column list. For a more efficient

program, specify a column list with only those columns that you intend to update.

Then use the positioned UPDATE statement. The clause WHERE CURRENT OF

identifies the cursor that points to the row you want to update.

Updating previously retrieved data

Question: How can you scroll backward and update data that was retrieved

previously?

Answer: Use a scrollable cursor that is declared with the FOR UPDATE clause.

Using a scrollable cursor to update backward involves these basic steps:

1. Declare the cursor with the SENSITIVE STATIC SCROLL keywords.

2. Open the cursor.

3. Execute a FETCH statement to position the cursor at the end of the result table.

4. FETCH statements that move the cursor backward, until you reach the row that

you want to update.

5. Execute the UPDATE WHERE CURRENT OF statement to update the current

row.

6. Repeat steps 4 and 5 until you have update all the rows that you need to.

7. When you have retrieved and updated all the data, close the cursor.

Updating thousands of rows

Question: Are there any special techniques for updating large volumes of data?


Answer: Yes. When updating large volumes of data using a cursor, you can

minimize the amount of time that you hold locks on the data by declaring the

cursor with the HOLD option and by issuing commits frequently.

Retrieving thousands of rows

Question: Are there any special techniques for fetching and displaying large

volumes of data?

Answer: There are no special techniques; but for large numbers of rows, efficiency

can become very important. In particular, you need to be aware of locking

considerations, including the possibilities of lock escalation.

If your program allows input from a terminal before it commits the data and

thereby releases locks, it is possible that a significant loss of concurrency results.

Review the description of locks in “The ISOLATION option” on page 471 while

designing your program. Then review the expected use of tables to predict

whether you could have locking problems.

Using SELECT *

Question: What are the implications of using SELECT * ?

Answer: Generally, you should select only the columns you need because DB2 is

sensitive to the number of columns selected. Use SELECT * only when you are

sure you want to select all columns, except hidden columns. (Hidden columns are

not returned when you specify SELECT *.) One alternative to selecting all columns

is to use views defined with only the necessary columns, and use SELECT * to

access the views. Avoid SELECT * if all the selected columns participate in a sort

operation (SELECT DISTINCT and SELECT...UNION, for example).

Optimizing retrieval for a small set of rows

Question: How can I tell DB2 that I want only a few of the thousands of rows that

satisfy a query?

Answer: Use OPTIMIZE FOR n ROWS or FETCH FIRST n ROWS ONLY.

DB2 usually optimizes queries to retrieve all rows that qualify. But sometimes you

want to retrieve only the first few rows. For example, to retrieve the first row that

is greater than or equal to a known value, code:

SELECT column list FROM table

WHERE key >= value

ORDER BY key ASC

Even with the ORDER BY clause, DB2 might fetch all the data first and sort it

afterwards, which could be wasteful. Instead, you can write the query in one of the

following ways:

SELECT * FROM table

WHERE key >= value

ORDER BY key ASC

OPTIMIZE FOR 1 ROW

SELECT * FROM table

WHERE key >= value

ORDER BY key ASC

FETCH FIRST n ROWS ONLY


|||||||

Use OPTIMIZE FOR 1 ROW to influence the access path. OPTIMIZE FOR 1 ROW

tells DB2 to select an access path that returns the first qualifying row quickly.

Use FETCH FIRST n ROWS ONLY to limit the number of rows in the result table

to n rows. FETCH FIRST n ROWS ONLY has the following benefits:

v When you use FETCH statements to retrieve data from a result table, FETCH

FIRST n ROWS ONLY causes DB2 to retrieve only the number of rows that you

need. This can have performance benefits, especially in distributed applications.

If you try to execute a FETCH statement to retrieve the n+1st row, DB2 returns a

+100 SQLCODE.

v When you use FETCH FIRST ROW ONLY in a SELECT INTO statement, you

never retrieve more than one row. Using FETCH FIRST ROW ONLY in a

SELECT INTO statement can prevent SQL errors that are caused by

inadvertently selecting more than one value into a host variable.

When you specify FETCH FIRST n ROWS ONLY but not OPTIMIZE FOR n ROWS,

OPTIMIZE FOR n ROWS is implied. When you specify FETCH FIRST n ROWS

ONLY and OPTIMIZE FOR m ROWS, and m is less than n, DB2 optimizes the

query for m rows. If m is greater than n, DB2 optimizes the query for n rows.

Adding data to the end of a table

Question: How can I add data to the end of a table?

Answer: Though the question is often asked, it has no meaning in a relational

database. The rows of a base table are not ordered; hence, the table does not have

an “end”.

However, depending on your goal, you can perform one of the following actions to

simulate adding data to the end of a table:

v If your goal is to get a result table that is ordered according to when the rows

were inserted, define a unique index on a TIMESTAMP column in the table

definition. Then, when you retrieve data from the table, use an ORDER BY

clause that names that column. The newest insert appears last.

v If your goal is for DB2 to insert rows in the next available free space, without

preserving clustering order, specify the APPEND YES option when you create or

alter the table. Specifying this option might reduce the time it takes to insert

rows, because DB2 does not spend time searching for free space.

Translating requests from end users into SQL statements

Question: A program translates requests from end users into SQL statements before

executing them, and users can save a request. How can the corresponding SQL

statement be saved?

Answer: You can save the corresponding SQL statements in a table with a column

having a data type of VARCHAR(n), where n is the maximum length of any SQL

statement. You must save the source SQL statements, not the prepared versions.

That means that you must retrieve and then prepare each statement before

executing the version stored in the table. In essence, your program prepares an

SQL statement from a character string and executes it dynamically. (For a

description of dynamic SQL, see Chapter 25, “Coding dynamic SQL in application

programs,” on page 661.)


||

||||

||||

Changing the table definition

Question: How can I write an SQL application that allows users to create new

tables, add columns to them, increase the length of character columns, rearrange

the columns, and delete columns?

Answer: Your program can dynamically execute CREATE TABLE and ALTER

TABLE statements entered by users to create new tables, add columns to existing

tables, or change the data types of existing columns. Added columns initially

contain either the null value or a default value. Both statements, like any data

definition statement, are relatively expensive to execute; consider the effects of

locks.

You cannot rearrange or delete columns in a table without dropping the entire

table. You can, however, create a view on the table, which includes only the

columns you want, in the order you want. This has the same effect as redefining

the table.

For a description of dynamic SQL execution, see Chapter 25, “Coding dynamic

SQL in application programs,” on page 661.

Storing data that does not have a tabular format

Question: How can I store a large volume of data that is not defined as a set of

columns in a table?

Answer: You can store the data in a table in a binary string, a LOB, or an XML

column.

Finding a violated referential or check constraint

Question: When a referential or check constraint has been violated, how do I

determine which one it is?

Answer: When you receive an SQL error because of a constraint violation, print out

the SQLCA. You can use the DSNTIAR routine described in “Calling DSNTIAR to

display SQLCA fields” on page 121 to format the SQLCA for you. Check the SQL

error message insertion text (SQLERRM) for the name of the constraint. For

information about possible violations, see SQLCODEs -530 through -548 in the

topic “Error SQL codes” in DB2 Codes.


||||||

||


Part 7. Appendixes



Appendix A. DB2 sample tables

Most of the examples in this book refer to the tables described in this appendix. As

a group, the tables include information that describes employees, departments,

projects, and activities, and make up a sample application that exemplifies most of

the features of DB2. The sample storage group, databases, tablespaces, tables, and

views are created when you run the installation sample jobs DSNTEJ1 and

DSNTEJ7. DB2 sample objects that include LOBs are created in job DSNTEJ7. All

other sample objects are created in job DSNTEJ1. The CREATE INDEX statements

for the sample tables are not shown here; they, too, are created by the DSNTEJ1

and DSNTEJ7 sample jobs.

Authorization on all sample objects is given to PUBLIC in order to make the

sample programs easier to run. The contents of any table can easily be reviewed by

executing an SQL statement, for example SELECT * FROM DSN8910.PROJ. For

convenience in interpreting the examples, the department and employee tables are

listed here in full.

The following topics provide additional information:

v “Activity table (DSN8910.ACT)”

v “Department table (DSN8910.DEPT)” on page 1084

v “Employee table (DSN8910.EMP)” on page 1086

v “Employee photo and resume table (DSN8910.EMP_PHOTO_RESUME)” on page

1089

v “Project table (DSN8910.PROJ)” on page 1090

v “Project activity table (DSN8910.PROJACT)” on page 1091

v “Employee to project activity table (DSN8910.EMPPROJACT)” on page 1092

v “Unicode sample table (DSN8910.DEMO_UNICODE)” on page 1093

v “Relationships among the sample tables” on page 1094

v “Views on the sample tables” on page 1094

v “Storage of sample application tables” on page 1099

Activity table (DSN8910.ACT)

The activity table describes the activities that can be performed during a project.

The table resides in database DSN8D91A and is created with the following

statement:

CREATE TABLE DSN8910.ACT

(ACTNO SMALLINT NOT NULL,

ACTKWD CHAR(6) NOT NULL,

ACTDESC VARCHAR(20) NOT NULL,

PRIMARY KEY (ACTNO) )

IN DSN8D91A.DSN8S91P

CCSID EBCDIC;

Content of the activity table:


Table 214 shows the content of the columns.

Table 214. Columns of the activity table

Column Column Name Description

1 ACTNO Activity ID (the primary key)

2 ACTKWD Activity keyword (up to six characters)

3 ACTDESC Activity description

The activity table has these indexes:

Table 215. Indexes of the activity table

Name On Column Type of Index

DSN8910.XACT1 ACTNO Primary, ascending

DSN8910.XACT2 ACTKWD Unique, ascending

Relationship to other tables:

The activity table is a parent table of the project activity table, through a foreign

key on column ACTNO.

Department table (DSN8910.DEPT)

The department table describes each department in the enterprise and identifies its

manager and the department to which it reports.

The table, shown in Table 218 on page 1085, resides in table space

DSN8D91A.DSN8S91D and is created with the following statement:

CREATE TABLE DSN8910.DEPT

(DEPTNO CHAR(3) NOT NULL,

DEPTNAME VARCHAR(36) NOT NULL,

MGRNO CHAR(6) ,

ADMRDEPT CHAR(3) NOT NULL,

LOCATION CHAR(16) ,

PRIMARY KEY (DEPTNO) )

IN DSN8D91A.DSN8S91D

CCSID EBCDIC;

Because the table is self-referencing, and also is part of a cycle of dependencies, its

foreign keys must be added later with these statements:

ALTER TABLE DSN8910.DEPT

FOREIGN KEY RDD (ADMRDEPT) REFERENCES DSN8910.DEPT

ON DELETE CASCADE;

ALTER TABLE DSN8910.DEPT

FOREIGN KEY RDE (MGRNO) REFERENCES DSN8910.EMP

ON DELETE SET NULL;

Content of the department table:


Table 216. Columns of the department table


1 DEPTNO Department ID, the primary key


Table 216. Columns of the department table (continued)


2 DEPTNAME A name describing the general activities of the

department

3 MGRNO Employee number (EMPNO) of the department

manager

4 ADMRDEPT ID of the department to which this department

reports; the department at the highest level reports

to itself

5 LOCATION The remote location name

Table 217 shows the indexes of the department table:

Table 217. Indexes of the department table


DSN8910.XDEPT1 DEPTNO Primary, ascending

DSN8910.XDEPT2 MGRNO Ascending

DSN8910.XDEPT3 ADMRDEPT Ascending

Table 218 shows the content of the department table:

Table 218. DSN8910.DEPT: department table

DEPTNO DEPTNAME MGRNO ADMRDEPT LOCATION

A00 SPIFFY COMPUTER SERVICE

DIV.

000010 A00 ----------------

B01 PLANNING 000020 A00 ----------------

C01 INFORMATION CENTER 000030 A00 ----------------

D01 DEVELOPMENT CENTER ------ A00 ----------------

E01 SUPPORT SERVICES 000050 A00 ----------------

D11 MANUFACTURING SYSTEMS 000060 D01 ----------------

D21 ADMINISTRATION SYSTEMS 000070 D01 ----------------

E11 OPERATIONS 000090 E01 ----------------

E21 SOFTWARE SUPPORT 000100 E01 ----------------

F22 BRANCH OFFICE F2 ------ E01 ----------------

G22 BRANCH OFFICE G2 ------ E01 ----------------

H22 BRANCH OFFICE H2 ------ E01 ----------------

I22 BRANCH OFFICE I2 ------ E01 ----------------

J22 BRANCH OFFICE J2 ------ E01 ----------------

The LOCATION column contains nulls until sample job DSNTEJ6 updates this

column with the location name.


The table is self-referencing: the value of the administering department must be a

department ID.

The table is a parent table of:

v The employee table, through a foreign key on column WORKDEPT

v The project table, through a foreign key on column DEPTNO.

Appendix A. DB2 sample tables 1085

It is a dependent of the employee table, through its foreign key on column

MGRNO.

Employee table (DSN8910.EMP)

The employee table identifies all employees by an employee number and lists basic

personnel information.

The table shown in Table 221 on page 1087 and Table 222 on page 1088 resides in

the partitioned table space DSN8D91A.DSN8S91E. Because it has a foreign key

referencing DEPT, that table and the index on its primary key must be created first.

Then EMP is created with the following statement:

CREATE TABLE DSN8910.EMP

(EMPNO CHAR(6) NOT NULL,

FIRSTNME VARCHAR(12) NOT NULL,

MIDINIT CHAR(1) NOT NULL,

LASTNAME VARCHAR(15) NOT NULL,

WORKDEPT CHAR(3) ,

PHONENO CHAR(4) CONSTRAINT NUMBER CHECK

(PHONENO >= ’0000’ AND

PHONENO <= ’9999’) ,

HIREDATE DATE ,

JOB CHAR(8) ,

EDLEVEL SMALLINT ,

SEX CHAR(1) ,

BIRTHDATE DATE ,

SALARY DECIMAL(9,2) ,

BONUS DECIMAL(9,2) ,

COMM DECIMAL(9,2) ,

PRIMARY KEY (EMPNO) ,

FOREIGN KEY RED (WORKDEPT) REFERENCES DSN8910.DEPT

ON DELETE SET NULL )

EDITPROC DSN8EAE1

IN DSN8D91A.DSN8S91E

CCSID EBCDIC;

Content of the employee table:

Table 219 shows the content of the columns. The table has a check constraint,

NUMBER, which checks that the phone number is in the numeric range 0000 to

9999.

Table 219. Columns of the employee table


1 EMPNO Employee number (the primary key)

2 FIRSTNME First name of employee

3 MIDINIT Middle initial of employee

4 LASTNAME Last name of employee

5 WORKDEPT ID of department in which the employee works

6 PHONENO Employee telephone number

7 HIREDATE Date of hire

8 JOB Job held by the employee

9 EDLEVEL Number of years of formal education

10 SEX Sex of the employee (M or F)

11 BIRTHDATE Date of birth


Table 219. Columns of the employee table (continued)


12 SALARY Yearly salary in dollars

13 BONUS Yearly bonus in dollars

14 COMM Yearly commission in dollars

Table 220 shows the indexes of the employee table:

Table 220. Indexes of the employee table


DSN8910.XEMP1 EMPNO Primary, partitioned, ascending

DSN8910.XEMP2 WORKDEPT Ascending

Table 221 and Table 222 on page 1088 show the content of the employee table:

Table 221. Left half of DSN8910.EMP: employee table. Note that a blank in the MIDINIT column is an actual value of

″ ″ rather than null.

EMPNO FIRSTNME MIDINIT LASTNAME WORKDEPT PHONENO HIREDATE

000010 CHRISTINE I HAAS A00 3978 1965-01-01

000020 MICHAEL L THOMPSON B01 3476 1973-10-10

000030 SALLY A KWAN C01 4738 1975-04-05

000050 JOHN B GEYER E01 6789 1949-08-17

000060 IRVING F STERN D11 6423 1973-09-14

000070 EVA D PULASKI D21 7831 1980-09-30

000090 EILEEN W HENDERSON E11 5498 1970-08-15

000100 THEODORE Q SPENSER E21 0972 1980-06-19

000110 VINCENZO G LUCCHESSI A00 3490 1958-05-16

000120 SEAN O’CONNELL A00 2167 1963-12-05

000130 DOLORES M QUINTANA C01 4578 1971-07-28

000140 HEATHER A NICHOLLS C01 1793 1976-12-15

000150 BRUCE ADAMSON D11 4510 1972-02-12

000160 ELIZABETH R PIANKA D11 3782 1977-10-11

000170 MASATOSHI J YOSHIMURA D11 2890 1978-09-15

000180 MARILYN S SCOUTTEN D11 1682 1973-07-07

000190 JAMES H WALKER D11 2986 1974-07-26

000200 DAVID BROWN D11 4501 1966-03-03

000210 WILLIAM T JONES D11 0942 1979-04-11

000220 JENNIFER K LUTZ D11 0672 1968-08-29

000230 JAMES J JEFFERSON D21 2094 1966-11-21

000240 SALVATORE M MARINO D21 3780 1979-12-05

000250 DANIEL S SMITH D21 0961 1969-10-30

000260 SYBIL P JOHNSON D21 8953 1975-09-11

000270 MARIA L PEREZ D21 9001 1980-09-30

000280 ETHEL R SCHNEIDER E11 8997 1967-03-24

000290 JOHN R PARKER E11 4502 1980-05-30

000300 PHILIP X SMITH E11 2095 1972-06-19

000310 MAUDE F SETRIGHT E11 3332 1964-09-12

000320 RAMLAL V MEHTA E21 9990 1965-07-07

000330 WING LEE E21 2103 1976-02-23

000340 JASON R GOUNOT E21 5698 1947-05-05

200010 DIAN J HEMMINGER A00 3978 1965-01-01

200120 GREG ORLANDO A00 2167 1972-05-05


Table 221. Left half of DSN8910.EMP: employee table (continued). Note that a blank in the MIDINIT column is an

actual value of ″ ″ rather than null.

EMPNO FIRSTNME MIDINIT LASTNAME WORKDEPT PHONENO HIREDATE

200140 KIM N NATZ C01 1793 1976-12-15

200170 KIYOSHI YAMAMOTO D11 2890 1978-09-15

200220 REBA K JOHN D11 0672 1968-08-29

200240 ROBERT M MONTEVERDE D21 3780 1979-12-05

200280 EILEEN R SCHWARTZ E11 8997 1967-03-24

200310 MICHELLE F SPRINGER E11 3332 1964-09-12

200330 HELENA WONG E21 2103 1976-02-23

200340 ROY R ALONZO E21 5698 1947-05-05

Table 222. Right half of DSN8910.EMP: employee table

(EMPNO) JOB EDLEVEL SEX BIRTHDATE SALARY BONUS COMM

(000010) PRES 18 F 1933-08-14 52750.00 1000.00 4220.00

(000020) MANAGER 18 M 1948-02-02 41250.00 800.00 3300.00

(000030) MANAGER 20 F 1941-05-11 38250.00 800.00 3060.00

(000050) MANAGER 16 M 1925-09-15 40175.00 800.00 3214.00

(000060) MANAGER 16 M 1945-07-07 32250.00 600.00 2580.00

(000070) MANAGER 16 F 1953-05-26 36170.00 700.00 2893.00

(000090) MANAGER 16 F 1941-05-15 29750.00 600.00 2380.00

(000100) MANAGER 14 M 1956-12-18 26150.00 500.00 2092.00

(000110) SALESREP 19 M 1929-11-05 46500.00 900.00 3720.00

(000120) CLERK 14 M 1942-10-18 29250.00 600.00 2340.00

(000130) ANALYST 16 F 1925-09-15 23800.00 500.00 1904.00

(000140) ANALYST 18 F 1946-01-19 28420.00 600.00 2274.00

(000150) DESIGNER 16 M 1947-05-17 25280.00 500.00 2022.00

(000160) DESIGNER 17 F 1955-04-12 22250.00 400.00 1780.00

(000170) DESIGNER 16 M 1951-01-05 24680.00 500.00 1974.00

(000180) DESIGNER 17 F 1949-02-21 21340.00 500.00 1707.00

(000190) DESIGNER 16 M 1952-06-25 20450.00 400.00 1636.00

(000200) DESIGNER 16 M 1941-05-29 27740.00 600.00 2217.00

(000210) DESIGNER 17 M 1953-02-23 18270.00 400.00 1462.00

(000220) DESIGNER 18 F 1948-03-19 29840.00 600.00 2387.00

(000230) CLERK 14 M 1935-05-30 22180.00 400.00 1774.00

(000240) CLERK 17 M 1954-03-31 28760.00 600.00 2301.00

(000250) CLERK 15 M 1939-11-12 19180.00 400.00 1534.00

(000260) CLERK 16 F 1936-10-05 17250.00 300.00 1380.00

(000270) CLERK 15 F 1953-05-26 27380.00 500.00 2190.00

(000280) OPERATOR 17 F 1936-03-28 26250.00 500.00 2100.00

(000290) OPERATOR 12 M 1946-07-09 15340.00 300.00 1227.00

(000300) OPERATOR 14 M 1936-10-27 17750.00 400.00 1420.00

(000310) OPERATOR 12 F 1931-04-21 15900.00 300.00 1272.00

(000320) FIELDREP 16 M 1932-08-11 19950.00 400.00 1596.00

(000330) FIELDREP 14 M 1941-07-18 25370.00 500.00 2030.00

(000340) FIELDREP 16 M 1926-05-17 23840.00 500.00 1907.00

(200010) SALESREP 18 F 1933-08-14 46500.00 1000.00 4220.00

(200120) CLERK 14 M 1942-10-18 29250.00 600.00 2340.00

(200140) ANALYST 18 F 1946-01-19 28420.00 600.00 2274.00

(200170) DESIGNER 16 M 1951-01-05 24680.00 500.00 1974.00

(200220) DESIGNER 18 F 1948-03-19 29840.00 600.00 2387.00

(200240) CLERK 17 M 1954-03-31 28760.00 600.00 2301.00

(200280) OPERATOR 17 F 1936-03-28 26250.00 500.00 2100.00

(200310) OPERATOR 12 F 1931-04-21 15900.00 300.00 1272.00

(200330) FIELDREP 14 F 1941-07-18 25370.00 500.00 2030.00

(200340) FIELDREP 16 M 1926-05-17 23840.00 500.00 1907.00



The table is a parent table of:

v The department table, through a foreign key on column MGRNO

v The project table, through a foreign key on column RESPEMP.

It is a dependent of the department table, through its foreign key on column

WORKDEPT.

Employee photo and resume table (DSN8910.EMP_PHOTO_RESUME)

The employee photo and resume table complements the employee table. Each row

of the photo and resume table contains a photo of the employee, in two formats,

and the employee″s resume. The photo and resume table resides in table space

DSN8D91A.DSN8S91E. The following statement creates the table:

CREATE TABLE DSN8910.EMP_PHOTO_RESUME


EMP_ROWID ROWID NOT NULL GENERATED ALWAYS,

PSEG_PHOTO BLOB(500K),

BMP_PHOTO BLOB(100K),

RESUME CLOB(5K))

PRIMARY KEY (EMPNO)

IN DSN8D91L.DSN8S91B

CCSID EBCDIC;

DB2 requires an auxiliary table for each LOB column in a table. These statements

define the auxiliary tables for the three LOB columns in

DSN8910.EMP_PHOTO_RESUME:

CREATE AUX TABLE DSN8910.AUX_BMP_PHOTO

IN DSN8D91L.DSN8S91M

STORES DSN8910.EMP_PHOTO_RESUME

COLUMN BMP_PHOTO;

CREATE AUX TABLE DSN8910.AUX_PSEG_PHOTO

IN DSN8D91L.DSN8S91L


COLUMN PSEG_PHOTO;

CREATE AUX TABLE DSN8910.AUX_EMP_RESUME

IN DSN8D91L.DSN8S91N


COLUMN RESUME;

Content of the employee photo and resume table:


Table 223. Columns of the employee photo and resume table


1 EMPNO Employee ID (the primary key)

2 EMP_ROWID Row ID to uniquely identify each row of the table.

DB2 supplies the values of this column.

3 PSEG_PHOTO Employee photo, in PSEG format

4 BMP_PHOTO Employee photo, in BMP format

5 RESUME Employee resume


Table 224 shows the indexes for the employee photo and resume table:

Table 224. Indexes of the employee photo and resume table


DSN8910.XEMP_PHOTO_RESUME EMPNO Primary, ascending

Table 225 shows the indexes for the auxiliary tables for the employee photo and

resume table:

Table 225. Indexes of the auxiliary tables for the employee photo and resume table

Name On Table Type of Index

DSN8910.XAUX_BMP_PHOTO DSN8910.AUX_BMP_PHOTO Unique

DSN8910.XAUX_PSEG_PHOTO DSN8910.AUX_PSEG_PHOTO Unique

DSN8910.XAUX_EMP_RESUME DSN8910.AUX_EMP_RESUME Unique


The table is a parent table of the project table, through a foreign key on column

RESPEMP.

Project table (DSN8910.PROJ)

The project table describes each project that the business is currently undertaking.

Data contained in each row include the project number, name, person responsible,

and schedule dates.

The table resides in database DSN8D91A. Because it has foreign keys referencing

DEPT and EMP, those tables and the indexes on their primary keys must be

created first. Then PROJ is created with the following statement:

CREATE TABLE DSN8910.PROJ

(PROJNO CHAR(6) PRIMARY KEY NOT NULL,

PROJNAME VARCHAR(24) NOT NULL WITH DEFAULT

’PROJECT NAME UNDEFINED’,

DEPTNO CHAR(3) NOT NULL REFERENCES

DSN8910.DEPT ON DELETE RESTRICT,

RESPEMP CHAR(6) NOT NULL REFERENCES

DSN8910.EMP ON DELETE RESTRICT,

PRSTAFF DECIMAL(5, 2) ,

PRSTDATE DATE ,

PRENDATE DATE ,

MAJPROJ CHAR(6))


CCSID EBCDIC;

Because the table is self-referencing, the foreign key for that restraint must be

added later with:

ALTER TABLE DSN8910.PROJ

FOREIGN KEY RPP (MAJPROJ) REFERENCES DSN8910.PROJ

ON DELETE CASCADE;

Content of the project table:



Table 226. Columns of the project table


1 PROJNO Project ID (the primary key)

2 PROJNAME Project name

3 DEPTNO ID of department responsible for the project

4 RESPEMP ID of employee responsible for the project

5 PRSTAFF Estimated mean number of persons needed

between PRSTDATE and PRENDATE to achieve

the whole project, including any subprojects

6 PRSTDATE Estimated project start date

7 PRENDATE Estimated project end date

8 MAJPROJ ID of any project of which this project is a part

Table 227 shows the indexes for the project table:

Table 227. Indexes of the project table


DSN8910.XPROJ1 PROJNO Primary, ascending

DSN8910.XPROJ2 RESPEMP Ascending


The table is self-referencing: a nonnull value of MAJPROJ must be a project

number. The table is a parent table of the project activity table, through a foreign

key on column PROJNO. It is a dependent of:

v The department table, through its foreign key on DEPTNO

v The employee table, through its foreign key on RESPEMP.

Project activity table (DSN8910.PROJACT)

The project activity table lists the activities performed for each project. The table

resides in database DSN8D91A. Because it has foreign keys referencing PROJ and

ACT, those tables and the indexes on their primary keys must be created first.

Then PROJACT is created with the following statement:

CREATE TABLE DSN8910.PROJACT

(PROJNO CHAR(6) NOT NULL,

ACTNO SMALLINT NOT NULL,

ACSTAFF DECIMAL(5,2) ,

ACSTDATE DATE NOT NULL,

ACENDATE DATE ,

PRIMARY KEY (PROJNO, ACTNO, ACSTDATE),

FOREIGN KEY RPAP (PROJNO) REFERENCES DSN8910.PROJ

ON DELETE RESTRICT,

FOREIGN KEY RPAA (ACTNO) REFERENCES DSN8910.ACT

ON DELETE RESTRICT)


CCSID EBCDIC;

Content of the project activity table:



Table 228. Columns of the project activity table


1 PROJNO Project ID

2 ACTNO Activity ID

3 ACSTAFF Estimated mean number of employees needed to

staff the activity

4 ACSTDATE Estimated activity start date

5 ACENDATE Estimated activity completion date

Table 229 shows the index of the project activity table:

Table 229. Index of the project activity table

Name On Columns Type of Index

DSN8910.XPROJAC1 PROJNO, ACTNO,

ACSTDATE

primary, ascending


The table is a parent table of the employee to project activity table, through a

foreign key on columns PROJNO, ACTNO, and EMSTDATE. It is a dependent of:

v The activity table, through its foreign key on column ACTNO

v The project table, through its foreign key on column PROJNO

Employee to project activity table (DSN8910.EMPPROJACT)

The employee to project activity table identifies the employee who performs an

activity for a project, tells the proportion of the employee’s time required, and

gives a schedule for the activity.

The table resides in database DSN8D91A. Because it has foreign keys referencing

EMP and PROJACT, those tables and the indexes on their primary keys must be

created first. Then EMPPROJACT is created with the following statement:

CREATE TABLE DSN8910.EMPPROJACT


PROJNO CHAR(6) NOT NULL,

ACTNO SMALLINT NOT NULL,

EMPTIME DECIMAL(5,2) ,

EMSTDATE DATE ,

EMENDATE DATE ,

FOREIGN KEY REPAPA (PROJNO, ACTNO, EMSTDATE)

REFERENCES DSN8910.PROJACT

ON DELETE RESTRICT,

FOREIGN KEY REPAE (EMPNO) REFERENCES DSN8910.EMP

ON DELETE RESTRICT)


CCSID EBCDIC;

Content of the employee to project activity table:



Table 230. Columns of the employee to project activity table


1 EMPNO Employee ID number

2 PROJNO Project ID of the project

3 ACTNO ID of the activity within the project

4 EMPTIME A proportion of the employee’s full time (between

0.00 and 1.00) to be spent on the activity

5 EMSTDATE Date the activity starts

6 EMENDATE Date the activity ends

Table 231 shows the indexes for the employee to project activity table:

Table 231. Indexes of the employee to project activity table

Name On Columns Type of Index

DSN8910.XEMPPROJACT1 PROJNO, ACTNO,

EMSTDATE, EMPNO

Unique, ascending

DSN8910.XEMPPROJACT2 EMPNO Ascending


The table is a dependent of:

v The employee table, through its foreign key on column EMPNO

v The project activity table, through its foreign key on columns PROJNO, ACTNO,

and EMSTDATE.

Unicode sample table (DSN8910.DEMO_UNICODE)

The Unicode sample table is used to verify that data conversions to and from

EBCDIC and Unicode are working as expected. The table resides in database

DSN8D91A, and is defined with the following statement:

CREATE TABLE DSN8910.DEMO_UNICODE

(LOWER_A_TO_Z CHAR(26) ,

UPPER_A_TO_Z CHAR(26) ,

ZERO_TO_NINE CHAR(10) ,

X00_TO_XFF VARCHAR(256) FOR BIT DATA)

IN DSN8D81E.DSN8S81U

CCSID UNICODE;

Content of the Unicode sample table:

Table 232 shows the content of the columns:

Table 232. Columns of the Unicode sample table


1 LOWER_A_TO_Z Array of characters, ’a’ to ’z’

2 UPPER_A_TO_Z Array of characters, ’A’ to ’Z’

3 ZERO_TO_NINE Array of characters, ’0’ to ’9’


Table 232. Columns of the Unicode sample table (continued)


4 X00_TO_XFF Array of characters, x’00’ to x’FF’

This table has no indexes


This table has no relationship to other tables.

Relationships among the sample tables

Figure 268 shows relationships among the tables. These are established by foreign

keys in dependent tables that reference primary keys in parent tables. You can find

descriptions of the columns with descriptions of the tables.

Views on the sample tables

DB2 creates a number of views on the sample tables for use in the sample

applications. Table 234 indicates the tables on which each view is defined and the

sample applications that use the view. All view names have the qualifier DSN8910.

Table 234. Views on sample tables

View name On tables or views Used in application

VDEPT DEPT Organization

Project

CASCADE

CASCADERESTRICT

RESTRICT

RESTRICT

RESTRICT

RESTRICT

RESTRICT

RESTRICT

RESTRICT

SETNULL

SETNULL

DEPT

EMP

PROJ

ACT

PROJACT

EMPPROJACT

EMP_PHOTO_RESUME

Figure 268. Relationships among tables in the sample application


Table 234. Views on sample tables (continued)

View name On tables or views Used in application

VHDEPT DEPT Distributed organization

VEMP EMP Distributed organization

Organization

Project

VPROJ PROJ Project

VACT ACT Project

VPROJACT PROJACT Project

VEMPPROJACT EMPROJACT Project

VDEPMG1 DEPT

EMP

Organization

VEMPDPT1 DEPT

EMP

Organization

VASTRDE1 DEPT

VASTRDE2 VDEPMG1

EMP

Organization

VPROJRE1 PROJ

EMP

Project

VPSTRDE1 VPROJRE1

VPROJRE2

Project

VPSTRDE2 VPROJRE1 Project

VFORPLA VPROJRE1

EMPPROJACT

Project

VSTAFAC1 PROJACT

ACT

Project

VSTAFAC2 EMPPROJACT

ACT

EMP

Project

VPHONE EMP

DEPT

Phone

VEMPLP EMP Phone

The following SQL statements are used to create the sample views:

CREATE VIEW DSN8910.VDEPT

AS SELECT ALL DEPTNO ,

DEPTNAME,

MGRNO ,

ADMRDEPT

FROM DSN8910.DEPT;

Figure 269. VDEPT


CREATE VIEW DSN8910.VHDEPT

AS SELECT ALL DEPTNO ,

DEPTNAME,

MGRNO ,

ADMRDEPT,

LOCATION

FROM DSN8910.DEPT;

Figure 270. VHDEPT

CREATE VIEW DSN8910.VEMP

AS SELECT ALL EMPNO ,

FIRSTNME,

MIDINIT ,

LASTNAME,

WORKDEPT

FROM DSN8910.EMP;

Figure 271. VEMP

CREATE VIEW DSN8910.VPROJ

AS SELECT ALL

PROJNO, PROJNAME, DEPTNO, RESPEMP, PRSTAFF,

PRSTDATE, PRENDATE, MAJPROJ

FROM DSN8910.PROJ ;

Figure 272. VPROJ

CREATE VIEW DSN8910.VACT

AS SELECT ALL ACTNO ,

ACTKWD ,

ACTDESC

FROM DSN8910.ACT ;

Figure 273. VACT

CREATE VIEW DSN8910.VPROJACT

AS SELECT ALL

PROJNO,ACTNO, ACSTAFF, ACSTDATE, ACENDATE

FROM DSN8910.PROJACT ;

Figure 274. VPROJACT

CREATE VIEW DSN8910.VEMPPROJACT

AS SELECT ALL

EMPNO, PROJNO, ACTNO, EMPTIME, EMSTDATE, EMENDATE

FROM DSN8910.EMPPROJACT ;

Figure 275. VEMPPROJACT

CREATE VIEW DSN8910.VDEPMG1

(DEPTNO, DEPTNAME, MGRNO, FIRSTNME, MIDINIT,

LASTNAME, ADMRDEPT)

AS SELECT ALL

DEPTNO, DEPTNAME, EMPNO, FIRSTNME, MIDINIT,

LASTNAME, ADMRDEPT

FROM DSN8910.DEPT LEFT OUTER JOIN DSN8910.EMP

ON MGRNO = EMPNO ;

Figure 276. VDEPMG1


CREATE VIEW DSN8910.VEMPDPT1

(DEPTNO, DEPTNAME, EMPNO, FRSTINIT, MIDINIT,

LASTNAME, WORKDEPT)

AS SELECT ALL

DEPTNO, DEPTNAME, EMPNO, SUBSTR(FIRSTNME, 1, 1), MIDINIT,

LASTNAME, WORKDEPT

FROM DSN8910.DEPT RIGHT OUTER JOIN DSN8910.EMP

ON WORKDEPT = DEPTNO ;

Figure 277. VEMPDPT1

CREATE VIEW DSN8910.VASTRDE1

(DEPT1NO,DEPT1NAM,EMP1NO,EMP1FN,EMP1MI,EMP1LN,TYPE2,

DEPT2NO,DEPT2NAM,EMP2NO,EMP2FN,EMP2MI,EMP2LN)

AS SELECT ALL

D1.DEPTNO,D1.DEPTNAME,D1.MGRNO,D1.FIRSTNME,D1.MIDINIT,

D1.LASTNAME, ’1’,


D2.LASTNAME

FROM DSN8910.VDEPMG1 D1, DSN8910.VDEPMG1 D2

WHERE D1.DEPTNO = D2.ADMRDEPT ;

Figure 278. VASTRDE1

CREATE VIEW DSN8910.VASTRDE2

(DEPT1NO,DEPT1NAM,EMP1NO,EMP1FN,EMP1MI,EMP1LN,TYPE2,

DEPT2NO,DEPT2NAM,EMP2NO,EMP2FN,EMP2MI,EMP2LN)

AS SELECT ALL


D1.LASTNAME,’2’,

D1.DEPTNO,D1.DEPTNAME,E2.EMPNO,E2.FIRSTNME,E2.MIDINIT,

E2.LASTNAME

FROM DSN8910.VDEPMG1 D1, DSN8910.EMP E2

WHERE D1.DEPTNO = E2.WORKDEPT;

Figure 279. VASTRDE2

CREATE VIEW DSN8910.VPROJRE1

(PROJNO,PROJNAME,PROJDEP,RESPEMP,FIRSTNME,MIDINIT,

LASTNAME,MAJPROJ)

AS SELECT ALL

PROJNO,PROJNAME,DEPTNO,EMPNO,FIRSTNME,MIDINIT,

LASTNAME,MAJPROJ

FROM DSN8910.PROJ, DSN8910.EMP

WHERE RESPEMP = EMPNO ;

Figure 280. VPROJRE1

CREATE VIEW DSN8910.VPSTRDE1

(PROJ1NO,PROJ1NAME,RESP1NO,RESP1FN,RESP1MI,RESP1LN,

PROJ2NO,PROJ2NAME,RESP2NO,RESP2FN,RESP2MI,RESP2LN)

AS SELECT ALL

P1.PROJNO,P1.PROJNAME,P1.RESPEMP,P1.FIRSTNME,P1.MIDINIT,

P1.LASTNAME,


P2.LASTNAME

FROM DSN8910.VPROJRE1 P1,

DSN8910.VPROJRE1 P2

WHERE P1.PROJNO = P2.MAJPROJ ;

Figure 281. VPSTRDE1


CREATE VIEW DSN8910.VPSTRDE2

(PROJ1NO,PROJ1NAME,RESP1NO,RESP1FN,RESP1MI,RESP1LN,

PROJ2NO,PROJ2NAME,RESP2NO,RESP2FN,RESP2MI,RESP2LN)

AS SELECT ALL


P1.LASTNAME,


P1.LASTNAME

FROM DSN8910.VPROJRE1 P1

WHERE NOT EXISTS

(SELECT * FROM DSN8910.VPROJRE1 P2

WHERE P1.PROJNO = P2.MAJPROJ) ;

Figure 282. VPSTRDE2

CREATE VIEW DSN8910.VFORPLA

(PROJNO,PROJNAME,RESPEMP,PROJDEP,FRSTINIT,MIDINIT,LASTNAME)

AS SELECT ALL

F1.PROJNO,PROJNAME,RESPEMP,PROJDEP, SUBSTR(FIRSTNME, 1, 1),

MIDINIT, LASTNAME

FROM DSN8910.VPROJRE1 F1 LEFT OUTER JOIN DSN8910.EMPPROJACT F2

ON F1.PROJNO = F2.PROJNO;

Figure 283. VFORPLA

CREATE VIEW DSN8910.VSTAFAC1

(PROJNO, ACTNO, ACTDESC, EMPNO, FIRSTNME, MIDINIT, LASTNAME,

EMPTIME,STDATE,ENDATE, TYPE)

AS SELECT ALL

PA.PROJNO, PA.ACTNO, AC.ACTDESC,’ ’, ’ ’, ’ ’, ’ ’,

PA.ACSTAFF, PA.ACSTDATE,

PA.ACENDATE,’1’

FROM DSN8910.PROJACT PA, DSN8910.ACT AC

WHERE PA.ACTNO = AC.ACTNO ;

Figure 284. VSTAFAC1

CREATE VIEW DSN8910.VSTAFAC2

(PROJNO, ACTNO, ACTDESC, EMPNO, FIRSTNME, MIDINIT, LASTNAME,

EMPTIME,STDATE, ENDATE, TYPE)

AS SELECT ALL

EP.PROJNO, EP.ACTNO, AC.ACTDESC, EP.EMPNO,EM.FIRSTNME,

EM.MIDINIT, EM.LASTNAME, EP.EMPTIME, EP.EMSTDATE,

EP.EMENDATE,’2’

FROM DSN8910.EMPPROJACT EP, DSN8910.ACT AC, DSN8910.EMP EM

WHERE EP.ACTNO = AC.ACTNO AND EP.EMPNO = EM.EMPNO ;

Figure 285. VSTAFAC2


Storage of sample application tables

Figure 288 shows how the sample tables are related to databases and storage

groups. Two databases are used to illustrate the possibility. Normally, related data

is stored in the same database.

In addition to the storage group and databases shown in Figure 288, the storage

group DSN8G91U and database DSN8D91U are created when you run DSNTEJ2A.

CREATE VIEW DSN8910.VPHONE

(LASTNAME,

FIRSTNAME,

MIDDLEINITIAL,

PHONENUMBER,

EMPLOYEENUMBER,

DEPTNUMBER,

DEPTNAME)

AS SELECT ALL LASTNAME,

FIRSTNME,

MIDINIT ,

VALUE(PHONENO,’ ’),

EMPNO,

DEPTNO,

DEPTNAME

FROM DSN8910.EMP, DSN8910.DEPT

WHERE WORKDEPT = DEPTNO;

Figure 286. VPHONE

CREATE VIEW DSN8910.VEMPLP

(EMPLOYEENUMBER,

PHONENUMBER)

AS SELECT ALL EMPNO ,

PHONENO

FROM DSN8910.EMP ;

Figure 287. VEMPLP

Storage group:

Databases:

Tablespaces:

DSN8G 0vr

DSN8D Aapplication

data

vr DSN8D Pcommon for

programmingtables

vr

DSN8S Ddepartment

table

vr DSN8S Eemployee

table

vr

Separatespaces for

otherapplication

tables

DSN8S Pcommon for

programmingtables

vr

vr is a 2-digit version identifer.

LOB spacesfor employee

photo andresume table

DSN8D LLOB application

data

vr

Figure 288. Relationship among sample databases and table spaces


Storage group for sample application data

The default storage group, SYSDEFLT, created when DB2 is installed, is not used to

store sample application data. The storage group used to store sample application

data is defined by this statement:

CREATE STOGROUP DSN8G910

VOLUMES (DSNV01)

VCAT DSNC910;

Databases

The default database, created when DB2 is installed, is not used to store the

sample application data. DSN8D81P is the database that is used for tables that are

related to programs. The remainder of the databases are used for tables that are

related to applications. They are defined by the following statements:

CREATE DATABASE DSN8D91A

STOGROUP DSN8G910

BUFFERPOOL BP0

CCSID EBCDIC;

CREATE DATABASE DSN8D91P

STOGROUP DSN8G910

BUFFERPOOL BP0

CCSID EBCDIC;

CREATE DATABASE DSN8D91L

STOGROUP DSN8G910

BUFFERPOOL BP0

CCSID EBCDIC;

CREATE DATABASE DSN8D81E

STOGROUP DSN8G810

BUFFERPOOL BP0

CCSID UNICODE;

CREATE DATABASE DSN8D81U

STOGROUP DSN8G81U

CCSID EBCDIC;

Table spaces

The following table spaces are explicitly defined by the following statements. The

table spaces not explicitly defined are created implicitly in the DSN8D91A

database, using the default space attributes.

CREATE TABLESPACE DSN8S91D

IN DSN8D91A

USING STOGROUP DSN8G910

PRIQTY 20

SECQTY 20

ERASE NO

LOCKSIZE PAGE LOCKMAX SYSTEM

BUFFERPOOL BP0

CLOSE NO

CCSID EBCDIC;

CREATE TABLESPACE DSN8S91E

IN DSN8D91A


PRIQTY 20

SECQTY 20

ERASE NO

NUMPARTS 4

(PART 1 USING STOGROUP DSN8G910

PRIQTY 12


SECQTY 12,

PART 3 USING STOGROUP DSN8G910

PRIQTY 12

SECQTY 12)


BUFFERPOOL BP0

CLOSE NO

COMPRESS YES

CCSID EBCDIC;

CREATE TABLESPACE DSN8S91B

IN DSN8D91L


PRIQTY 20

SECQTY 20

ERASE NO

LOCKSIZE PAGE

LOCKMAX SYSTEM

BUFFERPOOL BP0

CLOSE NO

CCSID EBCDIC;

CREATE LOB TABLESPACE DSN8S91M

IN DSN8D91L

LOG NO;

CREATE LOB TABLESPACE DSN8S91L

IN DSN8D91L

LOG NO;

CREATE LOB TABLESPACE DSN8S91N

IN DSN8D91L

LOG NO;

CREATE TABLESPACE DSN8S91C

IN DSN8D91P


PRIQTY 160

SECQTY 80

SEGSIZE 4

LOCKSIZE TABLE

BUFFERPOOL BP0

CLOSE NO

CCSID EBCDIC;

CREATE TABLESPACE DSN8S91P

IN DSN8D91A


PRIQTY 160

SECQTY 80

SEGSIZE 4

LOCKSIZE ROW

BUFFERPOOL BP0

CLOSE NO

CCSID EBCDIC;

CREATE TABLESPACE DSN8S91R

IN DSN8D91A


PRIQTY 20

SECQTY 20

ERASE NO


BUFFERPOOL BP0

CLOSE NO

CCSID EBCDIC;

CREATE TABLESPACE DSN8S91S

IN DSN8D91A



PRIQTY 20

SECQTY 20

ERASE NO


BUFFERPOOL BP0

CLOSE NO

CCSID EBCDIC;

CREATE TABLESPACE DSN8S81Q

IN DSN8D81P


PRIQTY 160

SECQTY 80

SEGSIZE 4

LOCKSIZE PAGE

BUFFERPOOL BP0

CLOSE NO

CCSID EBCDIC;

CREATE TABLESPACE DSN8S81U

IN DSN8D81E


PRIQTY 5

SECQTY 5

ERASE NO


BUFFERPOOL BP0

CLOSE NO

CCSID UNICODE;


Appendix B. Sample applications

This topic describes the DB2 sample applications and the environments under

which each application runs. It also provides information on how to use the

applications, and how to print the application listings.

Several sample applications come with DB2 to help you with DB2 programming

techniques and coding practices within each of the four environments: batch, TSO,

IMS, and CICS. The sample applications contain various applications that might

apply to managing to company.

You can examine the source code for the sample application programs in the online

sample library included with the DB2 product. The name of this sample library is

prefix.SDSNSAMP.

Types of sample applications

Organization application: The organization application manages the following

company information:

v Department administrative structure

v Individual departments

v Individual employees.

Management of information about department administrative structures involves

how departments relate to other departments. You can view or change the

organizational structure of an individual department, and the information about

individual employees in any department. The organization application runs

interactively in the ISPF/TSO, IMS, and CICS environments and is available in

PL/I and COBOL.

Project application: The project application manages information about a

company’s project activities, including the following:

v Project structures

v Project activity listings

v Individual project processing

v Individual project activity estimate processing

v Individual project staffing processing.

Each department works on projects that contain sets of related activities.

Information available about these activities includes staffing assignments,

completion-time estimates for the project as a whole, and individual activities

within a project. The project application runs interactively in IMS and CICS and is

available in PL/I only.

Phone application: The phone application lets you view or update individual

employee phone numbers. There are different versions of the application for

ISPF/TSO, CICS, IMS, and batch:

v ISPF/TSO applications use COBOL and PL/I.

v CICS and IMS applications use PL/I.

v Batch applications use C, C++, COBOL, FORTRAN, and PL/I.

Stored procedure applications: There are three sets of stored procedure

applications:


v IFI applications

These applications let you pass DB2 commands from a client program to a

stored procedure, which runs the commands at a DB2 server using the

instrumentation facility interface (IFI). There are two sets of client programs and

stored procedures. One set has a PL/I client and stored procedure; the other set

has a C client and stored procedure.

v ODBA application

This application demonstrates how you can use the IMS ODBA interface to

access IMS databases from stored procedures. The stored procedure accesses the

IMS sample DL/I database. The client program and the stored procedure are

written in COBOL.

v Utilities stored procedure application

This application demonstrates how to call the utilities stored procedure.

v SQL procedure applications

Sample applications are available for both external SQL procedures and native

SQL procedures:

– The applications for external SQL procedures demonstrate how to write,

prepare, and invoke such procedures. One set of applications demonstrates

how to prepare SQL procedures using JCL. The other set of applications

shows how to prepare SQL procedures using the SQL procedure processor.

The client programs are written in C.

– The sample job for a native SQL procedure shows how to prepare a native

SQL procedure, how to manage versions of native SQL procedures, and

optionally, how to deploy a native SQL procedure to a remote server. The

sample also prepares and executes a sample caller in the C languagev WLM refresh application

This application is a client program that calls the DB2–supplied stored procedure

WLM_REFRESH to refresh a WLM environment. This program is written in C.

v System parameter reporting application

This application is a client program that calls the DB2–supplied stored procedure

DSNWZP to display the current settings of system parameters. This program is

written in C.

All stored procedure applications run in the TSO batch environment.

User-defined function applications: The user-defined function applications consist

of a client program that invokes the sample user-defined functions and a set of

user-defined functions that perform the following functions:

v Convert the current date to a user-specified format

v Convert a date from one format to another

v Convert the current time to a user-specified format

v Convert a date from one format to another

v Return the day of the week for a user-specified date

v Return the month for a user-specified date

v Format a floating point number as a currency value

v Return the table name for a table, view, or alias

v Return the qualifier for a table, view or alias

v Return the location for a table, view or alias

v Return a table of weather information

All programs are written in C or C++ and run in the TSO batch environment.

LOB application: The LOB application demonstrates how to perform the following

tasks:


||

|||||

||||

v Define DB2 objects to hold LOB data

v Populate DB2 tables with LOB data using the LOAD utility, or using INSERT

and UPDATE statements when the data is too large for use with the LOAD

utility

v Manipulate the LOB data using LOB locators

The programs that create and populate the LOB objects use DSNTIAD and run in

the TSO batch environment. The program that manipulates the LOB data is written

in C and runs under ISPF/TSO.

Using the sample applications

You can use the applications interactively by accessing data in the sample tables on

screen displays (panels). You can also access the sample tables in batch when using

the phone applications. All sample objects have PUBLIC authorization, which

makes the samples easier to run.

Application languages and environments:Table 235 shows the environments under

which each application runs, and the languages the applications use for each

environment.

Table 235. Application languages and environments

Programs ISPF/TSO IMS CICS Batch SPUFI

Dynamic SQL

programs

Assembler

PL/I

Exit routines Assembler Assembler Assembler Assembler Assembler

Organization COBOL COBOL

PL/I

COBOL

PL/I

Phone COBOL

PL/I

Assembler1

PL/I PL/I COBOL

FORTRAN

PL/I

C

C++

Project PL/I PL/I

SQLCA

formatting

routines

Assembler Assembler Assembler Assembler

Stored

procedures

COBOL PL/I

C

SQL

User-defined

functions

C

C++

LOBs C

Notes:

1. Assembler subroutine DSN8CA.

Appendix B. Sample applications 1105

Application programs: Tables 236 through 238 on pages 1106 through 1108 provide

the program names, JCL member names, and a brief description of some of the

programs included for each of the three environments: TSO, IMS, and CICS.

Sample applications in TSO

Table 236. Sample DB2 applications for TSO

Application Program name

Preparation

JCL member

name

Attachment

facility Description

Phone DSN8BC3 DSNTEJ2C DSNELI This COBOL batch program lists employee

telephone numbers and updates them if

requested.

Phone DSN8BD3 DSNTEJ2D DSNELI This C batch program lists employee telephone

numbers and updates them if requested.

Phone DSN8BE3 DSNTEJ2E DSNELI This C++ batch program lists employee


requested.

Phone DSN8BP3 DSNTEJ2P DSNELI This PL/I batch program lists employee


requested.

Phone DSN8BF3 DSNTEJ2F DSNELI This FORTRAN program lists employee


requested.

Organization DSN8HC3 DSNTEJ3C or

DSNTEJ6

DSNALI This COBOL ISPF program displays and

updates information about a local department. It

can also display and update information about

an employee at a local or remote location.

Phone DSN8SC3 DSNTEJ3C DSNALI This COBOL ISPF program lists employee


requested.

Phone DSN8SP3 DSNTEJ3P DSNALI This PL/I ISPF program lists employee


requested.

UNLOAD DSNTIAUL DSNTEJ2A DSNELI This assembler language program unloads the

data from a table or view and to produce LOAD

utility control statements for the data.

Dynamic SQL DSNTIAD DSNTIJTM DSNELI This assembler language program dynamically

executes non-SELECT statements read in from

SYSIN; that is, it uses dynamic SQL to execute

non-SELECT SQL statements.

Dynamic SQL DSNTEP2 DSNTEJ1P or

DSNTEJ1L

DSNELI This PL/I program dynamically executes SQL

statements read in from SYSIN. Unlike

DSNTIAD, this application can also execute

SELECT statements.

Stored

procedures1

DSN8EP1 DSNTEJ6P DSNELI The jobs DSNTEJ6P and DSNTEJ6S prepare a

PL/I version of the application. This sample

executes DB2 commands using the

instrumentation facility interface (IFI).

Stored

procedure1

DSN8EP2 DSNTEJ6S DSNRLI

Stored

procedures1

DSN8EPU DSNTEJ6U DSNELI The sample that is prepared by job DSNTEJ6U

invokes the utilities stored procedure.


|

Table 236. Sample DB2 applications for TSO (continued)


Preparation

JCL member

name

Attachment


Stored

procedures1

DSN8ED1 DSNTEJ6D DSNELI The jobs DSNTEJ6D and DSNTEJ6T prepare a C

version of the application. The C stored

procedure uses result sets to return commands

to the client. This sample executes DB2

commands using the instrumentation facility

interface (IFI).

Stored

procedures1

DSN8ED2 DSNTEJ6T DSNRLI

Stored

procedures1

DSN8EC1 DSNTEJ61 DSNRLI The sample that is prepared by jobs DSNTEJ61

and DSNTEJ62 demonstrates a stored procedure

that accesses IMS databases through the ODBA

interface.

Stored

procedures1

DSN8EC2 DSNTEJ62 DSNELI

Stored

procedures1

DSN8ES1 DSNTEJ63 DSNRLI The sample that is prepared by jobs DSNTEJ63

and DSNTEJ64 demonstrates how to prepare an

SQL procedure using JCL. Stored

procedures1

DSN8ED3 DSNTEJ64 DSNELI

Stored

procedures1

DSN8ES2 DSNTEJ65 DSNRLI The sample that is prepared by job DSNTEJ65

demonstrates how to prepare an SQL procedure

using the SQL procedure processor.

Stored

procedures1

DSN8ED6 DSNTEJ6W DSNELI The sample that is prepared by job DSNTEJ6W

demonstrates how to prepare and run a client

program that calls a DB2–supplied stored

procedure to refresh a WLM environment.

Stored

procedures1

DSN8ED7 DSNTEJ6Z DSNELI The sample that is prepared by job DSNTEJ6Z


program that calls a DB2–supplied stored

procedure to display the current settings of

system parameters.

Stored

procedures1

DSN8ED9 DSNTEJ66 DSNELI The sample that is prepared by job DSNTEJ66


program that calls a native SQL procedure,

manages versions of that procedure, and

optionally, deploys that procedure to a remote

server. DSN8ES3 is the sample native SQL

procedure and DSN8ED9 is the sample C

language caller of DSN8ES3.

Stored

procedures1

DSN8ES3 DSNTEJ66 not applicable

User-defined

functions

DSN8DUAD DSNTEJ2U DSNRLI These C applications consist of a set of

user-defined scalar functions that can be

invoked through SPUFI or DSNTEP2. User-defined

functions

DSN8DUAT DSNTEJ2U DSNRLI

User-defined

functions

DSN8DUCD DSNTEJ2U DSNRLI

User-defined

functions

DSN8DUCT DSNTEJ2U DSNRLI

User-defined

functions

DSN8DUCY DSNTEJ2U DSNRLI

User-defined

functions

DSN8DUTI DSNTEJ2U DSNRLI


|

|

|

|

|||||||||||||

|||||

|

|

|

|

|

|

Table 236. Sample DB2 applications for TSO (continued)


Preparation

JCL member

name

Attachment


User-defined

functions

DSN8DUWC DSNTEJ2U DSNRLI The user-defined table function DSN8DUWF

can be invoked by the C client program

DSN8DUWC. User-defined

functions

DSN8DUWF DSNTEJ2U DSNRLI

User-defined

functions

DSN8EUDN DSNTEJ2U DSNRLI These C++ applications consist of a set of

user-defined scalar functions that can be

invoked through SPUFI or DSNTEP2. User-defined

functions

DSN8EUMN DSNTEJ2U DSNRLI

LOBs DSN8DLPL DSNTEJ71 DSNELI These applications demonstrate how to populate

a LOB column that is greater than 32 KB,

manipulate the data using the POSSTR and

SUBSTR built-in functions, and display the data

in ISPF using GDDM®.

LOBs DSN8DLCT DSNTEJ71 DSNELI

LOBs DSN8DLRV DSNTEJ73 DSNELI

LOBs DSN8DLPV DSNTEJ75 DSNELI

Notes:

1. All of the stored procedure applications consist of a calling program, a stored

procedure program, or both.

Sample applications in IMS

Table 237. Sample DB2 applications for IMS

Application Program name JCL member name Description

Organization DSN8IC0

DSN8IC1

DSN8IC2

DSNTEJ4C IMS COBOL

Organization

Application

Organization DSN8IP0

DSN8IP1

DSN8IP2

DSNTEJ4P IMS PL/I

Organization

Application

Project DSN8IP6

DSN8IP7

DSN8IP8

DSNTEJ4P IMS PL/I Project

Application

Phone DSN8IP3 DSNTEJ4P IMS PL/I Phone

Application. This

program lists

employee telephone

numbers and updates

them if requested.

Sample applications in CICS

Table 238. Sample DB2 applications for CICS


Organization DSN8CC0

DSN8CC1

DSN8CC2

DSNTEJ5C CICS COBOL

Organization

Application


|

|

|

|

Table 238. Sample DB2 applications for CICS (continued)


Organization DSN8CP0

DSN8CP1

DSN8CP2

DSNTEJ5P CICS PL/I

Organization

Application

Project DSN8CP6

DSN8CP7

DSN8CP8

DSNTEJ5P CICS PL/I Project

Application

Phone DSN8CP3 DSNTEJ5P CICS PL/I Phone

Application. This

program lists

employee telephone

numbers and updates

them if requested.



Appendix C. Running the productivity-aid sample programs

DB2 provides four sample programs that many users find helpful as productivity

aids. These programs are shipped as source code, so you can modify them to meet

your needs. The programs are:

DSNTIAUL The sample unload program. This program, which is written in

assembler language, is a simple alternative to the UNLOAD utility.

It unloads some or all rows from up to 100 DB2 tables. With

DSNTIAUL, you can unload data of any DB2 built-in data type or

distinct type. DSNTIAUL unloads the rows in a form that is

compatible with the LOAD utility and generates utility control

statements for LOAD. DSNTIAUL also lets you execute any SQL

non-SELECT statement that can be executed dynamically. See

“Running DSNTIAUL” on page 1112.

DSNTIAD A sample dynamic SQL program that is written in assembler

language. With this program, you can execute any SQL statement

that can be executed dynamically, except a SELECT statement. See

“Running DSNTIAD” on page 1118.

DSNTEP2 A sample dynamic SQL program that is written in the PL/I

language. With this program, you can execute any SQL statement

that can be executed dynamically. You can use the source version

of DSNTEP2 and modify it to meet your needs, or, if you do not

have a PL/I compiler at your installation, you can use the object

code version of DSNTEP2. See “Running DSNTEP2 and DSNTEP4”

on page 1119.

DSNTEP4 A sample dynamic SQL program that is written in the PL/I

language. This program is identical to DSNTEP2 except DSNTEP4

uses multi-row fetch for increased performance. You can use the

source version of DSNTEP4 and modify it to meet your needs, or,

if you do not have a PL/I compiler at your installation, you can

use the object code version of DSNTEP4. See “Running DSNTEP2

and DSNTEP4” on page 1119.

Because these four programs also accept the static SQL statements CONNECT, SET

CONNECTION, and RELEASE, you can use the programs to access DB2 tables at

remote locations.

Retrieval of UTF-16 Unicode data: You can use DSNTEP2, DSNTEP4, and

DSNTIAUL to retrieve Unicode UTF-16 graphic data. However, these programs

might not be able to display some characters, if those characters have no mapping

in the target SBCS EBCDIC CCSID.

DSNTIAUL and DSNTIAD are shipped only as source code, so you must

precompile, assemble, link, and bind them before you can use them. If you want to

use the source code version of DSNTEP2 or DSNTEP4, you must precompile,

compile, link, and bind it. You need to bind the object code version of DSNTEP2 or

DSNTEP4 before you can use it. Usually a system administrator prepares the

programs as part of the installation process. Table 239 on page 1112 indicates which

installation job prepares each sample program. All installation jobs are in data set

DSN910.SDSNSAMP.


Table 239. Jobs that prepare DSNTIAUL, DSNTIAD, DSNTEP2, and DSNTEP4

Program name Program preparation job

DSNTIAUL DSNTEJ2A

DSNTIAD DSNTIJTM

DSNTEP2 (source) DSNTEJ1P

DSNTEP2 (object) DSNTEJ1L

DSNTEP4 (source) DSNTEJ1P

DSNTEP4 (object) DSNTEJ1L

To run the sample programs, use the DSN RUN command. For more information

about the DSN RUN command, see the topic “RUN (DSN)” in DB2 Command

Reference.

Table 240 lists the load module name and plan name that you must specify, and

the parameters that you can specify when you run each program. See the following

sections for the meaning of each parameter.

Table 240. DSN RUN option values for DSNTIAUL, DSNTIAD, DSNTEP2, and DSNTEP4

Program name Load module Plan Parameters

DSNTIAUL DSNTIAUL DSNTIB91 SQL

number of rows per fetch

TOLWARN(NO|YES)

DSNTIAD DSNTIAD DSNTIA91 RC0

SQLTERM(termchar)

DSNTEP2 DSNTEP2 DSNTEP91 ALIGN(MID)

or ALIGN(LHS)

NOMIXED or MIXED

SQLTERM(termchar)

TOLWARN(NO|YES)

PREPWARN

DSNTEP4 DSNTEP4 DSNTP491 ALIGN(MID)

or ALIGN(LHS)

NOMIXED or MIXED

SQLTERM(termchar)

TOLWARN(NO|YES)

PREPWARN

The remainder of this chapter contains the following information about running

each program:

v Descriptions of the input parameters

v Data sets that you must allocate before you run the program

v Return codes from the program

v Examples of invocation

See the sample jobs that are listed in Table 239 for a working example of each

program.

Running DSNTIAUL

This topic contains information that you need when you run DSNTIAUL,

including parameters, data sets, return codes, and invocation examples.


|

|

To retrieve data from a remote site by using the multi-row fetch capability for

enhanced performance, bind DSNTIAUL with the DBPROTOCOL(DRDA) option.

To run DSNTIAUL remotely when it is bound with the DBPROTOCOL(PRIVATE)

option, switch DSNTIAUL to single-row fetch mode by specifying 1 for the

number of rows per fetch parameter.

DSNTIAUL parameters:

SQL

Specify SQL to indicate that your input data set contains one or more complete

SQL statements, each of which ends with a semicolon. You can include any

SQL statement that can be executed dynamically in your input data set. In

addition, you can include the static SQL statements CONNECT, SET

CONNECTION, or RELEASE. DSNTIAUL uses the SELECT statements to

determine which tables to unload and dynamically executes all other

statements except CONNECT, SET CONNECTION, and RELEASE. DSNTIAUL

executes CONNECT, SET CONNECTION, and RELEASE statically to connect

to remote locations.

number of rows per fetch

Specify a number from 1 to 32767 to specify the number of rows per fetch that

DSNTIAUL retrieves. If you do not specify this number, DSNTIAUL retrieves

100 rows per fetch. This parameter can be specified with the SQL parameter.

Specify 1 to retrieve data from a remote site when DSNTIAUL is bound with

the DBPROTOCOL(PRIVATE) option.

TOLWARN

Specify NO (the default) or YES to indicate whether DSNTIAUL continues to

retrieve rows after receiving an SQL warning:

NO If a warning occurs when DSNTIAUL executes an OPEN or FETCH to

retrieve rows, DSNTIAUL stops retrieving rows. If the SQLWARN1,

SQLWARN2, SQLWARN6, or SQLWARN7 flag is set when DSNTIAUL

executes a FETCH to retrieve rows, DSNTIAUL continues to retrieve

rows.

Exception:

YES If a warning occurs when DSNTIAUL executes an OPEN or FETCH to

retrieve rows, DSNTIAUL continues to retrieve rows.

LOBFILE(prefix)

Specify LOBFILE to indicate that you want DSNTIAUL to dynamically allocate

data sets, each to receive the full content of a LOB cell. (A LOB cell is the

intersection of a row and a LOB column.) If you do not specify the LOBFILE

option, you can unload up to only 32 KB of data from a LOB column.

prefix

Specify a high-level qualifier for these dynamically allocated data sets. You

can specify up to 17 characters. The qualifier must conform with the rules

for TSO data set names.

DSNTIAUL uses a naming convention for these dynamically allocated data sets

of prefix.Qiiiiiii.Cjjjjjjj.Rkkkkkkk, where these qualifiers have the following

values:

prefix

The high-level qualifier that you specify in the LOBFILE option.

Appendix C. Running the productivity-aid sample programs 1113

|||||

||||

|||

||

Qiiiiiii

The sequence number (starting from 0) of a query that returns one or more

LOB columns

Cjjjjjjj

The sequence number (starting from 0) of a column in a query that returns

one or more LOB columns

Rkkkkkkk

The sequence number (starting from 0) of a row of a result set that has one

or more LOB columns.

The generated LOAD statement contains LOB file reference variables that can

be used to load data from these dynamically allocated data sets.

If you do not specify the SQL parameter, your input data set must contain one or

more single-line statements (without a semicolon) that use the following syntax:

table or view name [WHERE conditions] [ORDER BY columns]

Each input statement must be a valid SQL SELECT statement with the clause

SELECT * FROM omitted and with no ending semicolon. DSNTIAUL generates a

SELECT statement for each input statement by appending your input line to

SELECT * FROM, then uses the result to determine which tables to unload. For this

input format, the text for each table specification can be a maximum of 72 bytes

and must not span multiple lines.

You can use the input statements to specify SELECT statements that join two or

more tables or select specific columns from a table. If you specify columns, you

need to modify the LOAD statement that DSNTIAUL generates.

DSNTIAUL data sets:

Data set Description

SYSIN Input data set.

You cannot enter comments in DSNTIAUL input.

The record length for the input data set must be at least 72 bytes.

DSNTIAUL reads only the first 72 bytes of each record.

SYSPRINT Output data set. DSNTIAUL writes informational and error

messages in this data set.

The record length for the SYSPRINT data set is 121 bytes.

SYSPUNCH Output data set. DSNTIAUL writes the LOAD utility control

statements in this data set.

SYSRECnn Output data sets. The value nn ranges from 00 to 99. You can have

a maximum of 100 output data sets for a single execution of

DSNTIAUL. Each data set contains the data that is unloaded when

DSNTIAUL processes a SELECT statement from the input data set.

Therefore, the number of output data sets must match the number

of SELECT statements (if you specify parameter SQL) or table

specifications in your input data set.

Define all data sets as sequential data sets. You can specify the record length and

block size of the SYSPUNCH and SYSRECnn data sets. The maximum record

length for the SYSPUNCH and SYSRECnn data sets is 32760 bytes.


|||

|||

|||

||

DSNTIAUL return codes:

Table 241. DSNTIAUL return codes

Return code Meaning

0 Successful completion.

4 An SQL statement received a warning code. If the SQL statement was a

SELECT statement, DB2 did not perform the associated unload operation.

If DB2 return a +394, which indicates that it is using optimization hints,

DB2 performs the unload operation.

8 An SQL statement received an error code. If the SQL statement was a

SELECT statement, DB2 did not perform the associated unload operation.

12 DSNTIAUL could not open a data set, an SQL statement returned a

severe error code (-8nn or -9nn), or an error occurred in the SQL message

formatting routine.

Example of using DSNTIAUL to unload a subset of rows in a table: Suppose that

you want to unload the rows for department D01 from the project table. Because

you can fit the table specification on one line, and you do not want to execute any

non-SELECT statements, you do not need the SQL parameter. Your invocation

looks like the one that is shown in Figure 289:

Example of using DSNTIAUL to unload rows in more than one table: Suppose that

you also want to use DSNTIAUL to perform the following actions:

v Unload all rows from the project table

v Unload only rows from the employee table for employees in departments with

department numbers that begin with D, and order the unloaded rows by

employee number

v Lock both tables in share mode before you unload them

v Retrieve 250 rows per fetch

For these activities, you must specify the SQL parameter and specify the number of

rows per fetch when you run DSNTIAUL. Your DSNTIAUL invocation is shown in

Figure 290 on page 1116:

//UNLOAD EXEC PGM=IKJEFT01,DYNAMNBR=20

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD *

DSN SYSTEM(DSN)

RUN PROGRAM(DSNTIAUL) PLAN(DSNTIB91) -

LIB(’DSN910.RUNLIB.LOAD’)

//SYSPRINT DD SYSOUT=*

//SYSUDUMP DD SYSOUT=*

//SYSREC00 DD DSN=DSN8UNLD.SYSREC00,

// UNIT=SYSDA,SPACE=(32760,(1000,500)),DISP=(,CATLG),

// VOL=SER=SCR03

//SYSPUNCH DD DSN=DSN8UNLD.SYSPUNCH,


// VOL=SER=SCR03,RECFM=FB,LRECL=120,BLKSIZE=1200

//SYSIN DD *

DSN8910.PROJ WHERE DEPTNO='D01'

Figure 289. DSNTIAUL invocation without the SQL parameter


Example of using DSNTIAUL to obtain LOAD utility control statements: If you

want to obtain the LOAD utility control statements for loading rows into a table,

but you do not want to unload the rows, you can set the data set names for the

SYSRECnn data sets to DUMMY. For example, to obtain the utility control

statements for loading rows into the department table, you invoke DSNTIAUL as

shown in Figure 291:

Example of using DSNTIAUL to unload LOB data: This example uses the sample

LOB table with the following structure:

CREATE TABLE DSN8910.EMP_PHOTO_RESUME

( EMPNO CHAR(06) NOT NULL,

EMP_ROWID ROWID NOT NULL GENERATED ALWAYS,

PSEG_PHOTO BLOB(500K),

BMP_PHOTO BLOB(100K),

RESUME CLOB(5K),

PRIMARY KEY (EMPNO))

IN DSN8D91L.DSN8S91B

CCSID EBCDIC;



//SYSTSIN DD *

DSN SYSTEM(DSN)

RUN PROGRAM(DSNTIAUL) PLAN(DSNTIB91) PARMS('SQL,250') -






// VOL=SER=SCR03



// VOL=SER=SCR03




//SYSIN DD *

LOCK TABLE DSN8910.EMP IN SHARE MODE;

LOCK TABLE DSN8910.PROJ IN SHARE MODE;

SELECT * FROM DSN8910.PROJ;

SELECT * FROM DSN8910.EMP

WHERE WORKDEPT LIKE ’D%’

ORDER BY EMPNO;

Figure 290. DSNTIAUL invocation with the SQL parameter



//SYSTSIN DD *

DSN SYSTEM(DSN)





//SYSREC00 DD DUMMY




//SYSIN DD *

DSN8910.DEPT

Figure 291. DSNTIAUL invocation to obtain LOAD control statements


||

|||||||||

The following call to DSNTIAUL unloads the sample LOB table. The parameters

for DSNTIAUL indicate the following options:

v The input data set (SYSIN) contains SQL.

v DSNTIAUL is to retrieve 2 rows per fetch.

v DSNTIAUL places the LOB data in data sets with a high-level qualifier of

DSN8UNLD.//UNLOAD EXEC PGM=IKJEFT01,DYNAMNBR=20


//SYSTSIN DD *

DSN SYSTEM(DSN)


PARMS(’SQL,2,LOBFILE(DSN8UNLD)’) -






// VOL=SER=SCR03,RECFM=FB



// VOL=SER=SCR03,RECFM=FB

//SYSIN DD *

SELECT * FROM DSN8910.EMP_PHOTO_RESUME;

Given that the sample LOB table has 4 rows of data, DSNTIAUL produces the

following output:

v Data for columns EMPNO and EMP_ROWID are placed in the data set that is

allocated according to the SYSREC00 DD statement. The data set name is

DSN8UNLD.SYSREC00

v A generated LOAD statement is placed in the data set that is allocated according

to the SYSPUNCH DD statement. The data set name is DSN8UNLD.SYSPUNCH

v The following data sets are dynamically created to store LOB data:

– DSN8UNLD.Q0000000.C0000002.R0000000

– DSN8UNLD.Q0000000.C0000002.R0000001

– DSN8UNLD.Q0000000.C0000002.R0000002

– DSN8UNLD.Q0000000.C0000002.R0000003

– DSN8UNLD.Q0000000.C0000003.R0000000

– DSN8UNLD.Q0000000.C0000003.R0000001

– DSN8UNLD.Q0000000.C0000003.R0000002

– DSN8UNLD.Q0000000.C0000003.R0000003

– DSN8UNLD.Q0000000.C0000004.R0000000

– DSN8UNLD.Q0000000.C0000004.R0000001

– DSN8UNLD.Q0000000.C0000004.R0000002

– DSN8UNLD.Q0000000.C0000004.R0000003

For example, DSN8UNLD.Q0000000.C0000004.R0000001 means that the data set

contains data that is unloaded from the second row (R0000001) and the fifth

column (C0000004) of the result set for the first query (Q0000000).


||

|

|

||

|||||||||||||||||

||

|||

||

|

|

|

|

|

|

|

|

|

|

|

|

|

|||

Running DSNTIAD

This section contains information that you need when you run DSNTIAD,

including parameters, data sets, return codes, and invocation examples.

DSNTIAD parameters:

RC0

If you specify this parameter, DSNTIAD ends with return code 0, even if the

program encounters SQL errors. If you do not specify RC0, DSNTIAD ends

with a return code that reflects the severity of the errors that occur. Without

RC0, DSNTIAD terminates if more than 10 SQL errors occur during a single

execution.

SQLTERM(termchar)

Specify this parameter to indicate the character that you use to end each SQL

statement. You can use any special character except one of those listed in

Table 242. SQLTERM(;) is the default.

Table 242. Invalid special characters for the SQL terminator

Name Character Hexadecimal representation

blank X'40'

comma , X'6B'

double quotation mark " X'7F'

left parenthesis ( X'4D'

right parenthesis ) X'5D'

single quotation mark ' X'7D'

underscore _ X'6D'

Use a character other than a semicolon if you plan to execute a statement that

contains embedded semicolons.

Example: Suppose that you specify the parameter SQLTERM(#) to indicate that

the character # is the statement terminator. Then a CREATE TRIGGER

statement with embedded semicolons looks like this:

CREATE TRIGGER NEW_HIRE

AFTER INSERT ON EMP

FOR EACH ROW MODE DB2SQL

BEGIN ATOMIC

UPDATE COMPANY_STATS SET NBEMP = NBEMP + 1;

END#

A CREATE PROCEDURE statement with embedded semicolons looks like the

following statement:

CREATE PROCEDURE PROC1 (IN PARM1 INT, OUT SCODE INT)

LANGUAGE SQL

BEGIN

DECLARE SQLCODE INT;

DECLARE EXIT HANDLER FOR SQLEXCEPTION

SET SCODE = SQLCODE;

UPDATE TBL1 SET COL1 = PARM1;

END #

Be careful to choose a character for the statement terminator that is not used

within the statement.


DSNTIAD data sets:

Data set Description

SYSIN Input data set. In this data set, you can enter any number of

non-SELECT SQL statements, each terminated with a semicolon. A

statement can span multiple lines, but DSNTIAD reads only the

first 72 bytes of each line.

You cannot enter comments in DSNTIAD input.

SYSPRINT Output data set. DSNTIAD writes informational and error

messages in this data set. DSNTIAD sets the record length of this

data set to 121 bytes and the block size to 1210 bytes.

Define all data sets as sequential data sets.

DSNTIAD return codes:

Table 243. DSNTIAD return codes

Return code Meaning

0 Successful completion, or the user-specified parameter RC0.

4 An SQL statement received a warning code.

8 An SQL statement received an error code.

12 DSNTIAD could not open a data set, the length of an SQL statement was

more than 32760 bytes, an SQL statement returned a severe error code

(-8nn or -9nn), or an error occurred in the SQL message formatting

routine.

Example of DSNTIAD invocation: Suppose that you want to execute 20 UPDATE

statements, and you do not want DSNTIAD to terminate if more than 10 errors

occur. Your invocation looks like the one that is shown in Figure 292:

Running DSNTEP2 and DSNTEP4

This section contains information that you need when you run DSNTEP2 or

DSNTEP4, including parameters, data sets, return codes, and invocation examples.

DSNTEP2 and DSNTEP4 parameters:

ALIGN(MID) or ALIGN(LHS)

Specifies the alignment.

//RUNTIAD EXEC PGM=IKJEFT01,DYNAMNBR=20


//SYSTSIN DD *

DSN SYSTEM(DSN)

RUN PROGRAM(DSNTIAD) PLAN(DSNTIA91) PARMS('RC0') -




//SYSIN DD *

UPDATE DSN8910.PROJ SET DEPTNO='J01' WHERE DEPTNO='A01';

UPDATE DSN8910.PROJ SET DEPTNO='J02' WHERE DEPTNO='A02'; ...UPDATE DSN8910.PROJ SET DEPTNO='J20' WHERE DEPTNO='A20';

Figure 292. DSNTIAD Invocation with the RC0 Parameter


ALIGN(MID)

Specifies that DSNTEP2 or DSNTEP4 output should be centered.

ALIGN(MID) is the default.

ALIGN(LHS)

Specifies that the DSNTEP2 or DSNTEP4 output should be left-justified.

NOMIXED or MIXED

Specifies whether DSNTEP2 or DSNTEP4 contains any DBCS characters.

NOMIXED

Specifies that the DSNTEP2 or DSNTEP4 input contains no DBCS

characters. NOMIXED is the default.

MIXED

Specifies that the DSNTEP2 or DSNTEP4 input contains some DBCS

characters.

PREPWARN

Specifies that DSNTEP2 or DSNTEP4 is to display the PREPARE

SQLWARNING message and set the return code to 4 when an SQLWARNING

is encountered at PREPARE.

SQLTERM(termchar)

Specifies the character that you use to end each SQL statement. You can use

any character except one of those that are listed in Table 242 on page 1118.

SQLTERM(;) is the default.

Use a character other than a semicolon if you plan to execute a statement that

contains embedded semicolons.

Example: Suppose that you specify the parameter SQLTERM(#) to indicate that

the character # is the statement terminator. Then a CREATE TRIGGER

statement with embedded semicolons looks like this:


AFTER INSERT ON EMP


BEGIN ATOMIC


END#

A CREATE PROCEDURE statement with embedded semicolons looks like the

following statement:

CREATE PROCEDURE PROC1 (IN PARM1 INT, OUT SCODE INT)

LANGUAGE SQL

BEGIN

DECLARE SQLCODE INT;

DECLARE EXIT HANDLER FOR SQLEXCEPTION

SET SCODE = SQLCODE;

UPDATE TBL1 SET COL1 = PARM1;

END #

Be careful to choose a character for the statement terminator that is not used

within the statement.

If you want to change the SQL terminator within a series of SQL statements,

you can use the --#SET TERMINATOR control statement.

Example: Suppose that you have an existing set of SQL statements to which

you want to add a CREATE TRIGGER statement that has embedded

semicolons. You can use the default SQLTERM value, which is a semicolon, for


||||

all of the existing SQL statements. Before you execute the CREATE TRIGGER

statement, include the --#SET TERMINATOR # control statement to change the

SQL terminator to the character #:

SELECT * FROM DEPT;

SELECT * FROM ACT;

SELECT * FROM EMPPROJACT;

SELECT * FROM PROJ;

SELECT * FROM PROJACT;

--#SET TERMINATOR #


AFTER INSERT ON EMP


BEGIN ATOMIC


END#

See the following discussion of the SYSIN data set for more information about

the --#SET control statement.

TOLWARN

Specify NO (the default) or YES to indicate whether DSNTEP2 or DSNTEP4

continues to process SQL SELECT statements after receiving an SQL warning:

NO If a warning occurs when DSNTEP2 or DSNTEP4 executes an OPEN or

FETCH for a SELECT statement, DSNTEP2 or DSNTEP4 stops

processing the SELECT statement. If SQLCODE +445 or SQLCODE

+595 occurs when DSNTEP2 or DSNTEP4 executes a FETCH for a

SELECT statement, DSNTEP2 or DSNTEP4 continues to process the

SELECT statement. If SQLCODE +802 occurs when DSNTEP2 or

DSNTEP4 executes a FETCH for a SELECT statement, DSNTEP2 or

DSNTEP4 continues to process the SELECT statement if the

TOLARTHWRN control statement is set to YES.

YES If a warning occurs when DSNTEP2 or DSNTEP4 executes an OPEN or

FETCH for a SELECT statement, DSNTEP2 or DSNTEP4 continues to

process the SELECT statement.

DSNTEP2 and DSNTEP4 data sets:

Data Set Description

SYSIN Input data set. In this data set, you can enter any number of SQL

statements, each terminated with a semicolon. A statement can

span multiple lines, but DSNTEP2 or DSNTEP4 reads only the first

72 bytes of each line.

You can enter comments in DSNTEP2 or DSNTEP4 input with an

asterisk (*) in column 1 or two hyphens (--) anywhere on a line.

Text that follows the asterisk is considered to be comment text.

Text that follows two hyphens can be comment text or a control

statement. Comments are not considered in dynamic statement

caching. Comments and control statements cannot span lines.

You can enter control statements of the following form in the

DSNTEP2 and DSNTEP4 input data set:

--#SET control-option value

The control options are:

TERMINATOR

The SQL statement terminator. value is any single-byte


||

character other than one of those that are listed in Table 242 on

page 1118. The default is the value of the SQLTERM parameter.

ROWS_FETCH

The number of rows that are to be fetched from the result

table. value is a numeric literal between -1 and the number of

rows in the result table. -1 means that all rows are to be

fetched. The default is -1.

ROWS_OUT

The number of fetched rows that are to be sent to the output

data set. value is a numeric literal between -1 and the number

of fetched rows. -1 means that all fetched rows are to be sent to

the output data set. The default is -1.

MULT_FETCH

This option is valid only for DSNTEP4. Use MULT_FETCH to

specify the number of rows that are to be fetched at one time

from the result table. The default fetch amount for DSNTEP4 is

100 rows, but you can specify from 1 to 32676 rows.

TOLWARN

Indicates whether DSNTEP2 and DSNTEP4 continue to process

an SQL SELECT after an SQL warning is returned. value is

either NO (the default) or YES.

PREPWARN

Indicates how DSNTEP2 and DSNTEP4 is to handle a

PREPARE SQLWARNING message.

NO

Indicates that DSNTEP2 and DSNTEP4 does not display

the PREPARE SQLWARNING message and does not set

the return code to 4 when an SQLWARNING is

encountered at PREPARE. The default is NO.

YES

Indicates that DSNTEP2 and DSNTEP4 displays the

PREPARE SQLWARNING message and sets the return

code to 4 when an SQLWARNING is encountered at

PREPARE.

SYSPRINT Output data set. DSNTEP2 and DSNTEP4 write informational and

error messages in this data set. DSNTEP2 and DSNTEP4 write

output records of no more than 133 bytes.

Define all data sets as sequential data sets.

DSNTEP2 and DSNTEP4 return codes:

Table 244. DSNTEP2 and DSNTEP4 return codes

Return code Meaning


4 An SQL statement received a warning code.

8 An SQL statement received an error code.

12 The length of an SQL statement was more than 32760 bytes, an SQL

statement returned a severe error code (-8nn or -9nn), or an error

occurred in the SQL message formatting routine.


|||

|||||

|||||

Example of DSNTEP2 invocation: Suppose that you want to use DSNTEP2 to

execute SQL SELECT statements that might contain DBCS characters. You also

want left-aligned output. Your invocation looks like the one in Figure 293:

Example of DSNTEP4 invocation: Suppose that you want to use DSNTEP4 to

execute SQL SELECT statements that might contain DBCS characters, and you

want center-aligned output. You also want DSNTEP4 to fetch 250 rows at a time.

Your invocation looks like the one in Figure 294:

//RUNTEP2 EXEC PGM=IKJEFT01,DYNAMNBR=20


//SYSTSIN DD *

DSN SYSTEM(DSN)

RUN PROGRAM(DSNTEP2) PLAN(DSNTEP91) PARMS('/ALIGN(LHS) MIXED TOLWARN(YES)') -




//SYSIN DD *

SELECT * FROM DSN8910.PROJ;

Figure 293. DSNTEP2 invocation with the ALIGN(LHS) and MIXED parameters

//RUNTEP2 EXEC PGM=IKJEFT01,DYNAMNBR=20


//SYSTSIN DD *

DSN SYSTEM(DSN)

RUN PROGRAM(DSNTEP4) PLAN(DSNTEP481) PARMS('/ALIGN(MID) MIXED') -




//SYSIN DD *

--#SET MULT_FETCH 250

SELECT * FROM DSN8910.EMP;

Figure 294. DSNTEP4 invocation with the ALIGN(MID) and MIXED parameters and using the

MULT_FETCH control option



Appendix D. Programming examples

This section contains the following programming examples:

v Sample COBOL dynamic SQL program

v “Sample dynamic and static SQL in a C program” on page 1137

v “Sample DB2 REXX application” on page 1141

v “Sample COBOL program using DRDA access with CONNECT statements” on

page 1155

v “Sample COBOL program using DRDA with three-part names” on page 1163

v “Examples of using stored procedures” on page 1169

To prepare and run these applications, use the JCL in DSN910.SDSNSAMP as a

model for your JCL. For a list JCL procedures for preparing sample programs, see

Appendix B, “Sample applications,” on page 1103. For information on the

appropriate compiler options to use for each language, see the following topics in

DB2 Installation Guide:

v “Special considerations for COBOL programs”

v “Special considerations for C and C++ programs”

v “Special considerations for PL/I programs”

Sample COBOL dynamic SQL program

Chapter 25, “Coding dynamic SQL in application programs,” on page 661 describes

three variations of dynamic SQL statements:

v Non-SELECT statements

v Fixed-List SELECT statements

In this case, you know the number of columns returned and their data types

when you write the program.

v Varying-List SELECT statements.

In this case, you do not know the number of columns returned and their data

types when you write the program.

This section documents a technique of coding varying list SELECT statements in

COBOL. For a list of the supported versions of COBOL, see DB2 Program Directory

.

This example program does not support BLOB, CLOB, or DBCLOB data types.

Pointers and based variables in the sample COBOL program

COBOL has a POINTER type and a SET statement that provide pointers and based

variables.

The SET statement sets a pointer from the address of an area in the linkage section

or another pointer; the statement can also set the address of an area in the linkage

section. Figure 296 on page 1128 provides these uses of the SET statement. The SET

statement does not permit the use of an address in the WORKING-STORAGE

section.


Storage allocation for the sample COBOL program

COBOL does not provide a means to allocate main storage within a program. You

can achieve the same end by having an initial program which allocates the storage,

and then calls a second program that manipulates the pointer. (COBOL does not

permit you to directly manipulate the pointer because errors and abends are likely

to occur.)

The initial program is extremely simple. It includes a working storage section that

allocates the maximum amount of storage needed. This program then calls the

second program, passing the area or areas on the CALL statement. The second

program defines the area in the linkage section and can then use pointers within

the area.

If you need to allocate parts of storage, the best method is to use indexes or

subscripts. You can use subscripts for arithmetic and comparison operations.

Example of the sample COBOL program

Figure 295 shows an example of the initial program DSN8BCU1 that allocates the

storage and calls the second program DSN8BCU2 shown in Figure 296 on page

1128. DSN8BCU2 then defines the passed storage areas in its linkage section and

includes the USING clause on its PROCEDURE DIVISION statement.

Defining the pointers, then redefining them as numeric, permits some

manipulation of the pointers that you cannot perform directly. For example, you

cannot add the column length to the record pointer, but you can add the column

length to the numeric value that redefines the pointer.

**** DSN8BCU1- DB2 SAMPLE BATCH COBOL UNLOAD PROGRAM ***********

* *

* MODULE NAME = DSN8BCU1 *

* *

* DESCRIPTIVE NAME = DB2 SAMPLE APPLICATION *

* UNLOAD PROGRAM *

* BATCH *

* ENTERPRISE COBOL FOR Z/OS *

* *

* FUNCTION = THIS MODULE PROVIDES THE STORAGE NEEDED BY *

* DSN8BCU2 AND CALLS THAT PROGRAM. *

* *

* NOTES = *

* DEPENDENCIES = NONE. *

* *

* RESTRICTIONS = *

* THE MAXIMUM NUMBER OF COLUMNS IS 750, *

* WHICH IS THE SQL LIMIT. *

* *

* DATA RECORDS ARE LIMITED TO 32700 BYTES, *

* INCLUDING DATA, LENGTHS FOR VARCHAR DATA, *

* AND SPACE FOR NULL INDICATORS. *

* *

* MODULE TYPE = COBOL PROGRAM *

* PROCESSOR = ENTERPRISE COBOL FOR Z/OS *

* *

* MODULE SIZE = SEE LINK EDIT *

* ATTRIBUTES = REENTRANT *

* *

Figure 295. Initial program that allocates storage (Part 1 of 2)


* ENTRY POINT = DSN8BCU1 *

* PURPOSE = SEE FUNCTION *

* LINKAGE = INVOKED FROM DSN RUN *

* INPUT = NONE *

* OUTPUT = NONE *

* *

* EXIT-NORMAL = RETURN CODE 0 NORMAL COMPLETION *

* *

* EXIT-ERROR = *

* RETURN CODE = NONE *

* ABEND CODES = NONE *

* ERROR-MESSAGES = NONE *

* *

* EXTERNAL REFERENCES = *

* ROUTINES/SERVICES = *

* DSN8BCU2 - ACTUAL UNLOAD PROGRAM *

* *

* DATA-AREAS = NONE *

* CONTROL-BLOCKS = NONE *

* *

* TABLES = NONE *

* CHANGE-ACTIVITY = NONE *

* *

* *PSEUDOCODE* *

* *

* PROCEDURE *

* CALL DSN8BCU2. *

* END. *

*---------------------------------------------------------------*

/

IDENTIFICATION DIVISION.

*-----------------------

PROGRAM-ID. DSN8BCU1

*

ENVIRONMENT DIVISION.

*

CONFIGURATION SECTION.

DATA DIVISION.

*

WORKING-STORAGE SECTION.

*

01 WORKAREA-IND.

02 WORKIND PIC S9(4) COMP OCCURS 750 TIMES.

01 RECWORK.

02 RECWORK-LEN PIC S9(8) COMP VALUE 32700.

02 RECWORK-CHAR PIC X(1) OCCURS 32700 TIMES.

*

PROCEDURE DIVISION.

*

CALL ’DSN8BCU2’ USING WORKAREA-IND RECWORK.

GOBACK.

Figure 295. Initial program that allocates storage (Part 2 of 2)

Appendix D. Programming examples 1127

**** DSN8BCU2- DB2 SAMPLE BATCH COBOL UNLOAD PROGRAM ***********

* *

* MODULE NAME = DSN8BCU2 *

* *

* DESCRIPTIVE NAME = DB2 SAMPLE APPLICATION *

* UNLOAD PROGRAM *

* BATCH *

* ENTERPRISE COBOL FOR Z/OS *

* *

* *

* FUNCTION = THIS MODULE ACCEPTS A TABLE NAME OR VIEW NAME *

* AND UNLOADS THE DATA IN THAT TABLE OR VIEW. *

* READ IN A TABLE NAME FROM SYSIN. *

* PUT DATA FROM THE TABLE INTO DD SYSREC01. *

* WRITE RESULTS TO SYSPRINT. *

* *

* NOTES = *

* DEPENDENCIES = NONE. *

* *

* RESTRICTIONS = *

* THE SQLDA IS LIMITED TO 33016 BYTES. *

* THIS SIZE ALLOWS FOR THE DB2 MAXIMUM *

* OF 750 COLUMNS. *

* *

* DATA RECORDS ARE LIMITED TO 32700 BYTES, *

* INCLUDING DATA, LENGTHS FOR VARCHAR DATA, *

* AND SPACE FOR NULL INDICATORS. *

* *

* TABLE OR VIEW NAMES ARE ACCEPTED, AND ONLY *

* ONE NAME IS ALLOWED PER RUN. *

* *


* PROCESSOR = DB2 PRECOMPILER *

* *

* *


* ATTRIBUTES = REENTRANT *

* *

* ENTRY POINT = DSN8BCU2 *

* PURPOSE = SEE FUNCTION *

* LINKAGE = *

* CALL ’DSN8BCU2’ USING WORKAREA-IND RECWORK. *

* *

* INPUT = SYMBOLIC LABEL/NAME = WORKAREA-IND *

* DESCRIPTION = INDICATOR VARIABLE ARRAY *

* 01 WORKAREA-IND. *

* 02 WORKIND PIC S9(4) COMP OCCURS 750 TIMES. *

* *

* SYMBOLIC LABEL/NAME = RECWORK *

* DESCRIPTION = WORK AREA FOR OUTPUT RECORD *

* 01 RECWORK. *

* 02 RECWORK-LEN PIC S9(8) COMP. *

* *

* SYMBOLIC LABEL/NAME = SYSIN *

* DESCRIPTION = INPUT REQUESTS - TABLE OR VIEW *

* *

Figure 296. Called program that does pointer manipulation (Part 1 of 10)


* OUTPUT = SYMBOLIC LABEL/NAME = SYSPRINT *

* DESCRIPTION = PRINTED RESULTS *

* *

* SYMBOLIC LABEL/NAME = SYSREC01 *

* DESCRIPTION = UNLOADED TABLE DATA *

* *

* EXIT-NORMAL = RETURN CODE 0 NORMAL COMPLETION *

* EXIT-ERROR = *

* RETURN CODE = NONE *

* ABEND CODES = NONE *

* ERROR-MESSAGES = *

* DSNT490I SAMPLE COBOL DATA UNLOAD PROGRAM RELEASE 3.0*

* - THIS IS THE HEADER, INDICATING A NORMAL *

* - START FOR THIS PROGRAM. *

* DSNT493I SQL ERROR, SQLCODE = NNNNNNNN *

* - AN SQL ERROR OR WARNING WAS ENCOUNTERED *

* - ADDITIONAL INFORMATION FROM DSNTIAR *

* - FOLLOWS THIS MESSAGE. *

* DSNT495I SUCCESSFUL UNLOAD XXXXXXXX ROWS OF *

* TABLE TTTTTTTT *

* - THE UNLOAD WAS SUCCESSFUL. XXXXXXXX IS *

* - THE NUMBER OF ROWS UNLOADED. TTTTTTTT *

* - IS THE NAME OF THE TABLE OR VIEW FROM *

* - WHICH IT WAS UNLOADED. *

* DSNT496I UNRECOGNIZED DATA TYPE CODE OF NNNNN *

* - THE PREPARE RETURNED AN INVALID DATA *

* - TYPE CODE. NNNNN IS THE CODE, PRINTED *

* - IN DECIMAL. USUALLY AN ERROR IN *

* - THIS ROUTINE OR A NEW DATA TYPE. *

* DSNT497I RETURN CODE FROM MESSAGE ROUTINE DSNTIAR *

* - THE MESSAGE FORMATTING ROUTINE DETECTED *

* - AN ERROR. SEE THAT ROUTINE FOR RETURN *

* - CODE INFORMATION. USUALLY AN ERROR IN *

* - THIS ROUTINE. *

* DSNT498I ERROR, NO VALID COLUMNS FOUND *

* - THE PREPARE RETURNED DATA WHICH DID NOT *

* - PRODUCE A VALID OUTPUT RECORD. *

* - USUALLY AN ERROR IN THIS ROUTINE. *

* DSNT499I NO ROWS FOUND IN TABLE OR VIEW *

* - THE CHOSEN TABLE OR VIEWS DID NOT *

* - RETURN ANY ROWS. *

* ERROR MESSAGES FROM MODULE DSNTIAR *

* - WHEN AN ERROR OCCURS, THIS MODULE *

* - PRODUCES CORRESPONDING MESSAGES. *

* *


* ROUTINES/SERVICES = *

* DSNTIAR - TRANSLATE SQLCA INTO MESSAGES *


* CONTROL-BLOCKS = *

* SQLCA - SQL COMMUNICATION AREA *

* *

* TABLES = NONE *


* *



* *PSEUDOCODE* *

* PROCEDURE *

* EXEC SQL DECLARE DT CURSOR FOR SEL END-EXEC. *

* EXEC SQL DECLARE SEL STATEMENT END-EXEC. *

* INITIALIZE THE DATA, OPEN FILES. *

* OBTAIN STORAGE FOR THE SQLDA AND THE DATA RECORDS. *

* READ A TABLE NAME. *

* OPEN SYSREC01. *

* BUILD THE SQL STATEMENT TO BE EXECUTED *

* EXEC SQL PREPARE SQL STATEMENT INTO SQLDA END-EXEC. *

* SET UP ADDRESSES IN THE SQLDA FOR DATA. *

* INITIALIZE DATA RECORD COUNTER TO 0. *

* EXEC SQL OPEN DT END-EXEC. *

* DO WHILE SQLCODE IS 0. *

* EXEC SQL FETCH DT USING DESCRIPTOR SQLDA END-EXEC. *

* ADD IN MARKERS TO DENOTE NULLS. *

* WRITE THE DATA TO SYSREC01. *

* INCREMENT DATA RECORD COUNTER. *

* END. *

* EXEC SQL CLOSE DT END-EXEC. *

* INDICATE THE RESULTS OF THE UNLOAD OPERATION. *

* CLOSE THE SYSIN, SYSPRINT, AND SYSREC01 FILES. *

* END. *

*---------------------------------------------------------------*

/


*-----------------------

PROGRAM-ID. DSN8BCU2

*


*--------------------


INPUT-OUTPUT SECTION.

FILE-CONTROL.

SELECT SYSIN

ASSIGN TO DA-S-SYSIN.

SELECT SYSPRINT

ASSIGN TO UT-S-SYSPRINT.

SELECT SYSREC01

ASSIGN TO DA-S-SYSREC01.

*

DATA DIVISION.

*-------------

*

FILE SECTION.

FD SYSIN

RECORD CONTAINS 80 CHARACTERS

BLOCK CONTAINS 0 RECORDS

LABEL RECORDS ARE OMITTED

RECORDING MODE IS F.

01 CARDREC PIC X(80).

*

FD SYSPRINT



DATA RECORD IS MSGREC

RECORDING MODE IS F.

01 MSGREC PIC X(120).



*

FD SYSREC01

RECORD CONTAINS 5 TO 32704 CHARACTERS


DATA RECORD IS REC01

RECORDING MODE IS V.

01 REC01.

02 REC01-LEN PIC S9(8) COMP.

02 REC01-CHAR PIC X(1) OCCURS 1 TO 32700 TIMES

DEPENDING ON REC01-LEN.

/


*

*****************************************************

* STRUCTURE FOR INPUT *

*****************************************************

01 IOAREA.

02 TNAME PIC X(72).

02 FILLER PIC X(08).

01 STMTBUF.

49 STMTLEN PIC S9(4) COMP VALUE 92.

49 STMTCHAR PIC X(92).

01 STMTBLD.

02 FILLER PIC X(20) VALUE ’SELECT * FROM’.

02 STMTTAB PIC X(72).

*

*****************************************************

* REPORT HEADER STRUCTURE *

*****************************************************

01 HEADER.

02 FILLER PIC X(35)

VALUE ’ DSNT490I SAMPLE COBOL DATA UNLOAD ’.

02 FILLER PIC X(85) VALUE ’PROGRAM RELEASE 3.0’.

01 MSG-SQLERR.

02 FILLER PIC X(31)

VALUE ’ DSNT493I SQL ERROR, SQLCODE = ’.

02 MSG-MINUS PIC X(1).

02 MSG-PRINT-CODE PIC 9(8).

02 FILLER PIC X(81) VALUE ’ ’.

01 UNLOADED.

02 FILLER PIC X(28)

VALUE ’ DSNT495I SUCCESSFUL UNLOAD ’.

02 ROWS PIC 9(8).

02 FILLER PIC X(15) VALUE ’ ROWS OF TABLE ’.

02 TABLENAM PIC X(72) VALUE ’ ’.

01 BADTYPE.

02 FILLER PIC X(42)

VALUE ’ DSNT496I UNRECOGNIZED DATA TYPE CODE OF ’.

02 TYPCOD PIC 9(8).


01 MSGRETCD.

02 FILLER PIC X(42)

VALUE ’ DSNT497I RETURN CODE FROM MESSAGE ROUTINE’.

02 FILLER PIC X(9) VALUE ’DSNTIAR ’.

02 RETCODE PIC 9(8).




01 MSGNOCOL.

02 FILLER PIC X(120)

VALUE ’ DSNT498I ERROR, NO VALID COLUMNS FOUND’.

01 MSG-NOROW.

02 FILLER PIC X(120)

VALUE ’ DSNT499I NO ROWS FOUND IN TABLE OR VIEW’.

*****************************************************

* WORKAREAS *

*****************************************************

77 NOT-FOUND PIC S9(8) COMP VALUE +100.

*****************************************************

* VARIABLES FOR ERROR-MESSAGE FORMATTING *

00

*****************************************************

01 ERROR-MESSAGE.

02 ERROR-LEN PIC S9(4) COMP VALUE +960.

02 ERROR-TEXT PIC X(120) OCCURS 8 TIMES

INDEXED BY ERROR-INDEX.

77 ERROR-TEXT-LEN PIC S9(8) COMP VALUE +120.

*****************************************************

* SQL DESCRIPTOR AREA *

*****************************************************

EXEC SQL INCLUDE SQLDA END-EXEC.

*

* DATA TYPES FOUND IN SQLTYPE, AFTER REMOVING THE NULL BIT

*

77 VARCTYPE PIC S9(4) COMP VALUE +448.

77 CHARTYPE PIC S9(4) COMP VALUE +452.

77 VARLTYPE PIC S9(4) COMP VALUE +456.

77 VARGTYPE PIC S9(4) COMP VALUE +464.

77 GTYPE PIC S9(4) COMP VALUE +468.

77 LVARGTYP PIC S9(4) COMP VALUE +472.

77 FLOATYPE PIC S9(4) COMP VALUE +480.

77 DECTYPE PIC S9(4) COMP VALUE +484.

77 INTTYPE PIC S9(4) COMP VALUE +496.

77 HWTYPE PIC S9(4) COMP VALUE +500.

77 DATETYP PIC S9(4) COMP VALUE +384.

77 TIMETYP PIC S9(4) COMP VALUE +388.

77 TIMESTMP PIC S9(4) COMP VALUE +392.

*



*****************************************************

* THE REDEFINES CLAUSES BELOW ARE FOR 31-BIT ADDRESSING.

* IF YOUR COMPILER SUPPORTS ONLY 24-BIT ADDRESSING,

* CHANGE THE DECLARATIONS TO THESE:

* 01 RECNUM REDEFINES RECPTR PICTURE S9(8) COMPUTATIONAL.

* 01 IRECNUM REDEFINES IRECPTR PICTURE S9(8) COMPUTATIONAL.

*****************************************************

01 RECPTR POINTER.

01 RECNUM REDEFINES RECPTR PICTURE S9(9) COMPUTATIONAL.

01 IRECPTR POINTER.

01 IRECNUM REDEFINES IRECPTR PICTURE S9(9) COMPUTATIONAL.

01 I PICTURE S9(4) COMPUTATIONAL.

01 J PICTURE S9(4) COMPUTATIONAL.

01 DUMMY PICTURE S9(4) COMPUTATIONAL.

01 MYTYPE PICTURE S9(4) COMPUTATIONAL.

01 COLUMN-IND PICTURE S9(4) COMPUTATIONAL.

01 COLUMN-LEN PICTURE S9(4) COMPUTATIONAL.

01 COLUMN-PREC PICTURE S9(4) COMPUTATIONAL.

01 COLUMN-SCALE PICTURE S9(4) COMPUTATIONAL.

01 INDCOUNT PIC S9(4) COMPUTATIONAL.

01 ROWCOUNT PIC S9(4) COMPUTATIONAL.

01 WORKAREA2.

02 WORKINDPTR POINTER OCCURS 750 TIMES.

*****************************************************

* DECLARE CURSOR AND STATEMENT FOR DYNAMIC SQL

*****************************************************

*

EXEC SQL DECLARE DT CURSOR FOR SEL END-EXEC.

EXEC SQL DECLARE SEL STATEMENT END-EXEC.

*

*****************************************************

* SQL INCLUDE FOR SQLCA *

*****************************************************

EXEC SQL INCLUDE SQLCA END-EXEC.

*

77 ONE PIC S9(4) COMP VALUE +1.

77 TWO PIC S9(4) COMP VALUE +2.

77 FOUR PIC S9(4) COMP VALUE +4.

77 QMARK PIC X(1) VALUE ’?’.

*

LINKAGE SECTION.

01 LINKAREA-IND.

02 IND PIC S9(4) COMP OCCURS 750 TIMES.

01 LINKAREA-REC.

02 REC1-LEN PIC S9(8) COMP.

02 REC1-CHAR PIC X(1) OCCURS 1 TO 32700 TIMES

DEPENDING ON REC1-LEN.

01 LINKAREA-QMARK.

02 INDREC PIC X(1).

/



PROCEDURE DIVISION USING LINKAREA-IND LINKAREA-REC.

*

*****************************************************

* SQL RETURN CODE HANDLING *

*****************************************************

EXEC SQL WHENEVER SQLERROR GOTO DBERROR END-EXEC.

EXEC SQL WHENEVER SQLWARNING GOTO DBERROR END-EXEC.

EXEC SQL WHENEVER NOT FOUND CONTINUE END-EXEC.

*

*****************************************************

* MAIN PROGRAM ROUTINE *

*****************************************************

SET IRECPTR TO ADDRESS OF REC1-CHAR(1).

* **OPEN FILES

OPEN INPUT SYSIN

OUTPUT SYSPRINT

OUTPUT SYSREC01.

* **WRITE HEADER

WRITE MSGREC FROM HEADER

AFTER ADVANCING 2 LINES.

* **GET FIRST INPUT

READ SYSIN RECORD INTO IOAREA.

* **MAIN ROUTINE

PERFORM PROCESS-INPUT THROUGH IND-RESULT.

*

PROG-END.

* **CLOSE FILES

CLOSE SYSIN

SYSPRINT

SYSREC01.

GOBACK.

/

***************************************************************

* *

* PERFORMED SECTION: *

* PROCESSING FOR THE TABLE OR VIEW JUST READ *

* *

***************************************************************

PROCESS-INPUT.

*

MOVE TNAME TO STMTTAB.

MOVE STMTBLD TO STMTCHAR.

EXEC SQL PREPARE SEL INTO :SQLDA FROM :STMTBUF END-EXEC.

***************************************************************

* *

* SET UP ADDRESSES IN THE SQLDA FOR DATA. *

* *

***************************************************************

IF SQLD = ZERO THEN

WRITE MSGREC FROM MSGNOCOL

AFTER ADVANCING 2 LINES

GO TO IND-RESULT.

MOVE ZERO TO ROWCOUNT.

MOVE ZERO TO REC1-LEN.

SET RECPTR TO IRECPTR.

MOVE ONE TO I.

PERFORM COLADDR UNTIL I > SQLD.



****************************************************************

* *

* SET LENGTH OF OUTPUT RECORD. *

* EXEC SQL OPEN DT END-EXEC. *

* DO WHILE SQLCODE IS 0. *

* EXEC SQL FETCH DT USING DESCRIPTOR :SQLDA END-EXEC. *

* ADD IN MARKERS TO DENOTE NULLS. *

* WRITE THE DATA TO SYSREC01. *

* INCREMENT DATA RECORD COUNTER. *

* END. *

* *

****************************************************************

* **OPEN CURSOR

EXEC SQL OPEN DT END-EXEC.

PERFORM BLANK-REC.

EXEC SQL FETCH DT USING DESCRIPTOR :SQLDA END-EXEC.

* **NO ROWS FOUND

* **PRINT ERROR MESSAGE

IF SQLCODE = NOT-FOUND

WRITE MSGREC FROM MSG-NOROW

AFTER ADVANCING 2 LINES

ELSE

* **WRITE ROW AND

* **CONTINUE UNTIL

* **NO MORE ROWS

PERFORM WRITE-AND-FETCH

UNTIL SQLCODE IS NOT EQUAL TO ZERO.

*

EXEC SQL WHENEVER NOT FOUND GOTO CLOSEDT END-EXEC.

*

CLOSEDT.

EXEC SQL CLOSE DT END-EXEC.

*

****************************************************************

* *

* INDICATE THE RESULTS OF THE UNLOAD OPERATION. *

* *

****************************************************************

IND-RESULT.

MOVE TNAME TO TABLENAM.

MOVE ROWCOUNT TO ROWS.

WRITE MSGREC FROM UNLOADED


GO TO PROG-END.

*

WRITE-AND-FETCH.

* ADD IN MARKERS TO DENOTE NULLS.

MOVE ONE TO INDCOUNT.

PERFORM NULLCHK UNTIL INDCOUNT = SQLD.

MOVE REC1-LEN TO REC01-LEN.

WRITE REC01 FROM LINKAREA-REC.

ADD ONE TO ROWCOUNT.

PERFORM BLANK-REC.

EXEC SQL FETCH DT USING DESCRIPTOR :SQLDA END-EXEC.

*

NULLCHK.

IF IND(INDCOUNT) < 0 THEN

SET ADDRESS OF LINKAREA-QMARK TO WORKINDPTR(INDCOUNT)

MOVE QMARK TO INDREC.

ADD ONE TO INDCOUNT.



*****************************************************

* BLANK OUT RECORD TEXT FIRST *

*****************************************************

BLANK-REC.

MOVE ONE TO J.

PERFORM BLANK-MORE UNTIL J > REC1-LEN.

BLANK-MORE.

MOVE ’ ’ TO REC1-CHAR(J).

ADD ONE TO J.

*

COLADDR.

SET SQLDATA(I) TO RECPTR.

****************************************************************

*

* DETERMINE THE LENGTH OF THIS COLUMN (COLUMN-LEN)

* THIS DEPENDS ON THE DATA TYPE. MOST DATA TYPES HAVE

* THE LENGTH SET, BUT VARCHAR, GRAPHIC, VARGRAPHIC, AND

* DECIMAL DATA NEED TO HAVE THE BYTES CALCULATED.

* THE NULL ATTRIBUTE MUST BE SEPARATED TO SIMPLIFY MATTERS.

*

****************************************************************

MOVE SQLLEN(I) TO COLUMN-LEN.

* COLUMN-IND IS 0 FOR NO NULLS AND 1 FOR NULLS

DIVIDE SQLTYPE(I) BY TWO GIVING DUMMY REMAINDER COLUMN-IND.

* MYTYPE IS JUST THE SQLTYPE WITHOUT THE NULL BIT

MOVE SQLTYPE(I) TO MYTYPE.

SUBTRACT COLUMN-IND FROM MYTYPE.

* SET THE COLUMN LENGTH, DEPENDENT ON DATA TYPE

EVALUATE MYTYPE

WHEN CHARTYPE CONTINUE,

WHEN DATETYP CONTINUE,

WHEN TIMETYP CONTINUE,

WHEN TIMESTMP CONTINUE,

WHEN FLOATYPE CONTINUE,

WHEN VARCTYPE

ADD TWO TO COLUMN-LEN,

WHEN VARLTYPE

ADD TWO TO COLUMN-LEN,

WHEN GTYPE

MULTIPLY COLUMN-LEN BY TWO GIVING COLUMN-LEN,

WHEN VARGTYPE

PERFORM CALC-VARG-LEN,

WHEN LVARGTYP

PERFORM CALC-VARG-LEN,

WHEN HWTYPE

MOVE TWO TO COLUMN-LEN,

WHEN INTTYPE

MOVE FOUR TO COLUMN-LEN,

WHEN DECTYPE

PERFORM CALC-DECIMAL-LEN,

WHEN OTHER

PERFORM UNRECOGNIZED-ERROR,

END-EVALUATE.

ADD COLUMN-LEN TO RECNUM.

ADD COLUMN-LEN TO REC1-LEN.



Sample dynamic and static SQL in a C program

Figure 297 on page 1138 illustrates dynamic SQL and static SQL embedded in a C

program. Each section of the program is identified with a comment. Section 1 of

the program shows static SQL; sections 2, 3, and 4 show dynamic SQL. The

function of each section is explained in detail in the prologue to the program.

****************************************************************

* *

* IF THIS COLUMN CAN BE NULL, AN INDICATOR VARIABLE IS *

* NEEDED. WE ALSO RESERVE SPACE IN THE OUTPUT RECORD TO *

* NOTE THAT THE VALUE IS NULL. *

* *

****************************************************************

MOVE ZERO TO IND(I).

IF COLUMN-IND = ONE THEN

SET SQLIND(I) TO ADDRESS OF IND(I)

SET WORKINDPTR(I) TO RECPTR

ADD ONE TO RECNUM

ADD ONE TO REC1-LEN.

*

ADD ONE TO I.

* PERFORMED PARAGRAPH TO CALCULATE COLUMN LENGTH

* FOR A DECIMAL DATA TYPE COLUMN

CALC-DECIMAL-LEN.

DIVIDE COLUMN-LEN BY 256 GIVING COLUMN-PREC

REMAINDER COLUMN-SCALE.

MOVE COLUMN-PREC TO COLUMN-LEN.

ADD ONE TO COLUMN-LEN.

DIVIDE COLUMN-LEN BY TWO GIVING COLUMN-LEN.

* PERFORMED PARAGRAPH TO CALCULATE COLUMN LENGTH

* FOR A VARGRAPHIC DATA TYPE COLUMN

CALC-VARG-LEN.

MULTIPLY COLUMN-LEN BY TWO GIVING COLUMN-LEN.

ADD TWO TO COLUMN-LEN.

* PERFORMED PARAGRAPH TO NOTE AN UNRECOGNIZED

* DATA TYPE COLUMN

UNRECOGNIZED-ERROR.

*

* ERROR MESSAGE FOR UNRECOGNIZED DATA TYPE

*

MOVE SQLTYPE(I) TO TYPCOD.

WRITE MSGREC FROM BADTYPE


GO TO IND-RESULT.

*

*****************************************************

* SQL ERROR OCCURRED - GET MESSAGE *

*****************************************************

DBERROR.

* **SQL ERROR

MOVE SQLCODE TO MSG-PRINT-CODE.

IF SQLCODE < 0 THEN MOVE ’-’ TO MSG-MINUS.

WRITE MSGREC FROM MSG-SQLERR


CALL ’DSNTIAR’ USING SQLCA ERROR-MESSAGE ERROR-TEXT-LEN.

IF RETURN-CODE = ZERO

PERFORM ERROR-PRINT VARYING ERROR-INDEX

FROM 1 BY 1 UNTIL ERROR-INDEX GREATER THAN 8

ELSE

* **ERROR FOUND IN DSNTIAR

* **PRINT ERROR MESSAGE

MOVE RETURN-CODE TO RETCODE

WRITE MSGREC FROM MSGRETCD


GO TO PROG-END.

*

*****************************************************

* PRINT MESSAGE TEXT *

*****************************************************

ERROR-PRINT.

WRITE MSGREC FROM ERROR-TEXT (ERROR-INDEX)

AFTER ADVANCING 1 LINE.



/**********************************************************************/

/* Descriptive name = Dynamic SQL sample using C language */

/* */

/* Function = To show examples of the use of dynamic and static */

/* SQL. */

/* */

/* Notes = This example assumes that the EMP and DEPT tables are */

/* defined. They need not be the same as the DB2 Sample */

/* tables. */

/* */

/* Module type = C program */

/* Processor = DB2 precompiler, C compiler */

/* Module size = see link edit */

/* Attributes = not reentrant or reusable */

/* */

/* Input = */

/* */

/* symbolic label/name = DEPT */

/* description = arbitrary table */

/* symbolic label/name = EMP */

/* description = arbitrary table */

/* */

/* Output = */

/* */

/* symbolic label/name = SYSPRINT */

/* description = print results via printf */

/* */

/* Exit-normal = return code 0 normal completion */

/* */

/* Exit-error = */

/* */

/* Return code = SQLCA */

/* */

/* Abend codes = none */

/* */

/* External references = none */

/* */

/* Control-blocks = */

/* SQLCA - sql communication area */

/* */

Figure 297. Sample SQL in a C program (Part 1 of 4)


/* Logic specification: */

/* */

/* There are four SQL sections. */

/* */

/* 1) STATIC SQL 1: using static cursor with a SELECT statement. */

/* Two output host variables. */

/* 2) Dynamic SQL 2: Fixed-list SELECT, using same SELECT statement */

/* used in SQL 1 to show the difference. The prepared string */

/* :iptstr can be assigned with other dynamic-able SQL statements. */

/* 3) Dynamic SQL 3: Insert with parameter markers. */

/* Using four parameter markers which represent four input host */

/* variables within a host structure. */

/* 4) Dynamic SQL 4: EXECUTE IMMEDIATE */

/* A GRANT statement is executed immediately by passing it to DB2 */

/* via a varying string host variable. The example shows how to */

/* set up the host variable before passing it. */

/* */

/**********************************************************************/

#include "stdio.h"

#include "stdefs.h"

EXEC SQL INCLUDE SQLCA;

EXEC SQL INCLUDE SQLDA;


short edlevel;

struct { short len;

char x1[56];

} stmtbf1, stmtbf2, inpstr;

struct { short len;

char x1[15];

} lname;

short hv1;

struct { char deptno[4];

struct { short len;

char x[36];

} deptname;

char mgrno[7];

char admrdept[4];

} hv2;

short ind[4];


EXEC SQL DECLARE EMP TABLE

(EMPNO CHAR(6) ,

FIRSTNAME VARCHAR(12) ,

MIDINIT CHAR(1) ,

LASTNAME VARCHAR(15) ,

WORKDEPT CHAR(3) ,

PHONENO CHAR(4) ,

HIREDATE DECIMAL(6) ,

JOBCODE DECIMAL(3) ,

EDLEVEL SMALLINT ,

SEX CHAR(1) ,

BIRTHDATE DECIMAL(6) ,

SALARY DECIMAL(8,2) ,

FORFNAME VARGRAPHIC(12) ,

FORMNAME GRAPHIC(1) ,

FORLNAME VARGRAPHIC(15) ,

FORADDR VARGRAPHIC(256) ) ;



EXEC SQL DECLARE DEPT TABLE

(

DEPTNO CHAR(3) ,

DEPTNAME VARCHAR(36) ,

MGRNO CHAR(6) ,

ADMRDEPT CHAR(3) );

main ()

{

printf("??/n*** begin of program ***");

EXEC SQL WHENEVER SQLERROR GO TO HANDLERR;

EXEC SQL WHENEVER SQLWARNING GO TO HANDWARN;

EXEC SQL WHENEVER NOT FOUND GO TO NOTFOUND;

/******************************************************************/

/* Assign values to host variables which will be input to DB2 */

/******************************************************************/

strcpy(hv2.deptno,"M92");

strcpy(hv2.deptname.x,"DDL");

hv2.deptname.len = strlen(hv2.deptname.x);

strcpy(hv2.mgrno,"123456");

strcpy(hv2.admrdept,"abc");

/******************************************************************/

/* Static SQL 1: DECLARE CURSOR, OPEN, FETCH, CLOSE */

/* Select into :edlevel, :lname */

/******************************************************************/

printf("??/n*** begin declare ***");

EXEC SQL DECLARE C1 CURSOR FOR SELECT EDLEVEL, LASTNAME FROM EMP

WHERE EMPNO = ’000010’;

printf("??/n*** begin open ***");

EXEC SQL OPEN C1;

printf("??/n*** begin fetch ***");

EXEC SQL FETCH C1 INTO :edlevel, :lname;

printf("??/n*** returned values ***");

printf("??/n??/nedlevel = %d",edlevel);

printf("??/nlname = %s\n",lname.x1);

printf("??/n*** begin close ***");

EXEC SQL CLOSE C1;

/******************************************************************/

/* Dynamic SQL 2: PREPARE, DECLARE CURSOR, OPEN, FETCH, CLOSE */

/* Select into :edlevel, :lname */

/******************************************************************/

sprintf (inpstr.x1,

"SELECT EDLEVEL, LASTNAME FROM EMP WHERE EMPNO = ’000010’");

inpstr.len = strlen(inpstr.x1);

printf("??/n*** begin prepare ***");

EXEC SQL PREPARE STAT1 FROM :inpstr;

printf("??/n*** begin declare ***");

EXEC SQL DECLARE C2 CURSOR FOR STAT1;

printf("??/n*** begin open ***");

EXEC SQL OPEN C2;

printf("??/n*** begin fetch ***");

EXEC SQL FETCH C2 INTO :edlevel, :lname;

printf("??/n*** returned values ***");

printf("??/n??/nedlevel = %d",edlevel);

printf("??/nlname = %s\n",lname.x1);

printf("??/n*** begin close ***");

EXEC SQL CLOSE C2;



Sample DB2 REXX application

The following example shows a complete DB2 REXX application named DRAW.

DRAW must be invoked from the command line of an ISPF edit session. DRAW

takes a table or view name as input and produces a SELECT, INSERT, or UPDATE

SQL statement or a LOAD utility control statement that includes the columns of

the table as output.

DRAW syntax:

�� %DRAW object-name (

SSID=ssid

SELECT

TYPE=

INSERT

UPDATE

LOAD

��

DRAW parameters:

/******************************************************************/

/* Dynamic SQL 3: PREPARE with parameter markers */

/* Insert into with four values. */

/******************************************************************/

sprintf (stmtbf1.x1,

"INSERT INTO DEPT VALUES (?,?,?,?)");

stmtbf1.len = strlen(stmtbf1.x1);

printf("??/n*** begin prepare ***");

EXEC SQL PREPARE s1 FROM :stmtbf1;

printf("??/n*** begin execute ***");

EXEC SQL EXECUTE s1 USING :hv2:ind;

printf("??/n*** following are expected insert results ***");

printf("??/n hv2.deptno = %s",hv2.deptno);

printf("??/n hv2.deptname.len = %d",hv2.deptname.len);

printf("??/n hv2.deptname.x = %s",hv2.deptname.x);

printf("??/n hv2.mgrno = %s",hv2.mgrno);

printf("??/n hv2.admrdept = %s",hv2.admrdept);

EXEC SQL COMMIT;

/******************************************************************/

/* Dynamic SQL 4: EXECUTE IMMEDIATE */

/* Grant select */

/******************************************************************/

sprintf (stmtbf2.x1,

"GRANT SELECT ON EMP TO USERX");

stmtbf2.len = strlen(stmtbf2.x1);

printf("??/n*** begin execute immediate ***");

EXEC SQL EXECUTE IMMEDIATE :stmtbf2;

printf("??/n*** end of program ***");

goto progend;

HANDWARN: HANDLERR: NOTFOUND: ;

printf("??/n SQLCODE = %d",SQLCODE);

printf("??/n SQLWARN0 = %c",SQLWARN0);








progend: ;

}



object-name

The name of the table or view for which DRAW builds an SQL statement or

utility control statement. The name can be a one-, two-, or three-part name.

The table or view to which object-name refers must exist before DRAW can run.

object-name is a required parameter.

SSID=ssid

Specifies the name of the local DB2 subsystem.

S can be used as an abbreviation for SSID.

If you invoke DRAW from the command line of the edit session in SPUFI,

SSID=ssid is an optional parameter. DRAW uses the subsystem ID from the

DB2I Defaults panel.

TYPE=operation-type

The type of statement that DRAW builds.

T can be used as an abbreviation for TYPE.

operation-type has one of the following values:

SELECT Builds a SELECT statement in which the result table contains

all columns of object-name.

S can be used as an abbreviation for SELECT.

INSERT Builds a template for an INSERT statement that inserts values

into all columns of object-name. The template contains

comments that indicate where the user can place column

values.

I can be used as an abbreviation for INSERT.

UPDATE Builds a template for an UPDATE statement that updates

columns of object-name. The template contains comments that

indicate where the user can place column values and qualify

the update operation for selected rows.

U can be used as an abbreviation for UPDATE.

LOAD Builds a template for a LOAD utility control statement for

object-name.

L can be used as an abbreviation for LOAD.

TYPE=operation-type is an optional parameter. The default is TYPE=SELECT.

DRAW data sets:

Edit data set

The data set from which you issue the DRAW command when you are in an

ISPF edit session. If you issue the DRAW command from a SPUFI session, this

data set is the data set that you specify in field 1 of the main SPUFI panel

(DSNESP01). The output from the DRAW command goes into this data set.

DRAW return codes:

Return code Meaning


12 An error occurred when DRAW edited the input file.

20 One of the following errors occurred:


v No input parameters were specified.

v One of the input parameters was not valid.

v An SQL error occurred when the output statement was

generated.

Examples of DRAW invocation:

Generate a SELECT statement for table DSN8910.EMP at the local subsystem. Use

the default DB2I subsystem ID.

The DRAW invocation is:

DRAW DSN8910.EMP (TYPE=SELECT

The output is:

SELECT "EMPNO" , "FIRSTNME" , "MIDINIT" , "LASTNAME" , "WORKDEPT" ,

"PHONENO" , "HIREDATE" , "JOB" , "EDLEVEL" , "SEX" , "BIRTHDATE" ,

"SALARY" , "BONUS" , "COMM"

FROM DSN8910.EMP

Generate a template for an INSERT statement that inserts values into table

DSN8910.EMP at location SAN_JOSE. The local subsystem ID is DSN.


DRAW SAN_JOSE.DSN8910.EMP (TYPE=INSERT SSID=DSN

The output is:

INSERT INTO SAN_JOSE.DSN8910.EMP ( "EMPNO" , "FIRSTNME" , "MIDINIT" ,

"LASTNAME" , "WORKDEPT" , "PHONENO" , "HIREDATE" , "JOB" ,

"EDLEVEL" , "SEX" , "BIRTHDATE" , "SALARY" , "BONUS" , "COMM" )

VALUES (

-- ENTER VALUES BELOW COLUMN NAME DATA TYPE

, -- EMPNO CHAR(6) NOT NULL

, -- FIRSTNME VARCHAR(12) NOT NULL

, -- MIDINIT CHAR(1) NOT NULL

, -- LASTNAME VARCHAR(15) NOT NULL

, -- WORKDEPT CHAR(3)

, -- PHONENO CHAR(4)

, -- HIREDATE DATE

, -- JOB CHAR(8)

, -- EDLEVEL SMALLINT

, -- SEX CHAR(1)

, -- BIRTHDATE DATE

, -- SALARY DECIMAL(9,2)

, -- BONUS DECIMAL(9,2)

) -- COMM DECIMAL(9,2)

Generate a template for an UPDATE statement that updates values of table

DSN8910.EMP. The local subsystem ID is DSN.


DRAW DSN8910.EMP (TYPE=UPDATE SSID=DSN

The output is:

UPDATE DSN8910.EMP SET

-- COLUMN NAME ENTER VALUES BELOW DATA TYPE

"EMPNO"= -- CHAR(6) NOT NULL

, "FIRSTNME"= -- VARCHAR(12) NOT NULL

, "MIDINIT"= -- CHAR(1) NOT NULL

, "LASTNAME"= -- VARCHAR(15) NOT NULL


, "WORKDEPT"= -- CHAR(3)

, "PHONENO"= -- CHAR(4)

, "HIREDATE"= -- DATE

, "JOB"= -- CHAR(8)

, "EDLEVEL"= -- SMALLINT

, "SEX"= -- CHAR(1)

, "BIRTHDATE"= -- DATE

, "SALARY"= -- DECIMAL(9,2)

, "BONUS"= -- DECIMAL(9,2)

, "COMM"= -- DECIMAL(9,2)

WHERE

Generate a LOAD control statement to load values into table DSN8910.EMP. The

local subsystem ID is DSN.

The draw invocation is:

DRAW DSN8910.EMP (TYPE=LOAD SSID=DSN

The output is:

LOAD DATA INDDN SYSREC INTO TABLE DSN8910.EMP

( "EMPNO" POSITION( 1) CHAR(6)

, "FIRSTNME" POSITION( 8) VARCHAR

, "MIDINIT" POSITION( 21) CHAR(1)

, "LASTNAME" POSITION( 23) VARCHAR

, "WORKDEPT" POSITION( 39) CHAR(3)

NULLIF( 39)=’?’

, "PHONENO" POSITION( 43) CHAR(4)

NULLIF( 43)=’?’

, "HIREDATE" POSITION( 48) DATE EXTERNAL

NULLIF( 48)=’?’

, "JOB" POSITION( 59) CHAR(8)

NULLIF( 59)=’?’

, "EDLEVEL" POSITION( 68) SMALLINT

NULLIF( 68)=’?’

, "SEX" POSITION( 71) CHAR(1)

NULLIF( 71)=’?’

, "BIRTHDATE" POSITION( 73) DATE EXTERNAL

NULLIF( 73)=’?’

, "SALARY" POSITION( 84) DECIMAL EXTERNAL(9,2)

NULLIF( 84)=’?’

, "BONUS" POSITION( 90) DECIMAL EXTERNAL(9,2)

NULLIF( 90)=’?’

, "COMM" POSITION( 96) DECIMAL EXTERNAL(9,2)

NULLIF( 96)=’?’

)

DRAW source code:


/* REXX ***************************************************************/

L1 = WHEREAMI()

/*

DRAW creates basic SQL queries by retrieving the description of a

table. You must specify the name of the table or view to be queried.

You can specify the type of query you want to compose. You might need

to specify the name of the DB2 subsystem.

>>--DRAW-----tablename-----|---------------------------|-------><

|-(-|-Ssid=subsystem-name-|-|

| +-Select-+ |

|-Type=-|-Insert-|----|

|-Update-|

+--Load--+

Ssid=subsystem-name

subsystem-name specified the name of a DB2 subsystem.

Select

Composes a basic query for selecting data from the columns of a

table or view. If TYPE is not specified, SELECT is assumed.

Using SELECT with the DRAW command produces a query that would

retrieve all rows and all columns from the specified table. You

can then modify the query as needed.

A SELECT query of EMP composed by DRAW looks like this:




FROM DSN8910.EMP

If you include a location qualifier, the query looks like this:




FROM STLEC1.DSN8910.EMP

Figure 298. REXX sample program DRAW (Part 1 of 10)


To use this SELECT query, type the other clauses you need. If

you are selecting from more than one table, use a DRAW command

for each table name you want represented.

Insert

Composes a basic query to insert data into the columns of a table

or view.

The following example shows an INSERT query of EMP that

DRAW composed:

INSERT INTO DSN8910.EMP ( "EMPNO" , "FIRSTNME" , "MIDINIT" , "LASTNAME" ,

"WORKDEPT" , "PHONENO" , "HIREDATE" , "JOB" , "EDLEVEL" , "SEX" ,

"BIRTHDATE" , "SALARY" , "BONUS" , "COMM" )

VALUES (

-- ENTER VALUES BELOW COLUMN NAME DATA TYPE

, -- EMPNO CHAR(6) NOT NULL

, -- FIRSTNME VARCHAR(12) NOT NULL

, -- MIDINIT CHAR(1) NOT NULL

, -- LASTNAME VARCHAR(15) NOT NULL

, -- WORKDEPT CHAR(3)

, -- PHONENO CHAR(4)

, -- HIREDATE DATE

, -- JOB CHAR(8)

, -- EDLEVEL SMALLINT

, -- SEX CHAR(1)

, -- BIRTHDATE DATE

, -- SALARY DECIMAL(9,2)

, -- BONUS DECIMAL(9,2)

) -- COMM DECIMAL(9,2)

To insert values into EMP, type values to the left of the

column names.

Update

Composes a basic query to change the data in a table or view.

The following example shows an UPDATE query of EMP composed

by DRAW:



UPDATE DSN8910.EMP SET

-- COLUMN NAME ENTER VALUES BELOW DATA TYPE

"EMPNO"= -- CHAR(6) NOT NULL

, "FIRSTNME"= -- VARCHAR(12) NOT NULL

, "MIDINIT"= -- CHAR(1) NOT NULL

, "LASTNAME"= -- VARCHAR(15) NOT NULL

, "WORKDEPT"= -- CHAR(3)

, "PHONENO"= -- CHAR(4)

, "HIREDATE"= -- DATE

, "JOB"= -- CHAR(8)

, "EDLEVEL"= -- SMALLINT

, "SEX"= -- CHAR(1)

, "BIRTHDATE"= -- DATE

, "SALARY"= -- DECIMAL(9,2)

, "BONUS"= -- DECIMAL(9,2)

, "COMM"= -- DECIMAL(9,2)

WHERE

To use this UPDATE query, type the changes you want to make to

the right of the column names, and delete the lines you don’t

need. Be sure to complete the WHERE clause.

Load

Composes a load statement to load the data in a table.

The following example shows a LOAD statement of EMP composed

by DRAW:

LOAD DATA INDDN SYSREC INTO TABLE DSN8910 .EMP

( "EMPNO" POSITION( 1) CHAR(6)

, "FIRSTNME" POSITION( 8) VARCHAR

, "MIDINIT" POSITION( 21) CHAR(1)

, "LASTNAME" POSITION( 23) VARCHAR

, "WORKDEPT" POSITION( 39) CHAR(3)

NULLIF( 39)=’?’

, "PHONENO" POSITION( 43) CHAR(4)

NULLIF( 43)=’?’

, "HIREDATE" POSITION( 48) DATE EXTERNAL

NULLIF( 48)=’?’

, "JOB" POSITION( 59) CHAR(8)

NULLIF( 59)=’?’

, "EDLEVEL" POSITION( 68) SMALLINT

NULLIF( 68)=’?’

, "SEX" POSITION( 71) CHAR(1)

NULLIF( 71)=’?’

, "BIRTHDATE" POSITION( 73) DATE EXTERNAL

NULLIF( 73)=’?’

, "SALARY" POSITION( 84) DECIMAL EXTERNAL(9,2)

NULLIF( 84)=’?’

, "BONUS" POSITION( 90) DECIMAL EXTERNAL(9,2)

NULLIF( 90)=’?’

, "COMM" POSITION( 96) DECIMAL EXTERNAL(9,2)

NULLIF( 96)=’?’

)



To use this LOAD statement, type the changes you want to make,

and delete the lines you don’t need.

*/

L2 = WHEREAMI()

/**********************************************************************/

/* TRACE ?R */

/**********************************************************************/

Address ISPEXEC

"ISREDIT MACRO (ARGS) NOPROCESS"

If ARGS = "" Then

Do

Do I = L1+2 To L2-2;Say SourceLine(I);End

Exit (20)

End

Parse Upper Var Args Table "(" Parms

Parms = Translate(Parms," ",",")

Type = "SELECT" /* Default */

SSID = "" /* Default */

"VGET (DSNEOV01)"

If RC = 0 Then SSID = DSNEOV01

If (Parms <> "") Then

Do Until(Parms = "")

Parse Var Parms Var "=" Value Parms

If Var = "T" | Var = "TYPE" Then Type = Value

Else

If Var = "S" | Var = "SSID" Then SSID = Value

Else

Exit (20)

End

"CONTROL ERRORS RETURN"

"ISREDIT (LEFTBND,RIGHTBND) = BOUNDS"

"ISREDIT (LRECL) = DATA_WIDTH" /*LRECL*/

BndSize = RightBnd - LeftBnd + 1

If BndSize > 72 Then BndSize = 72

"ISREDIT PROCESS DEST"

Select

When rc = 0 Then

’ISREDIT (ZDEST) = LINENUM .ZDEST’

When rc <= 8 Then /* No A or B entered */

Do

zedsmsg = ’Enter "A"/"B" line cmd’

zedlmsg = ’DRAW requires an "A" or "B" line command’

’SETMSG MSG(ISRZ001)’

Exit 12

End

When rc < 20 Then /* Conflicting line commands - edit sets message */

Exit 12

When rc = 20 Then

zdest = 0

Otherwise

Exit 12

End



SQLTYPE. = "UNKNOWN TYPE"

VCHTYPE = 448; SQLTYPES.VCHTYPE = ’VARCHAR’

CHTYPE = 452; SQLTYPES.CHTYPE = ’CHAR’

LVCHTYPE = 456; SQLTYPES.LVCHTYPE = ’VARCHAR’

VGRTYP = 464; SQLTYPES.VGRTYP = ’VARGRAPHIC’

GRTYP = 468; SQLTYPES.GRTYP = ’GRAPHIC’

LVGRTYP = 472; SQLTYPES.LVGRTYP = ’VARGRAPHIC’

FLOTYPE = 480; SQLTYPES.FLOTYPE = ’FLOAT’

DCTYPE = 484; SQLTYPES.DCTYPE = ’DECIMAL’

INTYPE = 496; SQLTYPES.INTYPE = ’INTEGER’

SMTYPE = 500; SQLTYPES.SMTYPE = ’SMALLINT’

DATYPE = 384; SQLTYPES.DATYPE = ’DATE’

TITYPE = 388; SQLTYPES.TITYPE = ’TIME’

TSTYPE = 392; SQLTYPES.TSTYPE = ’TIMESTAMP’

Address TSO "SUBCOM DSNREXX" /* HOST CMD ENV AVAILABLE? */

IF RC THEN /* NO, LET’S MAKE ONE */

S_RC = RXSUBCOM(’ADD’,’DSNREXX’,’DSNREXX’) /* ADD HOST CMD ENV */

Address DSNREXX "CONNECT" SSID

If SQLCODE ^= 0 Then Call SQLCA

Address DSNREXX "EXECSQL DESCRIBE TABLE :TABLE INTO :SQLDA"


Address DSNREXX "EXECSQL COMMIT"

Address DSNREXX "DISCONNECT"


Select

When (Left(Type,1) = "S") Then

Call DrawSelect

When (Left(Type,1) = "I") Then

Call DrawInsert

When (Left(Type,1) = "U") Then

Call DrawUpdate

When (Left(Type,1) = "L") Then

Call DrawLoad

Otherwise EXIT (20)

End

Do I = LINE.0 To 1 By -1

LINE = COPIES(" ",LEFTBND-1)||LINE.I

’ISREDIT LINE_AFTER ’zdest’ = DATALINE (Line)’

End

line1 = zdest + 1

’ISREDIT CURSOR = ’line1 0

Exit



/**********************************************************************/

WHEREAMI:; RETURN SIGL

/**********************************************************************/

/* Draw SELECT */

/**********************************************************************/

DrawSelect:

Line.0 = 0

Line = "SELECT"

Do I = 1 To SQLDA.SQLD

If I > 1 Then Line = Line ’,’

ColName = ’"’SQLDA.I.SQLNAME’"’

Null = SQLDA.I.SQLTYPE//2

If Length(Line)+Length(ColName)+LENGTH(" ,") > BndSize THEN

Do

L = Line.0 + 1; Line.0 = L

Line.L = Line

Line = " "

End

Line = Line ColName

End I

If Line ^= "" Then

Do

L = Line.0 + 1; Line.0 = L

Line.L = Line

Line = " "

End

L = Line.0 + 1; Line.0 = L

Line.L = "FROM" TABLE

Return

/**********************************************************************/

/* Draw INSERT */

/**********************************************************************/

DrawInsert:

Line.0 = 0

Line = "INSERT INTO" TABLE "("


If I > 1 Then Line = Line ’,’

ColName = ’"’SQLDA.I.SQLNAME’"’

If Length(Line)+Length(ColName) > BndSize THEN

Do

L = Line.0 + 1; Line.0 = L

Line.L = Line

Line = " "

End

Line = Line ColName

If I = SQLDA.SQLD Then Line = Line ’)’

End I

If Line ^= "" Then

Do

L = Line.0 + 1; Line.0 = L

Line.L = Line

Line = " "

End



L = Line.0 + 1; Line.0 = L

Line.L = " VALUES ("

L = Line.0 + 1; Line.0 = L

Line.L = ,

"-- ENTER VALUES BELOW COLUMN NAME DATA TYPE"


If SQLDA.SQLD > 1 & I < SQLDA.SQLD Then

Line = " , --"

Else

Line = " ) --"

Line = Line Left(SQLDA.I.SQLNAME,18)

Type = SQLDA.I.SQLTYPE

Null = Type//2

If Null Then Type = Type - 1

Len = SQLDA.I.SQLLEN

Prcsn = SQLDA.I.SQLLEN.SQLPRECISION

Scale = SQLDA.I.SQLLEN.SQLSCALE

Select

When (Type = CHTYPE ,

|Type = VCHTYPE ,

|Type = LVCHTYPE ,

|Type = GRTYP ,

|Type = VGRTYP ,

|Type = LVGRTYP ) THEN

Type = SQLTYPES.Type"("STRIP(LEN)")"

When (Type = FLOTYPE ) THEN

Type = SQLTYPES.Type"("STRIP((LEN*4)-11) ")"

When (Type = DCTYPE ) THEN

Type = SQLTYPES.Type"("STRIP(PRCSN)","STRIP(SCALE)")"

Otherwise

Type = SQLTYPES.Type

End

Line = Line Type

If Null = 0 Then

Line = Line "NOT NULL"

L = Line.0 + 1; Line.0 = L

Line.L = Line

End I

Return



/**********************************************************************/

/* Draw UPDATE */

/**********************************************************************/

DrawUpdate:

Line.0 = 1

Line.1 = "UPDATE" TABLE "SET"

L = Line.0 + 1; Line.0 = L

Line.L = ,

"-- COLUMN NAME ENTER VALUES BELOW DATA TYPE"


If I = 1 Then

Line = " "

Else

Line = " ,"

Line = Line Left(’"’SQLDA.I.SQLNAME’"=’,21)

Line = Line Left(" ",20)


Null = Type//2





Select


|Type = VCHTYPE ,

|Type = LVCHTYPE ,

|Type = GRTYP ,

|Type = VGRTYP ,






Type = SQLTYPES.Type"("STRIP(PRCSN)","STRIP(SCALE)")"

Otherwise


End

Line = Line "--" Type

If Null = 0 Then

Line = Line "NOT NULL"

L = Line.0 + 1; Line.0 = L

Line.L = Line

End I

L = Line.0 + 1; Line.0 = L

Line.L = "WHERE"

Return



/**********************************************************************/

/* Draw LOAD */

/**********************************************************************/

DrawLoad:

Line.0 = 1

Line.1 = "LOAD DATA INDDN SYSREC INTO TABLE" TABLE

Position = 1


If I = 1 Then

Line = " ("

Else

Line = " ,"

Line = Line Left(’"’SQLDA.I.SQLNAME’"’,20)

Line = Line "POSITION("RIGHT(POSITION,5)")"


Null = Type//2





Select


|Type = GRTYP ) THEN





Do

Type = SQLTYPES.Type "EXTERNAL"

Type = Type"("STRIP(PRCSN)","STRIP(SCALE)")"

Len = (PRCSN+2)%2

End

When (Type = DATYPE ,

|Type = TITYPE ,

|Type = TSTYPE ) THEN

Type = SQLTYPES.Type "EXTERNAL"

Otherwise


End

If (Type = GRTYP ,

|Type = VGRTYP ,


Len = Len * 2

If (Type = VCHTYPE ,

|Type = LVCHTYPE ,

|Type = VGRTYP ,


Len = Len + 2

Line = Line Type

L = Line.0 + 1; Line.0 = L



Line.L = Line

If Null = 1 Then

Do

Line = " "

Line = Line Left(’’,20)

Line = Line " NULLIF("RIGHT(POSITION,5)")=’?’"

L = Line.0 + 1; Line.0 = L

Line.L = Line

End

Position = Position + Len + 1

End I

L = Line.0 + 1; Line.0 = L

Line.L = " )"

Return

/**********************************************************************/

/* Display SQLCA */

/**********************************************************************/

SQLCA:

"ISREDIT LINE_AFTER "zdest" = MSGLINE ’SQLSTATE="SQLSTATE"’"

"ISREDIT LINE_AFTER "zdest" = MSGLINE ’SQLWARN ="SQLWARN.0",",

|| SQLWARN.1",",

|| SQLWARN.2",",

|| SQLWARN.3",",

|| SQLWARN.4",",

|| SQLWARN.5",",

|| SQLWARN.6",",

|| SQLWARN.7",",

|| SQLWARN.8",",

|| SQLWARN.9",",

|| SQLWARN.10"’"

"ISREDIT LINE_AFTER "zdest" = MSGLINE ’SQLERRD ="SQLERRD.1",",

|| SQLERRD.2",",

|| SQLERRD.3",",

|| SQLERRD.4",",

|| SQLERRD.5",",

|| SQLERRD.6"’"

"ISREDIT LINE_AFTER "zdest" = MSGLINE ’SQLERRP ="SQLERRP"’"

"ISREDIT LINE_AFTER "zdest" = MSGLINE ’SQLERRMC ="SQLERRMC"’"

"ISREDIT LINE_AFTER "zdest" = MSGLINE ’SQLCODE ="SQLCODE"’"

Exit 20



Sample COBOL program using DRDA access with CONNECT

statements

The following sample program demonstrates distributed data access using DRDA

access.


PROGRAM-ID. TWOPHASE.

AUTHOR.

REMARKS.

*****************************************************************

* *

* MODULE NAME = TWOPHASE *

* *

* DESCRIPTIVE NAME = DB2 SAMPLE APPLICATION USING *

* TWO PHASE COMMIT AND THE DRDA DISTRIBUTED *

* ACCESS METHOD WITH CONNECT STATEMENTS *

* *

* COPYRIGHT = 5665-DB2 (C) COPYRIGHT IBM CORP 1982, 1989 *

* REFER TO COPYRIGHT INSTRUCTIONS FORM NUMBER G120-2083 *

* *

* STATUS = VERSION 5 *

* *

* FUNCTION = THIS MODULE DEMONSTRATES DISTRIBUTED DATA ACCESS *

* USING 2 PHASE COMMIT BY TRANSFERRING AN EMPLOYEE *

* FROM ONE LOCATION TO ANOTHER. *

* *

* NOTE: THIS PROGRAM ASSUMES THE EXISTENCE OF THE *

* TABLE SYSADM.EMP AT LOCATIONS STLEC1 AND *

* STLEC2. *

* *


* PROCESSOR = DB2 PRECOMPILER, ENTERPRISE COBOL FOR Z/OS *


* ATTRIBUTES = NOT REENTRANT OR REUSABLE *

* *

* ENTRY POINT = *

* PURPOSE = TO ILLUSTRATE 2 PHASE COMMIT *

* LINKAGE = INVOKE FROM DSN RUN *

* INPUT = NONE *

* OUTPUT = *

* SYMBOLIC LABEL/NAME = SYSPRINT *

* DESCRIPTION = PRINT OUT THE DESCRIPTION OF EACH *

* STEP AND THE RESULTANT SQLCA *

* *

* EXIT NORMAL = RETURN CODE 0 FROM NORMAL COMPLETION *

* *

* EXIT ERROR = NONE *

* *


* ROUTINE SERVICES = NONE *




* *

* TABLES = NONE *

* *


* *

* *

* *

Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 1 of 8)


|

|

* PSEUDOCODE *

* *

* MAINLINE. *

* Perform CONNECT-TO-SITE-1 to establish *

* a connection to the local connection. *

* If the previous operation was successful Then *

* Do. *

* | Perform PROCESS-CURSOR-SITE-1 to obtain the *

* | information about an employee that is *

* | transferring to another location. *

* | If the information about the employee was obtained *

* | successfully Then *

* | Do. *

* | | Perform UPDATE-ADDRESS to update the information *

* | | to contain current information about the *

* | | employee. *

* | | Perform CONNECT-TO-SITE-2 to establish *

* | | a connection to the site where the employee is *

* | | transferring to. *

* | | If the connection is established successfully *

* | | Then *

* | | Do. *

* | | | Perform PROCESS-SITE-2 to insert the *

* | | | employee information at the location *

* | | | where the employee is transferring to. *

* | | End if the connection was established *

* | | successfully. *

* | End if the employee information was obtained *

* | successfully. *

* End if the previous operation was successful. *

* Perform COMMIT-WORK to COMMIT the changes made to STLEC1 *

* and STLEC2. *

* *

* PROG-END. *

* Close the printer. *

* Return. *

* *

* CONNECT-TO-SITE-1. *

* Provide a text description of the following step. *

* Establish a connection to the location where the *

* employee is transferring from. *

* Print the SQLCA out. *

* *

* PROCESS-CURSOR-SITE-1. *


* Open a cursor that will be used to retrieve information *

* about the transferring employee from this site. *


* If the cursor was opened successfully Then *

* Do. *

* | Perform FETCH-DELETE-SITE-1 to retrieve and *

* | delete the information about the transferring *

* | employee from this site. *

* | Perform CLOSE-CURSOR-SITE-1 to close the cursor. *

* End if the cursor was opened successfully. *

* *



* FETCH-DELETE-SITE-1. *


* Fetch information about the transferring employee. *


* If the information was retrieved successfully Then *

* Do. *

* | Perform DELETE-SITE-1 to delete the employee *

* | at this site. *

* End if the information was retrieved successfully. *

* *

* DELETE-SITE-1. *


* Delete the information about the transferring employee *

* from this site. *


* *

* CLOSE-CURSOR-SITE-1. *


* Close the cursor used to retrieve information about *

* the transferring employee. *


* *

* UPDATE-ADDRESS. *

* Update the address of the employee. *

* Update the city of the employee. *

* Update the location of the employee. *

* *

* CONNECT-TO-SITE-2. *


* Establish a connection to the location where the *

* employee is transferring to. *


* *

* PROCESS-SITE-2. *


* Insert the employee information at the location where *

* the employee is being transferred to. *


* *

* COMMIT-WORK. *

* COMMIT all the changes made to STLEC1 and STLEC2. *

* *

*****************************************************************



FILE-CONTROL.

SELECT PRINTER, ASSIGN TO S-OUT1.

DATA DIVISION.

FILE SECTION.

FD PRINTER


DATA RECORD IS PRT-TC-RESULTS

LABEL RECORD IS OMITTED.

01 PRT-TC-RESULTS.

03 PRT-BLANK PIC X(120).




*****************************************************************

* Variable declarations *

*****************************************************************

01 H-EMPTBL.

05 H-EMPNO PIC X(6).

05 H-NAME.

49 H-NAME-LN PIC S9(4) COMP-4.

49 H-NAME-DA PIC X(32).

05 H-ADDRESS.

49 H-ADDRESS-LN PIC S9(4) COMP-4.

49 H-ADDRESS-DA PIC X(36).

05 H-CITY.

49 H-CITY-LN PIC S9(4) COMP-4.

49 H-CITY-DA PIC X(36).

05 H-EMPLOC PIC X(4).

05 H-SSNO PIC X(11).

05 H-BORN PIC X(10).

05 H-SEX PIC X(1).

05 H-HIRED PIC X(10).

05 H-DEPTNO PIC X(3).

05 H-JOBCODE PIC S9(3)V COMP-3.

05 H-SRATE PIC S9(5) COMP.

05 H-EDUC PIC S9(5) COMP.

05 H-SAL PIC S9(6)V9(2) COMP-3.

05 H-VALIDCHK PIC S9(6)V COMP-3.

01 H-EMPTBL-IND-TABLE.

02 H-EMPTBL-IND PIC S9(4) COMP OCCURS 15 TIMES.

*****************************************************************

* Includes for the variables used in the COBOL standard *

* language procedures and the SQLCA. *

*****************************************************************

EXEC SQL INCLUDE COBSVAR END-EXEC.


*****************************************************************

* Declaration for the table that contains employee information *

*****************************************************************

EXEC SQL DECLARE SYSADM.EMP TABLE


NAME VARCHAR(32),

ADDRESS VARCHAR(36) ,

CITY VARCHAR(36) ,

EMPLOC CHAR(4) NOT NULL,

SSNO CHAR(11),

BORN DATE,

SEX CHAR(1),

HIRED CHAR(10),

DEPTNO CHAR(3) NOT NULL,

JOBCODE DECIMAL(3),

SRATE SMALLINT,

EDUC SMALLINT,



SAL DECIMAL(8,2) NOT NULL,

VALCHK DECIMAL(6))

END-EXEC.

*****************************************************************

* Constants *

*****************************************************************

77 SITE-1 PIC X(16) VALUE ’STLEC1’.

77 SITE-2 PIC X(16) VALUE ’STLEC2’.

77 TEMP-EMPNO PIC X(6) VALUE ’080000’.

77 TEMP-ADDRESS-LN PIC 99 VALUE 15.

77 TEMP-CITY-LN PIC 99 VALUE 18.

*****************************************************************

* Declaration of the cursor that will be used to retrieve *

* information about a transferring employee *

*****************************************************************


SELECT EMPNO, NAME, ADDRESS, CITY, EMPLOC,

SSNO, BORN, SEX, HIRED, DEPTNO, JOBCODE,

SRATE, EDUC, SAL, VALCHK

FROM SYSADM.EMP

WHERE EMPNO = :TEMP-EMPNO

END-EXEC.

PROCEDURE DIVISION.

A101-HOUSE-KEEPING.

OPEN OUTPUT PRINTER.

*****************************************************************

* An employee is transferring from location STLEC1 to STLEC2. *

* Retrieve information about the employee from STLEC1, delete *

* the employee from STLEC1 and insert the employee at STLEC2 *

* using the information obtained from STLEC1. *

*****************************************************************

MAINLINE.

PERFORM CONNECT-TO-SITE-1

IF SQLCODE IS EQUAL TO 0

PERFORM PROCESS-CURSOR-SITE-1


PERFORM UPDATE-ADDRESS

PERFORM CONNECT-TO-SITE-2


PERFORM PROCESS-SITE-2.

PERFORM COMMIT-WORK.



PROG-END.

CLOSE PRINTER.

GOBACK.

*****************************************************************

* Establish a connection to STLEC1 *

*****************************************************************

CONNECT-TO-SITE-1.

MOVE ’CONNECT TO STLEC1 ’ TO STNAME

WRITE PRT-TC-RESULTS FROM STNAME

EXEC SQL

CONNECT TO :SITE-1

END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* When a connection has been established successfully at STLEC1,*

* open the cursor that will be used to retrieve information *

* about the transferring employee. *

*****************************************************************

PROCESS-CURSOR-SITE-1.

MOVE ’OPEN CURSOR C1 ’ TO STNAME


EXEC SQL

OPEN C1

END-EXEC.

PERFORM PTSQLCA.

IF SQLCODE IS EQUAL TO ZERO

PERFORM FETCH-DELETE-SITE-1

PERFORM CLOSE-CURSOR-SITE-1.

*****************************************************************

* Retrieve information about the transferring employee. *

* Provided that the employee exists, perform DELETE-SITE-1 to *

* delete the employee from STLEC1. *

*****************************************************************

FETCH-DELETE-SITE-1.

MOVE ’FETCH C1 ’ TO STNAME


EXEC SQL

FETCH C1 INTO :H-EMPTBL:H-EMPTBL-IND

END-EXEC.

PERFORM PTSQLCA.


PERFORM DELETE-SITE-1.



*****************************************************************

* Delete the employee from STLEC1. *

*****************************************************************

DELETE-SITE-1.

MOVE ’DELETE EMPLOYEE ’ TO STNAME



EXEC SQL

DELETE FROM SYSADM.EMP


END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* Close the cursor used to retrieve information about the *

* transferring employee. *

*****************************************************************

CLOSE-CURSOR-SITE-1.

MOVE ’CLOSE CURSOR C1 ’ TO STNAME


EXEC SQL

CLOSE C1

END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* Update certain employee information in order to make it *

* current. *

*****************************************************************

UPDATE-ADDRESS.

MOVE TEMP-ADDRESS-LN TO H-ADDRESS-LN.

MOVE ’1500 NEW STREET’ TO H-ADDRESS-DA.

MOVE TEMP-CITY-LN TO H-CITY-LN.

MOVE ’NEW CITY, CA 97804’ TO H-CITY-DA.

MOVE ’SJCA’ TO H-EMPLOC.

*****************************************************************

* Establish a connection to STLEC2 *

*****************************************************************

CONNECT-TO-SITE-2.

MOVE ’CONNECT TO STLEC2 ’ TO STNAME


EXEC SQL

CONNECT TO :SITE-2

END-EXEC.

PERFORM PTSQLCA.



*****************************************************************

* Using the employee information that was retrieved from STLEC1 *

* and updated previously, insert the employee at STLEC2. *

*****************************************************************

PROCESS-SITE-2.

MOVE ’INSERT EMPLOYEE ’ TO STNAME


EXEC SQL

INSERT INTO SYSADM.EMP VALUES

(:H-EMPNO,

:H-NAME,

:H-ADDRESS,

:H-CITY,

:H-EMPLOC,

:H-SSNO,

:H-BORN,

:H-SEX,

:H-HIRED,

:H-DEPTNO,

:H-JOBCODE,

:H-SRATE,

:H-EDUC,

:H-SAL,

:H-VALIDCHK)

END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* COMMIT any changes that were made at STLEC1 and STLEC2. *

*****************************************************************

COMMIT-WORK.

MOVE ’COMMIT WORK ’ TO STNAME


EXEC SQL

COMMIT

END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* Include COBOL standard language procedures *

*****************************************************************

INCLUDE-SUBS.

EXEC SQL INCLUDE COBSSUB END-EXEC.



Sample COBOL program using DRDA with three-part names

The following sample program demonstrates distributed access data using DB2

private protocol access with two-phase commit.


PROGRAM-ID. TWOPHASE.

AUTHOR.

REMARKS.

*****************************************************************

* *

* MODULE NAME = TWOPHASE *

* *

* DESCRIPTIVE NAME = DB2 SAMPLE APPLICATION USING *

* TWO PHASE COMMIT AND DRDA WITH *

* THREE-PART NAMES *

* *

* COPYRIGHT = 5665-DB2 (C) COPYRIGHT IBM CORP 1982, 1989 *

* REFER TO COPYRIGHT INSTRUCTIONS FORM NUMBER G120-2083 *

* *

* STATUS = VERSION 5 *

* *

* FUNCTION = THIS MODULE DEMONSTRATES DISTRIBUTED DATA ACCESS *

* USING 2 PHASE COMMIT BY TRANSFERRING AN EMPLOYEE *

* FROM ONE LOCATION TO ANOTHER. *

* *

* NOTE: THIS PROGRAM ASSUMES THE EXISTENCE OF THE *

* TABLE SYSADM.EMP AT LOCATIONS STLEC1 AND *

* STLEC2. *

* *


* PROCESSOR = DB2 PRECOMPILER, ENTERPRISE COBOL FOR Z/OS *


* ATTRIBUTES = NOT REENTRANT OR REUSABLE *

* *

* ENTRY POINT = *

* PURPOSE = TO ILLUSTRATE 2 PHASE COMMIT *

* LINKAGE = INVOKE FROM DSN RUN *

* INPUT = NONE *

* OUTPUT = *

* SYMBOLIC LABEL/NAME = SYSPRINT *

* DESCRIPTION = PRINT OUT THE DESCRIPTION OF EACH *

* STEP AND THE RESULTANT SQLCA *

* *

* EXIT NORMAL = RETURN CODE 0 FROM NORMAL COMPLETION *

* *

* EXIT ERROR = NONE *

* *


* ROUTINE SERVICES = NONE *




* *

* TABLES = NONE *

* *


* *

* *

Figure 300. Sample COBOL two-phase commit application for DB2 private protocol access

(Part 1 of 7)


|

* *

* PSEUDOCODE *

* *

* MAINLINE. *

* Perform PROCESS-CURSOR-SITE-1 to obtain the information *

* about an employee that is transferring to another *

* location. *

* If the information about the employee was obtained *

* successfully Then *

* Do. *

* | Perform UPDATE-ADDRESS to update the information to *

* | contain current information about the employee. *

* | Perform PROCESS-SITE-2 to insert the employee *

* | information at the location where the employee is *

* | transferring to. *

* End if the employee information was obtained *

* successfully. *

* Perform COMMIT-WORK to COMMIT the changes made to STLEC1 *

* and STLEC2. *

* *

* PROG-END. *

* Close the printer. *

* Return. *

* *

* PROCESS-CURSOR-SITE-1. *


* Open a cursor that will be used to retrieve information *

* about the transferring employee from this site. *


* If the cursor was opened successfully Then *

* Do. *

* | Perform FETCH-DELETE-SITE-1 to retrieve and *

* | delete the information about the transferring *

* | employee from this site. *

* | Perform CLOSE-CURSOR-SITE-1 to close the cursor. *

* End if the cursor was opened successfully. *

* *

* FETCH-DELETE-SITE-1. *


* Fetch information about the transferring employee. *


* If the information was retrieved successfully Then *

* Do. *

* | Perform DELETE-SITE-1 to delete the employee *

* | at this site. *

* End if the information was retrieved successfully. *

* *

* DELETE-SITE-1. *


* Delete the information about the transferring employee *

* from this site. *


* *

* CLOSE-CURSOR-SITE-1. *


* Close the cursor used to retrieve information about *

* the transferring employee. *


* *


(Part 2 of 7)


* UPDATE-ADDRESS. *

* Update the address of the employee. *

* Update the city of the employee. *

* Update the location of the employee. *

* *

* PROCESS-SITE-2. *


* Insert the employee information at the location where *

* the employee is being transferred to. *


* *

* COMMIT-WORK. *

* COMMIT all the changes made to STLEC1 and STLEC2. *

* *

*****************************************************************



FILE-CONTROL.

SELECT PRINTER, ASSIGN TO S-OUT1.

DATA DIVISION.

FILE SECTION.

FD PRINTER


DATA RECORD IS PRT-TC-RESULTS

LABEL RECORD IS OMITTED.

01 PRT-TC-RESULTS.

03 PRT-BLANK PIC X(120).


*****************************************************************

* Variable declarations *

*****************************************************************

01 H-EMPTBL.

05 H-EMPNO PIC X(6).

05 H-NAME.

49 H-NAME-LN PIC S9(4) COMP-4.

49 H-NAME-DA PIC X(32).

05 H-ADDRESS.

49 H-ADDRESS-LN PIC S9(4) COMP-4.

49 H-ADDRESS-DA PIC X(36).

05 H-CITY.

49 H-CITY-LN PIC S9(4) COMP-4.

49 H-CITY-DA PIC X(36).

05 H-EMPLOC PIC X(4).

05 H-SSNO PIC X(11).

05 H-BORN PIC X(10).

05 H-SEX PIC X(1).

05 H-HIRED PIC X(10).

05 H-DEPTNO PIC X(3).

05 H-JOBCODE PIC S9(3)V COMP-3.

05 H-SRATE PIC S9(5) COMP.

05 H-EDUC PIC S9(5) COMP.

05 H-SAL PIC S9(6)V9(2) COMP-3.

05 H-VALIDCHK PIC S9(6)V COMP-3.


(Part 3 of 7)


01 H-EMPTBL-IND-TABLE.

02 H-EMPTBL-IND PIC S9(4) COMP OCCURS 15 TIMES.

*****************************************************************

* Includes for the variables used in the COBOL standard *

* language procedures and the SQLCA. *

*****************************************************************

EXEC SQL INCLUDE COBSVAR END-EXEC.


*****************************************************************

* Declaration for the table that contains employee information *

*****************************************************************

EXEC SQL DECLARE SYSADM.EMP TABLE


NAME VARCHAR(32),

ADDRESS VARCHAR(36) ,

CITY VARCHAR(36) ,

EMPLOC CHAR(4) NOT NULL,

SSNO CHAR(11),

BORN DATE,

SEX CHAR(1),

HIRED CHAR(10),

DEPTNO CHAR(3) NOT NULL,

JOBCODE DECIMAL(3),

SRATE SMALLINT,

EDUC SMALLINT,

SAL DECIMAL(8,2) NOT NULL,

VALCHK DECIMAL(6))

END-EXEC.

*****************************************************************

* Constants *

*****************************************************************

77 TEMP-EMPNO PIC X(6) VALUE ’080000’.

77 TEMP-ADDRESS-LN PIC 99 VALUE 15.

77 TEMP-CITY-LN PIC 99 VALUE 18.

*****************************************************************

* Declaration of the cursor that will be used to retrieve *

* information about a transferring employee *

*****************************************************************


SELECT EMPNO, NAME, ADDRESS, CITY, EMPLOC,

SSNO, BORN, SEX, HIRED, DEPTNO, JOBCODE,

SRATE, EDUC, SAL, VALCHK

FROM STLEC1.SYSADM.EMP


END-EXEC.


(Part 4 of 7)


PROCEDURE DIVISION.

A101-HOUSE-KEEPING.

OPEN OUTPUT PRINTER.

*****************************************************************

* An employee is transferring from location STLEC1 to STLEC2. *

* Retrieve information about the employee from STLEC1, delete *

* the employee from STLEC1 and insert the employee at STLEC2 *

* using the information obtained from STLEC1. *

*****************************************************************

MAINLINE.

PERFORM PROCESS-CURSOR-SITE-1


PERFORM UPDATE-ADDRESS

PERFORM PROCESS-SITE-2.

PERFORM COMMIT-WORK.

PROG-END.

CLOSE PRINTER.

GOBACK.

*****************************************************************

* Open the cursor that will be used to retrieve information *

* about the transferring employee. *

*****************************************************************

PROCESS-CURSOR-SITE-1.

MOVE ’OPEN CURSOR C1 ’ TO STNAME


EXEC SQL

OPEN C1

END-EXEC.

PERFORM PTSQLCA.


PERFORM FETCH-DELETE-SITE-1

PERFORM CLOSE-CURSOR-SITE-1.

*****************************************************************

* Retrieve information about the transferring employee. *

* Provided that the employee exists, perform DELETE-SITE-1 to *

* delete the employee from STLEC1. *

*****************************************************************

FETCH-DELETE-SITE-1.

MOVE ’FETCH C1 ’ TO STNAME


EXEC SQL

FETCH C1 INTO :H-EMPTBL:H-EMPTBL-IND

END-EXEC.


(Part 5 of 7)


PERFORM PTSQLCA.


PERFORM DELETE-SITE-1.

*****************************************************************

* Delete the employee from STLEC1. *

*****************************************************************

DELETE-SITE-1.




EXEC SQL

DELETE FROM STLEC1.SYSADM.EMP


END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* Close the cursor used to retrieve information about the *

* transferring employee. *

*****************************************************************

CLOSE-CURSOR-SITE-1.

MOVE ’CLOSE CURSOR C1 ’ TO STNAME


EXEC SQL

CLOSE C1

END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* Update certain employee information in order to make it *

* current. *

*****************************************************************

UPDATE-ADDRESS.

MOVE TEMP-ADDRESS-LN TO H-ADDRESS-LN.

MOVE ’1500 NEW STREET’ TO H-ADDRESS-DA.

MOVE TEMP-CITY-LN TO H-CITY-LN.

MOVE ’NEW CITY, CA 97804’ TO H-CITY-DA.

MOVE ’SJCA’ TO H-EMPLOC.


(Part 6 of 7)


Examples of using stored procedures

This section contains sample programs that you can refer to when programming

your stored procedure applications. DSN910.SDSNSAMP contains sample jobs

DSNTEJ6P and DSNTEJ6S and programs DSN8EP1 and DSN8EP2, which you can

run.

Calling a stored procedure from a C program

This example shows how to call the C language version of the GETPRML stored

procedure that uses the GENERAL WITH NULLS linkage convention. Because the

stored procedure returns result sets, this program checks for result sets and

retrieves the contents of the result sets.

*****************************************************************

* Using the employee information that was retrieved from STLEC1 *

* and updated previously, insert the employee at STLEC2. *

*****************************************************************

PROCESS-SITE-2.

MOVE ’INSERT EMPLOYEE ’ TO STNAME


EXEC SQL

INSERT INTO STLEC2.SYSADM.EMP VALUES

(:H-EMPNO,

:H-NAME,

:H-ADDRESS,

:H-CITY,

:H-EMPLOC,

:H-SSNO,

:H-BORN,

:H-SEX,

:H-HIRED,

:H-DEPTNO,

:H-JOBCODE,

:H-SRATE,

:H-EDUC,

:H-SAL,

:H-VALIDCHK)

END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* COMMIT any changes that were made at STLEC1 and STLEC2. *

*****************************************************************

COMMIT-WORK.

MOVE ’COMMIT WORK ’ TO STNAME


EXEC SQL

COMMIT

END-EXEC.

PERFORM PTSQLCA.

*****************************************************************

* Include COBOL standard language procedures *

*****************************************************************

INCLUDE-SUBS.

EXEC SQL INCLUDE COBSSUB END-EXEC.


(Part 7 of 7)


#include <stdio.h>

#include <stdlib.h>

#include <string.h>

main()

{

/************************************************************/

/* Include the SQLCA and SQLDA */

/************************************************************/


EXEC SQL INCLUDE SQLDA;

/************************************************************/

/* Declare variables that are not SQL-related. */

/************************************************************/

short int i; /* Loop counter */

/************************************************************/

/* Declare the following: */

/* - Parameters used to call stored procedure GETPRML */

/* - An SQLDA for DESCRIBE PROCEDURE */

/* - An SQLDA for DESCRIBE CURSOR */

/* - Result set variable locators for up to three result */

/* sets */

/************************************************************/


char procnm[19]; /* INPUT parm -- PROCEDURE name */

char schema[9]; /* INPUT parm -- User’s schema */

long int out_code; /* OUTPUT -- SQLCODE from the */

/* SELECT operation. */

struct {

short int parmlen;

char parmtxt[254];

} parmlst; /* OUTPUT -- RUNOPTS values */

/* for the matching row in */

/* catalog table SYSROUTINES */

struct indicators {

short int procnm_ind;

short int schema_ind;

short int out_code_ind;

short int parmlst_ind;

} parmind;

/* Indicator variable structure */

struct sqlda *proc_da;

/* SQLDA for DESCRIBE PROCEDURE */

struct sqlda *res_da;

/* SQLDA for DESCRIBE CURSOR */

static volatile

SQL TYPE IS RESULT_SET_LOCATOR *loc1, *loc2, *loc3;

/* Locator variables */


Figure 301. Calling a stored procedure from a C program (Part 1 of 4)


/*************************************************************/

/* Allocate the SQLDAs to be used for DESCRIBE */

/* PROCEDURE and DESCRIBE CURSOR. Assume that at most */

/* three cursors are returned and that each result set */

/* has no more than five columns. */

/*************************************************************/

proc_da = (struct sqlda *)malloc(SQLDASIZE(3));

res_da = (struct sqlda *)malloc(SQLDASIZE(5));

/************************************************************/

/* Call the GETPRML stored procedure to retrieve the */

/* RUNOPTS values for the stored procedure. In this */

/* example, we request the PARMLIST definition for the */

/* stored procedure named DSN8EP2. */

/* */

/* The call should complete with SQLCODE +466 because */

/* GETPRML returns result sets. */

/************************************************************/

strcpy(procnm,"dsn8ep2 ");

/* Input parameter -- PROCEDURE to be found */

strcpy(schema," ");

/* Input parameter -- Schema name for proc */

parmind.procnm_ind=0;

parmind.schema_ind=0;

parmind.out_code_ind=0;

/* Indicate that none of the input parameters */

/* have null values */

parmind.parmlst_ind=-1;

/* The parmlst parameter is an output parm. */

/* Mark PARMLST parameter as null, so the DB2 */

/* requester doesn’t have to send the entire */

/* PARMLST variable to the server. This */

/* helps reduce network I/O time, because */

/* PARMLST is fairly large. */

EXEC SQL

CALL GETPRML(:procnm INDICATOR :parmind.procnm_ind,

:schema INDICATOR :parmind.schema_ind,

:out_code INDICATOR :parmind.out_code_ind,

:parmlst INDICATOR :parmind.parmlst_ind);

if(SQLCODE!=+466) /* If SQL CALL failed, */

{

/* print the SQLCODE and any */

/* message tokens */

printf("SQL CALL failed due to SQLCODE = %d\n",SQLCODE);

printf("sqlca.sqlerrmc = ");

for(i=0;i<sqlca.sqlerrml;i++)

printf("%c",sqlca.sqlerrmc[i]);

printf("\n");

}



else /* If the CALL worked, */

if(out_code!=0) /* Did GETPRML hit an error? */

printf("GETPRML failed due to RC = %d\n",out_code);

/**********************************************************/

/* If everything worked, do the following: */

/* - Print out the parameters returned. */

/* - Retrieve the result sets returned. */

/**********************************************************/

else

{

printf("RUNOPTS = %s\n",parmlst.parmtxt);

/* Print out the runopts list */

/********************************************************/

/* Use the statement DESCRIBE PROCEDURE to */

/* return information about the result sets in the */

/* SQLDA pointed to by proc_da: */

/* - SQLD contains the number of result sets that were */

/* returned by the stored procedure. */

/* - Each SQLVAR entry has the following information */

/* about a result set: */

/* - SQLNAME contains the name of the cursor that */

/* the stored procedure uses to return the result */

/* set. */

/* - SQLIND contains an estimate of the number of */

/* rows in the result set. */

/* - SQLDATA contains the result locator value for */

/* the result set. */

/********************************************************/

EXEC SQL DESCRIBE PROCEDURE INTO :*proc_da;

/********************************************************/

/* Assume that you have examined SQLD and determined */

/* that there is one result set. Use the statement */

/* ASSOCIATE LOCATORS to establish a result set locator */

/* for the result set. */

/********************************************************/

EXEC SQL ASSOCIATE LOCATORS (:loc1) WITH PROCEDURE GETPRML;

/********************************************************/

/* Use the statement ALLOCATE CURSOR to associate a */

/* cursor for the result set. */

/********************************************************/

EXEC SQL ALLOCATE C1 CURSOR FOR RESULT SET :loc1;

/********************************************************/

/* Use the statement DESCRIBE CURSOR to determine the */

/* columns in the result set. */

/********************************************************/

EXEC SQL DESCRIBE CURSOR C1 INTO :*res_da;



Calling a stored procedure from a COBOL program

This example shows how to call a version of the GETPRML stored procedure that

uses the GENERAL WITH NULLS linkage convention from a COBOL program on

an z/OS system. Because the stored procedure returns result sets, this program

checks for result sets and retrieves the contents of the result sets.

/********************************************************/

/* Call a routine (not shown here) to do the following: */

/* - Allocate a buffer for data and indicator values */

/* fetched from the result table. */

/* - Update the SQLDATA and SQLIND fields in each */

/* SQLVAR of *res_da with the addresses at which to */

/* to put the fetched data and values of indicator */

/* variables. */

/********************************************************/

alloc_outbuff(res_da);

/********************************************************/

/* Fetch the data from the result table. */

/********************************************************/

while(SQLCODE==0)

EXEC SQL FETCH C1 USING DESCRIPTOR :*res_da;

}

return;

}




PROGRAM-ID. CALPRML.




FILE-CONTROL.

SELECT REPOUT

ASSIGN TO UT-S-SYSPRINT.

DATA DIVISION.

FILE SECTION.

FD REPOUT



DATA RECORD IS REPREC.

01 REPREC PIC X(127).


*****************************************************

* MESSAGES FOR SQL CALL *

*****************************************************

01 SQLREC.

02 BADMSG PIC X(34) VALUE

’ SQL CALL FAILED DUE TO SQLCODE = ’.

02 BADCODE PIC +9(5) USAGE DISPLAY.

02 FILLER PIC X(80) VALUE SPACES.

01 ERRMREC.

02 ERRMMSG PIC X(12) VALUE ’ SQLERRMC = ’.

02 ERRMCODE PIC X(70).


01 CALLREC.

02 CALLMSG PIC X(28) VALUE

’ GETPRML FAILED DUE TO RC = ’.

02 CALLCODE PIC +9(5) USAGE DISPLAY.


01 RSLTREC.

02 RSLTMSG PIC X(15) VALUE

’ TABLE NAME IS ’.

02 TBLNAME PIC X(18) VALUE SPACES.


Figure 302. Calling a stored procedure from a COBOL program (Part 1 of 3)


*****************************************************

* WORK AREAS *

*****************************************************

01 PROCNM PIC X(18).

01 SCHEMA PIC X(8).

01 OUT-CODE PIC S9(9) USAGE COMP.

01 PARMLST.

49 PARMLEN PIC S9(4) USAGE COMP.

49 PARMTXT PIC X(254).

01 PARMBUF REDEFINES PARMLST.

49 PARBLEN PIC S9(4) USAGE COMP.

49 PARMARRY PIC X(127) OCCURS 2 TIMES.

01 NAME.

49 NAMELEN PIC S9(4) USAGE COMP.

49 NAMETXT PIC X(18).

77 PARMIND PIC S9(4) COMP.

77 I PIC S9(4) COMP.

77 NUMLINES PIC S9(4) COMP.

*****************************************************

* DECLARE A RESULT SET LOCATOR FOR THE RESULT SET *

* THAT IS RETURNED. *

*****************************************************

01 LOC USAGE SQL TYPE IS

RESULT-SET-LOCATOR VARYING.

*****************************************************

* SQL INCLUDE FOR SQLCA *

*****************************************************


PROCEDURE DIVISION.

*------------------

PROG-START.

OPEN OUTPUT REPOUT.

* OPEN OUTPUT FILE

MOVE ’DSN8EP2 ’ TO PROCNM.

* INPUT PARAMETER -- PROCEDURE TO BE FOUND

MOVE SPACES TO SCHEMA.

* INPUT PARAMETER -- SCHEMA IN SYSROUTINES

MOVE -1 TO PARMIND.

* THE PARMLST PARAMETER IS AN OUTPUT PARM.

* MARK PARMLST PARAMETER AS NULL, SO THE DB2

* REQUESTER DOESN’T HAVE TO SEND THE ENTIRE

* PARMLST VARIABLE TO THE SERVER. THIS

* HELPS REDUCE NETWORK I/O TIME, BECAUSE

* PARMLST IS FAIRLY LARGE.

EXEC SQL

CALL GETPRML(:PROCNM,

:SCHEMA,

:OUT-CODE,

:PARMLST INDICATOR :PARMIND)

END-EXEC.



Calling a stored procedure from a PL/I program

This example shows how to call a version of the GETPRML stored procedure that

uses the GENERAL linkage convention from a PL/I program on an z/OSsystem.

* MAKE THE CALL

IF SQLCODE NOT EQUAL TO +466 THEN

* IF CALL RETURNED BAD SQLCODE

MOVE SQLCODE TO BADCODE

WRITE REPREC FROM SQLREC

MOVE SQLERRMC TO ERRMCODE

WRITE REPREC FROM ERRMREC

ELSE

PERFORM GET-PARMS

PERFORM GET-RESULT-SET.

PROG-END.

CLOSE REPOUT.

* CLOSE OUTPUT FILE

GOBACK.

PARMPRT.

MOVE SPACES TO REPREC.

WRITE REPREC FROM PARMARRY(I)


GET-PARMS.

* IF THE CALL WORKED,

IF OUT-CODE NOT EQUAL TO 0 THEN

* DID GETPRML HIT AN ERROR?

MOVE OUT-CODE TO CALLCODE

WRITE REPREC FROM CALLREC

ELSE

* EVERYTHING WORKED

DIVIDE 127 INTO PARMLEN GIVING NUMLINES ROUNDED

* FIND OUT HOW MANY LINES TO PRINT

PERFORM PARMPRT VARYING I

FROM 1 BY 1 UNTIL I GREATER THAN NUMLINES.

GET-RESULT-SET.

*****************************************************

* ASSUME YOU KNOW THAT ONE RESULT SET IS RETURNED, *

* AND YOU KNOW THE FORMAT OF THAT RESULT SET. *

* ALLOCATE A CURSOR FOR THE RESULT SET, AND FETCH *

* THE CONTENTS OF THE RESULT SET. *

*****************************************************

EXEC SQL ASSOCIATE LOCATORS (:LOC)

WITH PROCEDURE GETPRML

END-EXEC.

* LINK THE RESULT SET TO THE LOCATOR

EXEC SQL ALLOCATE C1 CURSOR FOR RESULT SET :LOC

END-EXEC.

* LINK THE CURSOR TO THE RESULT SET

PERFORM GET-ROWS VARYING I

FROM 1 BY 1 UNTIL SQLCODE EQUAL TO +100.

GET-ROWS.

EXEC SQL FETCH C1 INTO :NAME

END-EXEC.

MOVE NAME TO TBLNAME.

WRITE REPREC FROM RSLTREC




C stored procedure: GENERAL

This example stored procedure does the following:

v Searches the DB2 catalog table SYSROUTINES for a row that matches the input

parameters from the client program. The two input parameters contain values

for NAME and SCHEMA.

*PROCESS SYSTEM(MVS);

CALPRML:

PROC OPTIONS(MAIN);

/************************************************************/

/* Declare the parameters used to call the GETPRML */

/* stored procedure. */

/************************************************************/

DECLARE PROCNM CHAR(18), /* INPUT parm -- PROCEDURE name */

SCHEMA CHAR(8), /* INPUT parm -- User’s schema */

OUT_CODE FIXED BIN(31),

/* OUTPUT -- SQLCODE from the */

/* SELECT operation. */

PARMLST CHAR(254) /* OUTPUT -- RUNOPTS for */

VARYING, /* the matching row in the */

/* catalog table SYSROUTINES */

PARMIND FIXED BIN(15);

/* PARMLST indicator variable */

/************************************************************/

/* Include the SQLCA */

/************************************************************/


/************************************************************/

/* Call the GETPRML stored procedure to retrieve the */

/* RUNOPTS values for the stored procedure. In this */

/* example, we request the RUNOPTS values for the */

/* stored procedure named DSN8EP2. */

/************************************************************/

PROCNM = ’DSN8EP2’;

/* Input parameter -- PROCEDURE to be found */

SCHEMA = ’ ’;

/* Input parameter -- SCHEMA in SYSROUTINES */

PARMIND = -1; /* The PARMLST parameter is an output parm. */

/* Mark PARMLST parameter as null, so the DB2 */

/* requester doesn’t have to send the entire */

/* PARMLST variable to the server. This */

/* helps reduce network I/O time, because */

/* PARMLST is fairly large. */

EXEC SQL

CALL GETPRML(:PROCNM,

:SCHEMA,

:OUT_CODE,

:PARMLST INDICATOR :PARMIND);

Figure 303. Calling a stored procedure from a PL/I program (Part 1 of 2)

IF SQLCODE¬=0 THEN /* If SQL CALL failed, */

DO;

PUT SKIP EDIT(’SQL CALL failed due to SQLCODE = ’,

SQLCODE) (A(34),A(14));

PUT SKIP EDIT(’SQLERRM = ’,

SQLERRM) (A(10),A(70));

END;

ELSE /* If the CALL worked, */

IF OUT_CODE¬=0 THEN /* Did GETPRML hit an error? */

PUT SKIP EDIT(’GETPRML failed due to RC = ’,

OUT_CODE) (A(33),A(14));

ELSE /* Everything worked. */

PUT SKIP EDIT(’RUNOPTS = ’, PARMLST) (A(11),A(200));

RETURN;

END CALPRML;

Figure 303. Calling a stored procedure from a PL/I program (Part 2 of 2)


v Searches the DB2 catalog table SYSTABLES for all tables in which the value of

CREATOR matches the value of input parameter SCHEMA. The stored

procedure uses a cursor to return the table names.

The linkage convention used for this stored procedure is GENERAL.

The output parameters from this stored procedure contain the SQLCODE from the

SELECT statement and the value of the RUNOPTS column from SYSROUTINES.

The CREATE PROCEDURE statement for this stored procedure might look like

this:

CREATE PROCEDURE GETPRML(PROCNM CHAR(18) IN, SCHEMA CHAR(8) IN,

OUTCODE INTEGER OUT, PARMLST VARCHAR(254) OUT)

LANGUAGE C

DETERMINISTIC

READS SQL DATA

EXTERNAL NAME "GETPRML"

COLLID GETPRML

ASUTIME NO LIMIT

PARAMETER STYLE GENERAL

STAY RESIDENT NO

RUN OPTIONS "MSGFILE(OUTFILE),RPTSTG(ON),RPTOPTS(ON)"

WLM ENVIRONMENT SAMPPROG

PROGRAM TYPE MAIN

SECURITY DB2

RESULT SETS 2

COMMIT ON RETURN NO;


C stored procedure: GENERAL WITH NULLS


#pragma runopts(plist(os))

#include <stdlib.h>


/***************************************************************/

/* Declare C variables for SQL operations on the parameters. */

/* These are local variables to the C program, which you must */

/* copy to and from the parameter list provided to the stored */

/* procedure. */

/***************************************************************/


char PROCNM[19];

char SCHEMA[9];

char PARMLST[255];


/***************************************************************/

/* Declare cursors for returning result sets to the caller. */

/***************************************************************/

EXEC SQL DECLARE C1 CURSOR WITH RETURN FOR

SELECT NAME

FROM SYSIBM.SYSTABLES

WHERE CREATOR=:SCHEMA;

main(argc,argv)

int argc;

char *argv[];

{

/********************************************************/

/* Copy the input parameters into the area reserved in */

/* the program for SQL processing. */

/********************************************************/

strcpy(PROCNM, argv[1]);

strcpy(SCHEMA, argv[2]);

/********************************************************/

/* Issue the SQL SELECT against the SYSROUTINES */

/* DB2 catalog table. */

/********************************************************/

strcpy(PARMLST, ""); /* Clear PARMLST */

EXEC SQL

SELECT RUNOPTS INTO :PARMLST

FROM SYSIBM.ROUTINES

WHERE NAME=:PROCNM AND

SCHEMA=:SCHEMA;

Figure 304. A C stored procedure with linkage convention GENERAL (Part 1 of 2)

/********************************************************/

/* Copy SQLCODE to the output parameter list. */

/********************************************************/

*(int *) argv[3] = SQLCODE;

/********************************************************/

/* Copy the PARMLST value returned by the SELECT back to*/

/* the parameter list provided to this stored procedure.*/

/********************************************************/

strcpy(argv[4], PARMLST);

/********************************************************/

/* Open cursor C1 to cause DB2 to return a result set */

/* to the caller. */

/********************************************************/

EXEC SQL OPEN C1;

}

Figure 304. A C stored procedure with linkage convention GENERAL (Part 2 of 2)


v Searches the DB2 catalog table SYSROUTINES for a row that matches the input






The linkage convention for this stored procedure is GENERAL WITH NULLS.


SELECT operation, and the value of the RUNOPTS column retrieved from the

SYSROUTINES table.


this:



LANGUAGE C

DETERMINISTIC

READS SQL DATA


COLLID GETPRML

ASUTIME NO LIMIT

PARAMETER STYLE GENERAL WITH NULLS

STAY RESIDENT NO



PROGRAM TYPE MAIN

SECURITY DB2

RESULT SETS 2



#pragma runopts(plist(os))

#include <stdlib.h>


/***************************************************************/

/* Declare C variables used for SQL operations on the */

/* parameters. These are local variables to the C program, */

/* which you must copy to and from the parameter list provided */

/* to the stored procedure. */

/***************************************************************/


char PROCNM[19];

char SCHEMA[9];

char PARMLST[255];

struct INDICATORS {

short int PROCNM_IND;

short int SCHEMA_IND;

short int OUT_CODE_IND;

short int PARMLST_IND;

} PARM_IND;


/***************************************************************/

/* Declare cursors for returning result sets to the caller. */

/***************************************************************/


SELECT NAME

FROM SYSIBM.SYSTABLES

WHERE CREATOR=:SCHEMA;

main(argc,argv)

int argc;

char *argv[];

{

/********************************************************/

/* Copy the input parameters into the area reserved in */

/* the local program for SQL processing. */

/********************************************************/

strcpy(PROCNM, argv[1]);

strcpy(SCHEMA, argv[2]);

/********************************************************/

/* Copy null indicator values for the parameter list. */

/********************************************************/

memcpy(&PARM_IND,(struct INDICATORS *) argv[5],

sizeof(PARM_IND));

Figure 305. A C stored procedure with linkage convention GENERAL WITH NULLS (Part 1 of

2)


COBOL stored procedure: GENERAL


v Searches the catalog table SYSROUTINES for a row matching the input






This stored procedure is able to return a NULL value for the output host variables.

The linkage convention for this stored procedure is GENERAL.

/********************************************************/

/* If any input parameter is NULL, return an error */

/* return code and assign a NULL value to PARMLST. */

/********************************************************/

if (PARM_IND.PROCNM_IND<0 ||

PARM_IND.SCHEMA_IND<0 || {

*(int *) argv[3] = 9999; /* set output return code */

PARM_IND.OUT_CODE_IND = 0; /* value is not NULL */

PARM_IND.PARMLST_IND = -1; /* PARMLST is NULL */

}

else {

/********************************************************/

/* If the input parameters are not NULL, issue the SQL */

/* SELECT against the SYSIBM.SYSROUTINES catalog */

/* table. */

/********************************************************/

strcpy(PARMLST, ""); /* Clear PARMLST */

EXEC SQL


FROM SYSIBM.SYSROUTINES


SCHEMA=:SCHEMA;

/********************************************************/

/* Copy SQLCODE to the output parameter list. */

/********************************************************/

*(int *) argv[3] = SQLCODE;

PARM_IND.OUT_CODE_IND = 0; /* OUT_CODE is not NULL */

}

/********************************************************/

/* Copy the RUNOPTS value back to the output parameter */

/* area. */

/********************************************************/

strcpy(argv[4], PARMLST);

/********************************************************/

/* Copy the null indicators back to the output parameter*/

/* area. */

/********************************************************/

memcpy((struct INDICATORS *) argv[5],&PARM_IND,

sizeof(PARM_IND));

/********************************************************/

/* Open cursor C1 to cause DB2 to return a result set */

/* to the caller. */

/********************************************************/

EXEC SQL OPEN C1;

}

Figure 305. A C stored procedure with linkage convention GENERAL WITH NULLS (Part 2 of

2)




SYSROUTINES table.


this:



LANGUAGE COBOL

DETERMINISTIC

READS SQL DATA


COLLID GETPRML

ASUTIME NO LIMIT


STAY RESIDENT NO



PROGRAM TYPE MAIN

SECURITY DB2

RESULT SETS 2



CBL RENT


PROGRAM-ID. GETPRML.

AUTHOR. EXAMPLE.

DATE-WRITTEN. 03/25/98.



FILE-CONTROL.

DATA DIVISION.

FILE SECTION.



***************************************************

* DECLARE A HOST VARIABLE TO HOLD INPUT SCHEMA

***************************************************

01 INSCHEMA PIC X(8).

***************************************************

* DECLARE CURSOR FOR RETURNING RESULT SETS

***************************************************

*


SELECT NAME FROM SYSIBM.SYSTABLES WHERE CREATOR=:INSCHEMA

END-EXEC.

*

LINKAGE SECTION.

***************************************************

* DECLARE THE INPUT PARAMETERS FOR THE PROCEDURE

***************************************************


01 SCHEMA PIC X(8).

*******************************************************

* DECLARE THE OUTPUT PARAMETERS FOR THE PROCEDURE

*******************************************************

01 OUT-CODE PIC S9(9) USAGE BINARY.

01 PARMLST.

49 PARMLST-LEN PIC S9(4) USAGE BINARY.

49 PARMLST-TEXT PIC X(254).

PROCEDURE DIVISION USING PROCNM, SCHEMA,

OUT-CODE, PARMLST.

Figure 306. A COBOL stored procedure with linkage convention GENERAL (Part 1 of 2)

*******************************************************

* Issue the SQL SELECT against the SYSIBM.SYSROUTINES

* DB2 catalog table.

*******************************************************

EXEC SQL


FROM SYSIBM.ROUTINES


SCHEMA=:SCHEMA

END-EXEC.

*******************************************************

* COPY SQLCODE INTO THE OUTPUT PARAMETER AREA

*******************************************************

MOVE SQLCODE TO OUT-CODE.

*******************************************************

* OPEN CURSOR C1 TO CAUSE DB2 TO RETURN A RESULT SET

* TO THE CALLER.

*******************************************************

EXEC SQL OPEN C1

END-EXEC.

PROG-END.

GOBACK.

Figure 306. A COBOL stored procedure with linkage convention GENERAL (Part 2 of 2)


COBOL stored procedure: GENERAL WITH NULLS


v Searches the DB2 SYSIBM.SYSROUTINES catalog table for a row that matches

the input parameters from the client program. The two input parameters contain

values for NAME and SCHEMA.







SYSIBM.SYSROUTINES table.


this:



LANGUAGE COBOL

DETERMINISTIC

READS SQL DATA


COLLID GETPRML

ASUTIME NO LIMIT


STAY RESIDENT NO



PROGRAM TYPE MAIN

SECURITY DB2

RESULT SETS 2



CBL RENT


PROGRAM-ID. GETPRML.

AUTHOR. EXAMPLE.

DATE-WRITTEN. 03/25/98.



FILE-CONTROL.

DATA DIVISION.

FILE SECTION.

*


*


*

***************************************************

* DECLARE A HOST VARIABLE TO HOLD INPUT SCHEMA

***************************************************

01 INSCHEMA PIC X(8).

***************************************************

* DECLARE CURSOR FOR RETURNING RESULT SETS

***************************************************

*


SELECT NAME FROM SYSIBM.SYSTABLES WHERE CREATOR=:INSCHEMA

END-EXEC.

*

LINKAGE SECTION.

***************************************************

* DECLARE THE INPUT PARAMETERS FOR THE PROCEDURE

***************************************************


01 SCHEMA PIC X(8).

***************************************************

* DECLARE THE OUTPUT PARAMETERS FOR THE PROCEDURE

***************************************************

01 OUT-CODE PIC S9(9) USAGE BINARY.

01 PARMLST.

49 PARMLST-LEN PIC S9(4) USAGE BINARY.

49 PARMLST-TEXT PIC X(254).

***************************************************

* DECLARE THE STRUCTURE CONTAINING THE NULL

* INDICATORS FOR THE INPUT AND OUTPUT PARAMETERS.

***************************************************

01 IND-PARM.

03 PROCNM-IND PIC S9(4) USAGE BINARY.

03 SCHEMA-IND PIC S9(4) USAGE BINARY.

03 OUT-CODE-IND PIC S9(4) USAGE BINARY.

03 PARMLST-IND PIC S9(4) USAGE BINARY.

Figure 307. A COBOL stored procedure with linkage convention GENERAL WITH NULLS

(Part 1 of 2)


PL/I stored procedure: GENERAL

This example stored procedure searches the DB2 SYSIBM.SYSROUTINES catalog

table for a row that matches the input parameters from the client program. The

two input parameters contain values for NAME and SCHEMA.

The linkage convention for this stored procedure is GENERAL.





this:



LANGUAGE PLI

DETERMINISTIC

READS SQL DATA


COLLID GETPRML

ASUTIME NO LIMIT


STAY RESIDENT NO


PROCEDURE DIVISION USING PROCNM, SCHEMA,

OUT-CODE, PARMLST, IND-PARM.

*******************************************************

* If any input parameter is null, return a null value

* for PARMLST and set the output return code to 9999.

*******************************************************

IF PROCNM-IND < 0 OR

SCHEMA-IND < 0

MOVE 9999 TO OUT-CODE

MOVE 0 TO OUT-CODE-IND

MOVE -1 TO PARMLST-IND

ELSE

*******************************************************

* Issue the SQL SELECT against the SYSIBM.SYSROUTINES

* DB2 catalog table.

*******************************************************

EXEC SQL




SCHEMA=:SCHEMA

END-EXEC

MOVE 0 TO PARMLST-IND

*******************************************************

* COPY SQLCODE INTO THE OUTPUT PARAMETER AREA

*******************************************************

MOVE SQLCODE TO OUT-CODE

MOVE 0 TO OUT-CODE-IND.

*

*******************************************************

* OPEN CURSOR C1 TO CAUSE DB2 TO RETURN A RESULT SET

* TO THE CALLER.

*******************************************************

EXEC SQL OPEN C1

END-EXEC.

PROG-END.

GOBACK.

Figure 307. A COBOL stored procedure with linkage convention GENERAL WITH NULLS

(Part 2 of 2)



PROGRAM TYPE MAIN

SECURITY DB2

RESULT SETS 0


PL/I stored procedure: GENERAL WITH NULLS

This example stored procedure searches the DB2 SYSIBM.SYSROUTINES catalog

table for a row that matches the input parameters from the client program. The

two input parameters contain values for NAME and SCHEMA.






this:



LANGUAGE PLI

DETERMINISTIC

READS SQL DATA


COLLID GETPRML

ASUTIME NO LIMIT


STAY RESIDENT NO




GETPRML:

PROC(PROCNM, SCHEMA, OUT_CODE, PARMLST)

OPTIONS(MAIN NOEXECOPS REENTRANT);


SCHEMA CHAR(8), /* INPUT parm -- User’s SCHEMA */

OUT_CODE FIXED BIN(31), /* OUTPUT -- SQLCODE from */

/* the SELECT operation. */

PARMLST CHAR(254) /* OUTPUT -- RUNOPTS for */

VARYING; /* the matching row in */

/* SYSIBM.SYSROUTINES */


/************************************************************/

/* Execute SELECT from SYSIBM.SYSROUTINES in the catalog. */

/************************************************************/

EXEC SQL




SCHEMA=:SCHEMA;

OUT_CODE = SQLCODE; /* return SQLCODE to caller */

RETURN;

END GETPRML;

Figure 308. A PL/I stored procedure with linkage convention GENERAL


PROGRAM TYPE MAIN

SECURITY DB2

RESULT SETS 0



GETPRML:

PROC(PROCNM, SCHEMA, OUT_CODE, PARMLST, INDICATORS)

OPTIONS(MAIN NOEXECOPS REENTRANT);


SCHEMA CHAR(8), /* INPUT parm -- User’s schema */

OUT_CODE FIXED BIN(31), /* OUTPUT -- SQLCODE from */

/* the SELECT operation. */

PARMLST CHAR(254) /* OUTPUT -- PARMLIST for */

VARYING; /* the matching row in */

/* SYSIBM.SYSROUTINES */

DECLARE 1 INDICATORS, /* Declare null indicators for */

/* input and output parameters. */

3 PROCNM_IND FIXED BIN(15),

3 SCHEMA_IND FIXED BIN(15),

3 OUT_CODE_IND FIXED BIN(15),

3 PARMLST_IND FIXED BIN(15);


IF PROCNM_IND<0 |

SCHEMA_IND<0 THEN

DO; /* If any input parm is NULL, */

OUT_CODE = 9999; /* Set output return code. */

OUT_CODE_IND = 0;

/* Output return code is not NULL.*/

PARMLST_IND = -1; /* Assign NULL value to PARMLST. */

END;

ELSE /* If input parms are not NULL, */

DO; /* */

/************************************************************/

/* Issue the SQL SELECT against the SYSIBM.SYSROUTINES */

/* DB2 catalog table. */

/************************************************************/

EXEC SQL




SCHEMA=:SCHEMA;

PARMLST_IND = 0; /* Mark PARMLST as not NULL. */

OUT_CODE = SQLCODE; /* return SQLCODE to caller */

OUT_CODE_IND = 0;

OUT_CODE_IND = 0; /* Output return code is not NULL.*/

END;

RETURN;

END GETPRML;

Figure 309. A PL/I stored procedure with linkage convention GENERAL WITH NULLS



Appendix E. Recursive common table expression examples

Bill of materials (BOM) applications are a common requirement in many business

environments. Recursive SQL is very useful in creating BOM applications. To

illustrate the some of the capability of a recursive common table expression for

BOM applications, consider a table of parts with associated subparts and the

quantity of subparts required by each part. For more information about recursive

SQL, refer to “Recursive SQL” on page 25.

For the examples in this topic, create the following table:

CREATE TABLE PARTLIST

(PART VARCHAR(8),

SUBPART VARCHAR(8),

QUANTITY INTEGER);

Assume that the PARTLIST table is populated with the values that are in Table 245:

Table 245. PARTLIST table

PART SUBPART QUANTITY

00 01 5

00 05 3

01 02 2

01 03 3

01 04 4

01 06 3

02 05 7

02 06 6

03 07 6

04 08 10

04 09 11

05 10 10

05 11 10

06 12 10

06 13 10

07 14 8

07 12 8

Example 1: Single level explosion: Single level explosion answers the question,

″What parts are needed to build the part identified by ’01’?″. The list will include

the direct subparts, subparts of the subparts and so on. However, if a part is used

multiple times, its subparts are only listed once.

WITH RPL (PART, SUBPART, QUANTITY) AS

(SELECT ROOT.PART, ROOT.SUBPART, ROOT.QUANTITY

FROM PARTLIST ROOT

WHERE ROOT.PART = ’01’

UNION ALL


SELECT CHILD.PART, CHILD.SUBPART, CHILD.QUANTITY

FROM RPL PARENT, PARTLIST CHILD

WHERE PARENT.SUBPART = CHILD.PART)

SELECT DISTINCT PART, SUBPART, QUANTITY

FROM RPL

ORDER BY PART, SUBPART, QUANTITY;

The preceding query includes a common table expression, identified by the name

RPL, that expresses the recursive part of this query. It illustrates the basic elements

of a recursive common table expression.

The first operand (fullselect) of the UNION, referred to as the initialization

fullselect, gets the direct subparts of part ’01’. The FROM clause of this fullselect

refers to the source table and will never refer to itself (RPL in this case). The result

of this first fullselect goes into the common table expression RPL. As in this

example, the UNION must always be a UNION ALL.

The second operand (fullselect) of the UNION uses RPL to compute subparts of

subparts by using the FROM clause to refer to the common table expression RPL

and the source table PARTLIST with a join of a part from the source table (child) to

a subpart of the current result contained in RPL (parent). The result goes then back

to RPL again. The second operand of UNION is used repeatedly until no more

subparts exist.

The SELECT DISTINCT in the main fullselect of this query ensures the same

part/subpart is not listed more than once.

The result of the query is shown in Table 246:

Table 246. Result table for example 1

PART SUBPART QUANTITY

01 02 2

01 03 3

01 04 4

01 06 3

02 05 7

02 06 6

03 07 6

04 08 10

04 09 11

05 10 10

05 11 10

06 12 10

06 13 10

07 12 8

17 14 8

Observe in the result that part ’01’ contains subpart ’02’ which contains subpart

’06’ and so on. Further, notice that part ’06’ is reached twice, once through part ’01’

directly and another time through part ’02’. In the output, however, the subparts of

part ’06’ are listed only once (this is the result of using a SELECT DISTINCT).


Remember that with recursive common table expressions it is possible to introduce

an infinite loop. In this example, an infinite loop would be created if the search

condition of the second operand that joins the parent and child tables was coded

as follows:

WHERE PARENT.SUBPART = CHILD.SUBPART

This infinite loop is created by not coding what is intended. You should carefully

determining what to code so that there is a definite end of the recursion cycle.

The result produced by this example could be produced in an application program

without using a recursive common table expression. However, such an application

would require coding a different query for every level of recursion. Furthermore,

the application would need to put all of the results back in the database to order

the final result. This approach complicates the application logic and does not

perform well. The application logic becomes more difficult and inefficient for other

bill of material queries, such as summarized and indented explosion queries.

Example 2: Summarized explosion: A summarized explosion answers the

question, ″What is the total quantity of each part required to build part ’01’?″ The

main difference from a single level explosion is the need to aggregate the

quantities. A single level explosion indicates the quantity of subparts required for

the part whenever it is required. It does not indicate how many of each subpart is

needed to build part ’01’.

WITH RPL (PART, SUBPART, QUANTITY) AS

(

SELECT ROOT.PART, ROOT.SUBPART, ROOT.QUANTITY

FROM PARTLIST ROOT


UNION ALL

SELECT PARENT.PART, CHILD.SUBPART,

PARENT.QUANTITY*CHILD.QUANTITY


WHERE PARENT.SUBPART = CHILD.PART

)

SELECT PART, SUBPART, SUM(QUANTITY) AS "Total QTY Used"

FROM RPL

GROUP BY PART, SUBPART

ORDER BY PART, SUBPART;

In the preceding query, the select list of the second operand of the UNION in the

recursive common table expression, identified by the name RPL, shows the

aggregation of the quantity. To determine how many of each subpart is used, the

quantity of the parent is multiplied by the quantity per parent of a child. If a part

is used multiple times in different places, it requires another final aggregation. This

is done by the grouping the parts and subparts in the common table expression

RPL and using the SUM column function in the select list of the main fullselect.



PART SUBPART Total QTY Used

01 02 2

01 03 3

01 04 4

01 05 14

01 06 15

Appendix E. Recursive common table expression examples 1193

Table 247. Result table for example 2 (continued)

PART SUBPART Total QTY Used

01 07 18

01 08 40

01 09 44

01 10 140

01 11 140

01 12 294

01 13 150

01 14 144

Consider the total quantity for subpart ’06’. The value of 15 is derived from a

quantity of 3 directly for part ’01’ and a quantity of 6 for part ’02’ which is needed

two times by part ’01’.

Example 3: Controlling depth: You can control the depth of a recursive query to

answer the question, ″What are the first two levels of parts that are needed to

build part ’01’?″ For the sake of clarity in this example, the level of each part is

included in the result table.

WITH RPL (LEVEL, PART, SUBPART, QUANTITY) AS

(

SELECT 1, ROOT.PART, ROOT.SUBPART, ROOT.QUANTITY

FROM PARTLIST ROOT


UNION ALL

SELECT PARENT.LEVEL+1, CHILD.PART, CHILD.SUBPART, CHILD.QUANTITY


WHERE PARENT.SUBPART = CHILD.PART

AND PARENT.LEVEL < 2

)

SELECT PART, LEVEL, SUBPART, QUANTITY

FROM RPL;

This query is similar to the query in example 1. The column LEVEL is introduced

to count the level each subpart is from the original part. In the initialization

fullselect, the value for the LEVEL column is initialized to 1. In the subsequent

fullselect, the level from the parent table increments by 1. To control the number of

levels in the result, the second fullselect includes the condition that the level of the

parent must be less than 2. This ensures that the second fullselect only processes

children to the second level.



PART LEVEL SUBPART QUANTITY

01 1 02 2

01 1 03 3

01 1 04 4

01 1 06 3

02 2 05 7

02 2 06 6


Table 248. Result table for example 3 (continued)

PART LEVEL SUBPART QUANTITY

03 2 07 6

04 2 08 10

04 2 09 11

06 2 12 10

06 2 13 10

Appendix E. Recursive common table expression examples 1195


Appendix F. REBIND subcommands for lists of plans or

packages

If a list of packages or plans that you want to rebind is not easily specified using

asterisks, you might be able to create the needed REBIND subcommands

automatically, using the sample program DSNTIAUL.

One situation in which this technique might be useful is when a resource becomes

unavailable during a rebind of many plans or packages. DB2 normally terminates

the rebind and does not rebind the remaining plans or packages. Later, however,

you might want to rebind only the objects that remain to be rebound. You can

build REBIND subcommands for the remaining plans or packages by using

DSNTIAUL to select the plans or packages from the DB2 catalog and to create the

REBIND subcommands. You can then submit the subcommands through the DSN

command processor, as usual.

You might first need to edit the output from DSNTIAUL so that DSN can accept it

as input. The CLIST DSNTEDIT can perform much of that task for you.

This section contains the following topics:

v Overview of the procedure for generating lists of REBIND commands

v “Sample SELECT statements for generating REBIND commands”

v “Sample JCL for running lists of REBIND commands” on page 1200

Overview of the procedure for generating lists of REBIND commands

The following list is an overview of the procedures for REBIND PLAN:

1. Use DSNTIAUL to generate the REBIND PLAN subcommands for the selected

plans.

2. Use TSO edit commands to add TSO DSN commands to the sequential data

set.

3. Use DSN to execute the REBIND PLAN subcommands for the selected plans.

The following list is an overview of the procedures for REBIND PACKAGE:

1. Use DSNTIAUL to generate the REBIND PACKAGE subcommands for the

selected packages.

2. Use DSNTEDIT CLIST to delete extraneous blanks from the REBIND

PACKAGE subcommands.

3. Use TSO edit commands to add DSN commands to the sequential data set.

4. Use DSN to execute the REBIND PACKAGE subcommands for the selected

packages.

Sample SELECT statements for generating REBIND commands

Building REBIND subcommands: The examples that follow illustrate the following

techniques:

v Using SELECT to select specific packages or plans to be rebound

v Using the CONCAT operator to concatenate the REBIND subcommand syntax

around the plan or package names


v Using the SUBSTR function to convert a varying-length string to a fixed-length

string

v Appending additional blanks to the REBIND PLAN and REBIND PACKAGE

subcommands, so that the DSN command processor can accept the record length

as valid input

If the SELECT statement returns rows, then DSNTIAUL generates REBIND

subcommands for the plans or packages identified in the returned rows. Put those

subcommands in a sequential data set, where you can then edit them.

For REBIND PACKAGE subcommands, delete any extraneous blanks in the

package name, using either TSO edit commands or the DB2 CLIST DSNTEDIT.

For both REBIND PLAN and REBIND PACKAGE subcommands, add the DSN

command that the statement needs as the first line in the sequential data set, and

add END as the last line, using TSO edit commands. When you have edited the

sequential data set, you can run it to rebind the selected plans or packages.

If the SELECT statement returns no qualifying rows, then DSNTIAUL does not

generate REBIND subcommands.

The examples in this topic generate REBIND subcommands that work in DB2 for

z/OS Version 9.1. You might need to modify the examples for prior releases of DB2

that do not allow all of the same syntax.

Example 1:

REBIND all plans without terminating because of unavailable resources.

SELECT SUBSTR(’REBIND PLAN(’CONCAT NAME

CONCAT’) ’,1,45)

FROM SYSIBM.SYSPLAN;

Example 2:

REBIND all versions of all packages without terminating because of

unavailable resources.

SELECT SUBSTR(’REBIND PACKAGE(’CONCAT COLLID CONCAT’.’

CONCAT NAME CONCAT’.(*)) ’,1,55)

FROM SYSIBM.SYSPACKAGE;

Example 3:

REBIND all plans bound before a given date and time.


CONCAT’) ’,1,45)

FROM SYSIBM.SYSPLAN

WHERE BINDDATE <= ’yyyymmdd’ AND

BINDTIME <= ’hhmmssth’;

where yyyymmdd represents the date portion and hhmmssth represents the

time portion of the timestamp string.

Example 4:

REBIND all versions of all packages bound before a given date and time.



FROM SYSIBM.SYSPACKAGE

WHERE BINDTIME <= ’timestamp’;

where timestamp is an ISO timestamp string.


Example 5:

REBIND all plans bound since a given date and time.


CONCAT’) ’,1,45)

FROM SYSIBM.SYSPLAN

WHERE BINDDATE >= ’yyyymmdd’ AND

BINDTIME >= ’hhmmssth’;



Example 6:

REBIND all versions of all packages bound since a given date and time.

SELECT SUBSTR(’REBIND PACKAGE(’CONCAT COLLID

CONCAT’.’CONCAT NAME

CONCAT’.(*)) ’,1,55)


WHERE BINDTIME >= ’timestamp’;

where timestamp is an ISO timestamp string.

Example 7:

REBIND all plans bound within a given date and time range.


CONCAT’) ’,1,45)

FROM SYSIBM.SYSPLAN

WHERE

(BINDDATE >= ’yyyymmdd’ AND

BINDTIME >= ’hhmmssth’) AND

BINDDATE <= ’yyyymmdd’ AND

BINDTIME <= ’hhmmssth’);



Example 8:

REBIND all versions of all packages bound within a given date and time

range.




WHERE BINDTIME >= ’timestamp1’ AND

BINDTIME <= ’timestamp2’;

where timestamp1 and timestamp2 are ISO timestamp strings.

Example 9:

REBIND all invalid plans.


CONCAT’) ’,1,45)

FROM SYSIBM.SYSPLAN

WHERE VALID = ’N’;

Example 10:

REBIND all invalid versions of all packages.




WHERE VALID = ’N’;

Example 11:

REBIND all plans bound with ISOLATION level of cursor stability.

Appendix F. REBIND subcommands for lists of plans or packages 1199


CONCAT’) ’,1,45)

FROM SYSIBM.SYSPLAN

WHERE ISOLATION = ’S’;

Example 12:

REBIND all versions of all packages that allow CPU and/or I/O

parallelism.




WHERE DEGREE=’ANY’;

Sample JCL for running lists of REBIND commands

Figure 310 shows the JCL that is used to rebind all versions of all packages that are

bound within the specified date and time period.

You specify the date and time period for which you want packages to be rebound

in a WHERE clause of the SELECT statement that contains the REBIND command.

In Figure 310, the WHERE clause looks like the following clause:

WHERE BINDTIME >= ’YYYY-MM-DD-hh.mm.ss’ AND

BINDTIME <= ’YYYY-MM-DD-hh.mm.ss’

The date and time period has the following format:

YYYY The four-digit year. For example: 2003.

MM The two-digit month, which can be a value between 01 and 12.

DD The two-digit day, which can be a value between 01 and 31.

hh The two-digit hour, which can be a value between 01 and 24.

mm The two-digit minute, which can be a value between 00 and 59.

ss The two-digit second, which can be a value between 00 and 59.

//REBINDS JOB MSGLEVEL=(1,1),CLASS=A,MSGCLASS=A,USER=SYSADM,

// REGION=1024K

//*********************************************************************/

//SETUP EXEC PGM=IKJEFT01


//SYSTSIN DD *

DSN SYSTEM(DSN)

RUN PROGRAM(DSNTIAUL) PLAN(DSNTIB91) PARMS(’SQL’) -


END



//SYSPUNCH DD SYSOUT=*

//SYSREC00 DD DSN=SYSADM.SYSTSIN.DATA,

// UNIT=SYSDA,DISP=SHR

Figure 310. Example JCL: Rebind all packages that were bound within a specified date and

time period (Part 1 of 2)


Figure 311 on page 1202 shows some sample JCL for rebinding all plans bound

without specifying the DEGREE keyword on BIND with DEGREE(ANY).

//*********************************************************************/

//*

//* GENER= ’<SUBCOMMANDS TO REBIND ALL PACKAGES BOUND IN 1994

//*

//*********************************************************************/

//SYSIN DD *




WHERE BINDTIME >= ’YYYY-MM-DD-hh.mm.ss’ AND

BINDTIME <= ’YYYY-MM-DD-hh.mm.ss’;

/*

//*********************************************************************/

//*

//* STRIP THE BLANKS OUT OF THE REBIND SUBCOMMANDS

//*

//*********************************************************************/

//STRIP EXEC PGM=IKJEFT01

//SYSPROC DD DSN=SYSADM.DSNCLIST,DISP=SHR



//SYSOUT DD SYSOUT=*

//SYSTSIN DD *

DSNTEDIT SYSADM.SYSTSIN.DATA

//SYSIN DD DUMMY

/*

//*********************************************************************/

//*

//* PUT IN THE DSN COMMAND STATEMENTS

//*

//*********************************************************************/

//EDIT EXEC PGM=IKJEFT01


//SYSTSIN DD *

EDIT ’SYSADM.SYSTSIN.DATA’ DATA NONUM

TOP

INSERT DSN SYSTEM(DSN)

BOTTOM

INSERT END

TOP

LIST * 99999

END SAVE

/*

//*********************************************************************/

//*

//* EXECUTE THE REBIND PACKAGE SUBCOMMANDS THROUGH DSN

//*

//*********************************************************************/

//LOCAL EXEC PGM=IKJEFT01

//DBRMLIB DD DSN=DSN910.DBRMLIB.DATA,

// DISP=SHR




//SYSTSIN DD DSN=SYSADM.SYSTSIN.DATA,


/*

Figure 310. Example JCL: Rebind all packages that were bound within a specified date and

time period (Part 2 of 2)

Appendix F. REBIND subcommands for lists of plans or packages 1201

//REBINDS JOB MSGLEVEL=(1,1),CLASS=A,MSGCLASS=A,USER=SYSADM,

// REGION=1024K

//*********************************************************************/

//SETUP EXEC TSOBATCH


//SYSPUNCH DD SYSOUT=*

//SYSREC00 DD DSN=SYSADM.SYSTSIN.DATA,


//*********************************************************************/

//*

//* REBIND ALL PLANS THAT WERE BOUND WITHOUT SPECIFYING THE DEGREE

//* KEYWORD ON BIND WITH DEGREE(ANY)

//*

//*********************************************************************/

//SYSTSIN DD *

DSN S(DSN)

RUN PROGRAM(DSNTIAUL) PLAN(DSNTIB91) PARM(’SQL’)

END

//SYSIN DD *


CONCAT’) DEGREE(ANY) ’,1,45)

FROM SYSIBM.SYSPLAN

WHERE DEGREE = ’ ’;

/*

//*********************************************************************/

//*

//* PUT IN THE DSN COMMAND STATEMENTS

//*

//*********************************************************************/

//EDIT EXEC PGM=IKJEFT01


//SYSTSIN DD *

EDIT ’SYSADM.SYSTSIN.DATA’ DATA NONUM

TOP

INSERT DSN S(DSN)

BOTTOM

INSERT END

TOP

LIST * 99999

END SAVE

/*

//*********************************************************************/

//*

//* EXECUTE THE REBIND SUBCOMMANDS THROUGH DSN

//*

//*********************************************************************/

//REBIND EXEC PGM=IKJEFT01

//STEPLIB DD DSN=SYSADM.TESTLIB,DISP=SHR

// DD DSN=DSN910.SDSNLOAD,DISP=SHR

//DBRMLIB DD DSN=SYSADM.DBRMLIB.DATA,DISP=SHR




//SYSOUT DD SYSOUT=*

//SYSTSIN DD DSN=SYSADM.SYSTSIN.DATA,DISP=SHR

//SYSIN DD DUMMY

/*

Figure 311. Example JCL: Rebind selected plans with a different bind option


Appendix G. Reserved schema names and reserved words

There are restrictions on the use of certain names that are used by the database

manager. In some cases, names are reserved and cannot be used by application

programs. In other cases, certain names are not recommended for use by

application programs though not prevented by the database manager.

Reserved schema names

In general, for distinct types, user-defined functions, stored procedures, sequences,

and triggers, schema names that begin with the prefix SYS are reserved. The

schema name for these objects cannot begin with SYS with these exceptions:

v SYSADM. The schema name can be SYSADM for all these objects.

v SYSIBM. The schema name can be SYSIBM for procedures.

v SYSPROC. The schema name can be SYSPROC for procedures.

v SYSTOOLS. The schema name can be SYSTOOLS for distinct types, user-defined

functions, procedures, and triggers if the user who executes the CREATE

statement has the SYSADM or SYSCTRL privilege.

v SYSFUN can be used for external user-defined scalar functions or external

user-defined table functions if the user who executes the CREATE statement has

the SYSADM or SYSCTRL privilege.

It is also recommended not to use SESSION name as a schema name.

Reserved words

The following lists of terms are words that cannot be used as ordinary identifiers

in some contexts because they might be interpreted as SQL keywords. For

example, ALL cannot be a column name in a SELECT statement. Each word,

however, can be used as a delimited identifier in contexts where it otherwise

cannot be used as an ordinary identifier. For example, if the quotation mark (") is

the escape character that begins and ends delimited identifiers, “ALL” can appear

as a column name in a SELECT statement. In addition, some sections of this book

might indicate words that cannot be used in the specific context that is being

described.

IBM SQL has additional reserved words that DB2 for z/OS does not enforce.

Therefore, you should not use these additional reserved words as ordinary

identifiers in names that have a continuing use. See IBM DB2 SQL Reference for

Cross-Platform Development for a list of the words.

A

ADD

AFTER

ALL

ALLOCATE

ALLOW

ALTER

AND

ANY

AS

ASENSITIVE

ASSOCIATE

ASUTIME

AT1

AUDIT

AUX

AUXILIARY

Note: 1. New reserved word for Version 9.1.


|||

|

B

BEFORE

BEGIN

BETWEEN

BUFFERPOOL

BY

C

CALL

CAPTURE

CASCADED

CASE

CAST

CCSID

CHAR

CHARACTER

CHECK

CLONE1

CLOSE

CLUSTER

COLLECTION

COLLID

COLUMN

COMMENT

COMMIT

CONCAT

CONDITION

CONNECT

CONNECTION

CONSTRAINT

CONTAINS

CONTENT

CONTINUE

CREATE

CURRENT

CURRENT_DATE

CURRENT_LC_CTYPE

CURRENT_PATH

CURRENT_SCHEMA1

CURRENT_TIME

CURRENT_TIMESTAMP

CURSOR


D

DATA

DATABASE

DAY

DAYS

DBINFO

DECLARE

DEFAULT

DELETE

DESCRIPTOR

DETERMINISTIC

DISABLE

DISALLOW

DISTINCT

DO

DOCUMENT1

DOUBLE

DROP

DSSIZE

DYNAMIC


E

EDITPROC

ELSE

ELSEIF

ENCODING

ENCRYPTIONEND

ENDINGEND-EXEC1

ERASE

ESCAPE

EXCEPT

EXCEPTION

EXECUTE

EXISTS

EXIT

EXPLAIN

EXTERNAL

Notes:

1. COBOL only

F

FENCED

FETCH

FIELDPROC

FINAL

FOR

FREE

FROM

FULL

FUNCTION


||

|

G

GENERATED

GET

GLOBAL

GO

GOTO

GRANT

GROUP

H

HANDLER

HAVING

HOLD

HOUR

HOURS

I

IF

IMMEDIATE

IN

INCLUSIVE

INDEX

INF1

INFINITY1

INHERIT

INNER

INOUT

INSENSITIVE

INSERT

INTERSECT1

INTO

IS

ISOBID

ITERATE


J

JAR

JOIN

K

KEEP1

KEY


L

LABEL

LANGUAGE

LC_CTYPE

LEAVE

LEFT

LIKE

LOCAL

LOCALE

LOCATOR

LOCATORS

LOCK

LOCKMAX

LOCKSIZE

LONG

LOOP

M

MAINTAINED

MATERIALIZED

MICROSECOND

MICROSECONDS

MINUTE

MINUTES

MODIFIES

MONTH

MONTHS

Appendix G. Reserved schema names and reserved words 1205

|||

|

N

NAN1

NEXTVAL

NO

NONE

NOT

NULL

NULLS

NUMPARTS


O

OBID

OF

ON

OPEN

OPTIMIZATION

OPTIMIZE

OR

ORDER

OUT

OUTER

P

PACKAGE

PARAMETER

PART

PADDED

PARTITION

PARTITIONED

PARTITIONING

PATH

PIECESIZE

PLAN

PRECISION

PREPARE

PREVVAL

PRIQTY

PRIVILEGES

PROCEDURE

PROGRAM

PSID

PUBLIC1


Q

QUERY

QUERYNO

R

READS

REFERENCES

REFRESH

RESIGNAL

RELEASE

RENAME

REPEAT

RESTRICT

RESULT

RESULT_SET_LOCATOR

RETURN

RETURNS

REVOKE

RIGHT

ROLE1

ROLLBACK

ROUND_CEILING1

ROUND_DOWN1

ROUND_FLOOR1

ROUND_HALF_DOWN1

ROUND_HALF_EVEN1

ROUND_HALF_UP1

ROUND_UP1

ROW1

ROWSET

RUN



|

|

|

|

|||||||

S

SAVEPOINT

SCHEMA

SCRATCHPAD

SECOND

SECONDS

SECQTY

SECURITY

SEQUENCE

SELECT

SENSITIVE

SESSION_USER1

SET

SIGNAL

SIMPLE

SNAN1

SOME

SOURCE

SPECIFIC

STANDARD

STATIC

STATMENT1

STAY

STOGROUP

STORES

STYLE

SUMMARY

SYNONYM

SYSFUN

SYSIBM

SYSPROC

SYSTEM


T

TABLE

TABLESPACE

THEN

TO

TRIGGER

TRUNCATE1

TYPE1


U

UNDO

UNION

UNIQUE

UNTIL

UPDATE

USER

USING

V

VALIDPROC

VALUE

VALUES

VARIABLE

VARIANT

VCAT

VIEW

VOLATILE

VOLUMES

W

WHEN

WHENEVER

WHERE

WHILE

WITH

WLM

X

XMLELEMENT

XMLEXISTS1

XMLNAMESPACES1


Appendix G. Reserved schema names and reserved words 1207

|

|

|

||

||

Y

YEAR

YEARS


Appendix H. Characteristics of SQL statements in DB2 for

z/OS

Actions allowed on SQL statements

Table 249 shows whether a specific DB2 statement can be executed, prepared

interactively or dynamically, or processed by the requester, the server, or the

precompiler. The letter Y means yes.

Table 249. Actions allowed on SQL statements in DB2 for z/OS

SQL statement Executable

Interactively

or

dynamically

prepared

Processed by

Requesting

system Server Precompiler

ALLOCATE CURSOR1 Y Y Y

ALTER2 Y Y Y

ASSOCIATE LOCATORS1 Y Y Y

BEGIN DECLARE SECTION Y

CALL1 Y Y

CLOSE Y Y

COMMENT Y Y Y

COMMIT8 Y Y Y

CONNECT Y Y

CREATE2 Y Y Y

DECLARE CURSOR Y

DECLARE GLOBAL

TEMPORARY TABLE

Y Y Y

DECLARE STATEMENT Y

DECLARE TABLE Y

DECLARE VARIABLE Y

DELETE Y Y Y

DESCRIBE prepared statement or

table

Y Y

DESCRIBE CURSOR Y Y

DESCRIBE INPUT Y Y

DESCRIBE PROCEDURE Y Y

DROP2 Y Y Y

END DECLARE SECTION Y

EXECUTE Y Y

EXECUTE IMMEDIATE Y Y

EXPLAIN Y Y Y

FETCH Y Y

FREE LOCATOR1 Y Y Y


Table 249. Actions allowed on SQL statements in DB2 for z/OS (continued)


Interactively

or

dynamically

prepared

Processed by

Requesting


GET DIAGNOSTICS Y Y

GRANT2 Y Y Y

HOLD LOCATOR1 Y Y Y

INCLUDE Y

INSERT Y Y Y

LABEL Y Y Y

LOCK TABLE Y Y Y

MERGE Y Y Y

OPEN Y Y

PREPARE Y Y4

REFRESH TABLE Y Y Y

RELEASE connection Y Y

RELEASE SAVEPOINT Y Y Y

RENAME2 Y Y Y

REVOKE2 Y Y Y

ROLLBACK8 Y Y Y

SAVEPOINT Y Y Y

SELECT INTO Y Y

SET CONNECTION Y Y

SET CURRENT APPLICATION

ENCODING SCHEME

Y Y

SET CURRENT DEBUG MODE Y Y Y

SET CURRENT DECFLOAT

ROUNDING MODE

Y Y Y

SET CURRENT DEGREE Y Y Y

SET CURRENT LC_CTYPE Y Y Y

SET CURRENT MAINTAINED

TABLE TYPES FOR

OPTIMIZATION

Y Y Y

SET CURRENT OPTIMIZATION

HINT

Y Y Y

SET CURRENT PACKAGE PATH Y Y

SET CURRENT PACKAGESET Y Y

SET CURRENT PRECISION Y Y Y

SET CURRENT REFRESH AGE Y Y Y

SET CURRENT ROUTINE

VERSION

Y Y Y

SET CURRENT RULES Y Y Y

SET CURRENT SQLID5 Y Y Y


||||||

||||||

|||||||

|||||||



Interactively

or

dynamically

prepared

Processed by

Requesting


SET host-variable = CURRENT

APPLICATION ENCODING

SCHEME

Y Y Y


DATE

Y Y


DEGREE

Y Y


MEMBER

Y Y


PACKAGESET

Y Y


PATH

Y Y


QUERY OPTIMIZATION LEVEL

Y Y


SERVER

Y Y


SQLID

Y Y


TIME

Y Y


TIMESTAMP

Y Y


TIMEZONE

Y Y

SET PATH Y Y Y

SET SCHEMA Y Y Y

SET transition-variable =

CURRENT DATE

Y Y


CURRENT DEGREE

Y Y


CURRENT PATH

Y Y


CURRENT QUERY

OPTIMIZATION LEVEL

Y Y


CURRENT SQLID

Y Y


CURRENT TIME

Y Y


CURRENT TIMESTAMP

Y Y


CURRENT TIMEZONE

Y Y

SIGNAL6 Y Y

Appendix H. Characteristics of SQL statements in DB2 for z/OS 1211



Interactively

or

dynamically

prepared

Processed by

Requesting


TRUNCATE Y Y Y

UPDATE Y Y Y

VALUES6 Y Y

VALUES INTO7 Y Y

WHENEVER Y

Notes:

1. The statement can be dynamically prepared. It cannot be issued dynamically.

2. The statement can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly

specified.

3. The statement can be dynamically prepared, but only from an ODBC or CLI driver that supports dynamic CALL

statements.

4. The requesting system processes the PREPARE statement when the statement being prepared is ALLOCATE

CURSOR or ASSOCIATE LOCATORS.

5. The value to which special register CURRENT SQLID is set is used as the SQL authorization ID for dynamic SQL

statements only when DYNAMICRULES run behavior is in effect. The CURRENT SQLID value is ignored for the

other DYNAMICRULES behaviors.

6. This statement can be used only in the triggered action of a trigger.

7. Local special registers can be referenced in a VALUES INTO statement if it results in the assignment of a single

host-variable, not if it results in setting more than one value.

8. Some processing also occurs at the requester.

SQL statements allowed in external functions and stored procedures

Table 250 shows which SQL statements in an external stored procedure or in an

external user-defined function can execute. Whether the statements can be executed

depends on the level of SQL data access with which the stored procedure or

external function is defined (NO SQL, CONTAINS SQL, READS SQL DATA, or

MODIFIES SQL DATA). The letter Y means yes.

In general, if an executable SQL statement is encountered in a stored procedure or

function defined as NO SQL, SQLSTATE 38001 is returned. If the routine is defined

to allow some level of SQL access, SQL statements that are not supported in any

context return SQLSTATE 38003. SQL statements not allowed for routines defined

as CONTAINS SQL return SQLSTATE 38004, and SQL statements not allowed for

READS SQL DATA return SQL STATE 38002.

Table 250. SQL statements in external user-defined functions and stored procedures

SQL statement

Level of SQL access

NO SQL

CONTAINS

SQL

READS SQL

DATA

MODIFIES

SQL DATA

ALLOCATE CURSOR Y Y

ALTER Y

ASSOCIATE LOCATORS Y Y

BEGIN DECLARE SECTION Y1 Y Y Y

CALL Y2 Y2 Y2


||||||

Table 250. SQL statements in external user-defined functions and stored

procedures (continued)

SQL statement

Level of SQL access

NO SQL

CONTAINS

SQL

READS SQL

DATA

MODIFIES

SQL DATA

CLOSE Y Y

COMMENT Y

COMMIT3

Y Y Y

CONNECT Y Y Y

CREATE Y

DECLARE CURSOR Y1 Y Y Y

DECLARE GLOBAL

TEMPORARY TABLE

Y

DECLARE STATEMENT Y1 Y Y Y

DECLARE TABLE Y1 Y Y Y

DECLARE VARIABLE Y1 Y Y Y

DELETE Y

DESCRIBE Y Y

DESCRIBE CURSOR Y Y

DESCRIBE INPUT Y Y

DESCRIBE PROCEDURE Y Y

DROP Y

END DECLARE SECTION Y1 Y Y Y

EXECUTE Y4 Y4 Y

EXECUTE IMMEDIATE Y4 Y4 Y

EXPLAIN Y

FETCH Y Y

FREE LOCATOR Y Y Y

GET DIAGNOSTICS Y Y Y

GRANT Y

HOLD LOCATOR Y Y Y

INCLUDE Y1 Y Y Y

INSERT Y

LABEL Y

LOCK TABLE Y Y Y

MERGE Y

OPEN Y Y

PREPARE Y Y Y

REFRESH TABLE Y

RELEASE connection Y Y Y

RELEASE SAVEPOINT6

Y

REVOKE Y

ROLLBACK6, 7, 8

Y Y Y


|||||



SQL statement

Level of SQL access

NO SQL

CONTAINS

SQL

READS SQL

DATA

MODIFIES

SQL DATA

ROLLBACK TO SAVEPOINT6,

7, 8

Y

SAVEPOINT6

Y

SELECT Y9 Y

SELECT INTO Y Y

SET CONNECTION Y Y Y

SET CURRENT DEBUG

MODE

Y Y Y

SET CURRENT ROUTINE

VERSION

Y Y Y

SET host-variable Assignment Y5 Y Y

SET special register Y Y Y

SET transition-variable

Assignment

Y5 Y Y

SIGNAL Y Y Y

TRUNCATE Y

UPDATE Y

VALUES Y Y

VALUES INTO Y5 Y Y

WHENEVER Y1 Y Y Y


||||||

||||||

|||||



SQL statement

Level of SQL access

NO SQL

CONTAINS

SQL

READS SQL

DATA

MODIFIES

SQL DATA

Notes:

1. Although the SQL option implies that no SQL statements can be specified,

non-executable statements are not restricted.

2. The stored procedure that is called must have the same or more restrictive level of SQL

data access than the current level in effect. For example, a routine defined as MODIFIES

SQL DATA can call a stored procedure defined as MODIFIES SQL DATA, READS SQL

DATA, CONTAINS SQL, or NO SQL. A routine defined as CONTAINS SQL can call a

procedure defined as CONTAINS SQL or NO SQL.

3. The COMMIT statement cannot be executed in a user-defined function. The COMMIT

statement cannot be executed in a stored procedure if the procedure is in the calling

chain of a user-defined function or trigger.

4. The statement specified for the EXECUTE statement must be a statement that is allowed

for the particular level of SQL data access in effect. For example, if the level in effect is

READS SQL DATA, the statement must not be an INSERT, UPDATE, MERGE, or

DELETE statement.

5. The statement is supported only if it does not contain a subquery or query-expression.

6. RELEASE SAVEPOINT, SAVEPOINT, and ROLLBACK (with the TO SAVEPOINT clause)

cannot be executed from a user-defined function.

7. If the ROLLBACK statement (without the TO SAVEPOINT clause) is executed in a

user-defined function, an error is returned to the calling program, and the application is

placed in a must rollback state.

8. The ROLLBACK statement (without the TO SAVEPOINT clause) cannot be executed in a

stored procedure if the procedure is in the calling chain of a user-defined function or

trigger.

9. If the SELECT statement contains an SQL data change statement, the SQL level of access

must be MODIFIES SQL DATA.

SQL statements allowed in SQL procedures

Table 251 lists the statements that are valid in an SQL procedure body, in addition

to SQL procedure statements. The table lists the statements that can be used as the

only statement in the SQL procedure and as the statements that can be nested in a

compound statement. An SQL statement can be executed in an SQL procedure

depending on whether MODIFIES SQL DATA, CONTAINS SQL, or READS SQL

DATA is specified in the stored procedure definition. See Table 250 on page 1212

for a list of SQL statements that can be executed for each of these parameter

values.

Table 251. Valid SQL statements in an SQL procedure body

SQL statement

SQL statement is...

The only statement

in the procedure

Nested in a

compound statement

ALLOCATE CURSOR Y

ALTER DATABASE Y Y

ALTER FUNCTION Y Y

ALTER INDEX Y Y

ALTER PROCEDURE Y Y


|||||

||

||

|

|

||||

|||

|||

|||

|||

|||

Table 251. Valid SQL statements in an SQL procedure body (continued)

SQL statement

SQL statement is...

The only statement

in the procedure

Nested in a

compound statement

ALTER SEQUENCE Y Y

ALTER STOGROUP Y Y

ALTER TABLE Y Y

ALTER TABLESPACE Y Y

ALTER TRUSTED CONTEXT Y Y

ALTER VIEW Y Y

ASSOCIATE LOCATORS Y

CALL Y

CLOSE Y

COMMENT Y Y

COMMIT1 Y Y

CONNECT Y Y

CREATE ALIAS Y Y

CREATE DATABASE Y Y

CREATE TYPE Y Y

CREATE FUNCTION2 Y Y

CREATE GLOBAL TEMPORARY TABLE Y Y

CREATE INDEX Y Y

CREATE PROCEDURE2 Y Y

CREATE ROLE Y Y

CREATE SEQUENCE Y Y

CREATE STOGROUP Y Y

CREATE SYNONYM Y Y

CREATE TABLE Y Y

CREATE TABLESPACE Y Y

CREATE TRUSTED CONTEXT Y Y

CREATE VIEW Y Y

DECLARE CURSOR Y

DECLARE GLOBAL TEMPORARY TABLE Y Y

DELETE Y Y

DROP INDEX Y Y

DROP ROLE Y Y

DROP TABLE Y Y

DROP TRUSTED CONTEXT Y Y

DROP VIEW Y Y

EXCHANGE Y Y

EXECUTE Y

EXECUTE IMMEDIATE Y Y


|

|

|

||||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

Table 251. Valid SQL statements in an SQL procedure body (continued)

SQL statement

SQL statement is...

The only statement

in the procedure

Nested in a

compound statement

FETCH3

Y

GET DIAGNOSTICS Y Y

GRANT Y Y

INSERT Y Y

LABEL Y Y

LOCK TABLE Y Y

MERGE Y Y

OPEN Y

PREPARE Y

REFRESH TABLE Y Y

RELEASE connection Y Y

RELEASE SAVEPOINT Y Y

RENAME Y Y

REVOKE Y Y

ROLLBACK1 Y Y

SAVEPOINT Y Y

SELECT INTO Y Y

SET CONNECTION Y Y

SET CURRENT DEBUG MODE Y Y

SET CURRENT DECFLOAT ROUNDING

MODE

Y Y

SET CURRENT ROUTINE VERSION Y Y

SET ENCRYPTION PASSWORD Y Y

SET PATH Y Y

SET SCHEMA Y Y

TRUNCATE Y Y

UPDATE Y Y

VALUES INTO Y Y

Notes:

1. The COMMIT statement and the ROLLBACK statement (without the TO SAVEPOINT

clause) cannot be executed in a procedure if the procedure is in the calling chain of a

user-defined function or trigger

2. CREATE FUNCTION with LANGUAGE SQL (specified either implicitly or explicitly)

and CREATE PROCEDURE with LANGUAGE SQL are not allowed within the body of

an SQL procedure.

3. The FETCH statement cannot specify the WITH CONTINUE or CURRENT CONTINUE

clauses within an SQL procedure body.


|

|

|

||||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

|||

||||

|||

|||

|||

|||

|||

|||

|||

|

|||

|||

|||


Appendix I. Program preparation options for remote packages

Table 252 gives generic descriptions of program preparation options, lists the

equivalent DB2 option for each one, and indicates if appropriate, whether it is a

bind package (B) or a precompiler (P) option. In addition, the table indicates

whether a DB2 server supports the option.

Table 252. Program preparation options for packages

Generic option description Equivalent for Requesting DB2

Bind or

Precompile

Option DB2 Server Support

Package replacement: protect

existing packages

ACTION(ADD) B Supported

Package replacement: replace

existing packages

ACTION(REPLACE) B Supported

Package replacement: version

name

ACTION(REPLACE REPLVER

(version-id))

B Supported

Statement string delimiter APOSTSQL/QUOTESQL P Supported

DRDA access: SQL CONNECT

(Type 1)

CONNECT(1) P Supported

DRDA access: SQL CONNECT

(Type 2)

CONNECT(2) P Supported

Block protocol: Do not block data

for an ambiguous cursor

CURRENTDATA(YES) B Supported

Block protocol: Block data when

possible

CURRENTDATA(NO) B Supported

Block protocol: Never block data (Not available) Not supported

Name of remote database CURRENTSERVER(location name) B Supported as a BIND

PLAN option

Date format of statement DATE P Supported

Protocol for remote access DBPROTOCOL B Not supported

Maximum decimal precision: 15 DEC(15) P Supported

Maximum decimal precision: 31 DEC(31) P Supported

Defer preparation of dynamic

SQL

DEFER(PREPARE) B Supported

Do not defer preparation of

dynamic SQL

NODEFER(PREPARE) B Supported

Dynamic SQL Authorization DYNAMICRULES B Supported

Encoding scheme for static SQL

statements

ENCODING B Not supported

Explain option EXPLAIN B Supported

Immediately write group

bufferpool-dependent page sets

or partitions in a data sharing

environment

IMMEDWRITE B Supported

Package isolation level: CS ISOLATION(CS) B Supported


Table 252. Program preparation options for packages (continued)


Bind or

Precompile


Package isolation level: RR ISOLATION(RR) B Supported

Package isolation level: RS ISOLATION(RS) B Supported

Package isolation level: UR ISOLATION(UR) B Supported

Keep prepared statements after

commit points

KEEPDYNAMIC B Supported

Consistency token LEVEL P Supported

Package name MEMBER B Supported

Package owner OWNER B Supported

Schema name list for user-defined

functions, distinct types, and

stored procedures

PATH B Supported

Statement decimal delimiter PERIOD/COMMA P Supported

Default qualifier QUALIFIER B Supported

Use access path hints OPTHINT B Supported

Lock release option RELEASE B Supported

Choose access path at each run

time

REOPT(ALWAYS) B Supported

Choose access path at bind time

only

REOPT(NONE) B Supported

Choose and cache access path at

only the first run or open time

REOPT(ONCE) B Supported

Choose access path at run time.

Each time a statement is

executed, DB2 determines if a

new access path is needed to

improve the performance of the

statement.

REOPT(AUTO B Supported

Creation control: create a package

despite errors

SQLERROR(CONTINUE) B Supported

Creation control: create no

package if there are errors

SQLERROR(NO PACKAGE) B Supported

Creation control: create no

package

(Not available) Supported

Time format of statement TIME P Supported

Existence checking: full VALIDATE(BIND) B Supported

Existence checking: deferred VALIDATE(RUN) B Supported

Package version VERSION P Supported

Default character subtype: system

default

(Not available) Supported

Default character subtype: BIT (Not available) Not supported

Default character subtype: SBCS (Not available) Not supported

Default character subtype: DBCS (Not available) Not supported

Default character CCSID: SBCS (Not available) Not supported


||||||

|||

Table 252. Program preparation options for packages (continued)


Bind or

Precompile


Default character CCSID: Mixed (Not available) Not supported

Default character CCSID: Graphic (Not available) Not supported

Package label (Not available) Ignored when received;

no error is returned

Privilege inheritance: retain default Supported

Privilege inheritance: revoke (Not available) Not supported

Appendix I. Program preparation options for remote packages 1221


Appendix J. DB2-supplied stored procedures

DB2 provides several stored procedures that you can call in your application

programs to perform a number of utility and application programming functions.

Those stored procedures are:

v The utilities stored procedure for EBCDIC input (DSNUTILS)

This stored procedure lets you invoke utilities from a local or remote client

program. For more information about DSNUTILS, see the topic “Invoking

utilities as a stored procedure (DSNUTILS)” in DB2 Utility Guide and Reference.

v The utilities stored procedure for Unicode input (DSNUTILU)

This stored procedure lets you invoke utilities from a local or remote client

program that generates Unicode utility control statements. For more information

about DSNUTILU, see the topic “DSNUTILU stored procedure” in DB2 Utility

Guide and Reference.

v The real-time statistics stored procedure (DSNACCOR)

This stored procedure queries the DB2 real-time statistics tables to help you

determine when you should run COPY, REORG, or RUNSTATS, or enlarge your

DB2 data sets. For more information about DSNACCOR, see the topic “The DB2

real-time statistics stored procedure” in DB2 Utility Guide and Reference.

v The WLM environment refresh stored procedure (WLM_REFRESH)

This stored procedure lets you refresh a WLM environment from a remote

workstation. For more information about WLM_REFRESH, see “WLM

environment refresh stored procedure (WLM_REFRESH)” on page 1226.

v The CICS transaction invocation stored procedure (DSNACICS)

This stored procedure lets you invoke CICS transactions from a remote

workstation. For more information about DSNACICS, see “The CICS transaction

invocation stored procedure (DSNACICS)” on page 1228.

v The SYSIBM.USERNAMES encryption stored procedure (DSNLEUSR)

This stored procedure lets you store encrypted values in the NEWAUTHID and

PASSWORD fields of the SYSIBM.USERNAMES catalog table. For more

information about DSNLEUSR, see the topic “The DSNLEUSR stored procedure”

in DB2 Administration Guide.

v The IMS transactions stored procedure (DSNAIMS)

This stored procedure allows DB2 to invoke IMS transactions and commands

easily, without maintaining their own connections to IMS. For more information

about DSNAIMS, see “IMS transactions stored procedure (DSNAIMS)” on page

1236.

v The EXPLAIN stored procedure (DSN8EXP)

This stored procedure enables a user to use the EXPLAIN function on an SQL

statement without having the authorization to execute that SQL statement. For

more information about DSN8EXP, see “The DB2 EXPLAIN stored procedure”

on page 1240.

v The MQ XML stored procedures

These stored procedures perform the following functions:


Table 253. MQ XML stored procedures

Stored procedure name Function For information, see:

DXXMQINSERT Returns a message that contains an XML document

from an MQ message queue, decomposes the

document, and stores the data in DB2 tables that are

specified by an enabled XML collection.

“Store an XML document from

an MQ message queue in DB2

tables (DXXMQINSERT)” on

page 1243

DXXMQSHRED Returns a message that contains an XML document



specified in a document access definition (DAD) file.

DXXMQSHRED does not require an enabled XML

collection.

“Store an XML document from


tables (DXXMQSHRED)” on

page 1245

DXXMQINSERTCLOB Returns a message that contains an XML document



specified by an enabled XML collection.

DXXMQINSERTCLOB is intended for an XML

document with a length of up to 1 MB.

“Store a large XML document

from an MQ message queue in

DB2 tables

(DXXMQINSERTCLOB)” on

page 1248

DXXMQSHREDCLOB Returns a message that contains an XML document



specified in a document access definition (DAD) file.

DXXMQSHREDCLOB does not require an enabled

XML collection. DXXMQSHREDCLOB is intended for

an XML document with a length of up to 1 MB.

“Store a large XML document


DB2 tables

(DXXMQSHREDCLOB)” on

page 1250

DXXMQINSERTALL Returns messages that contains XML documents from

an MQ message queue, decomposes the documents,

and stores the data in DB2 tables that are specified by

an enabled XML collection. DXXMQINSERTALL is

intended for XML documents with a length of up to 3

KB.

“Store XML documents from


tables (DXXMQINSERTALL)”

on page 1252

DXXMQSHREDALL Returns messages that contain XML documents from


and stores the data in DB2 tables that are specified in

a document access definition (DAD) file.

DXXMQSHREDALL does not require an enabled XML

collection. DXXMQSHREDALL is intended for XML

documents with a length of up to 3 KB.

“Store XML documents from


tables (DXXMQSHREDALL)”

on page 1255

DXXMQSHREDALLCLOB Returns messages that contain XML documents from


and stores the data in DB2 tables that are specified in

a document access definition (DAD) file.

DXXMQSHREDALLCLOB does not require an

enabled XML collection. DXXMQSHREDALLCLOB is

intended for XML documents with a length of up to

1MB.

“Store large XML documents


DB2 tables

(DXXMQSHREDALLCLOB)”

on page 1257

DXXMQINSERTALLCLOB Returns messages that contains XML documents from


and stores the data in DB2 tables that are specified by

an enabled XML collection. DXXMQINSERTALLCLOB

is intended for XML documents with a length of up to

1 MB.

“Store large XML documents


DB2 tables

(DXXMQINSERTALLCLOB)”

on page 1259


Table 253. MQ XML stored procedures (continued)


DXXMQGEN Constructs XML documents from data that is stored in

DB2 tables that are specified in a document access

definition (DAD) file, and sends the XML documents

to an MQ message queue. DXXMQGEN is intended

for XML documents with a length of up to 3 KB.

“Send XML documents to an

MQ message queue

(DXXMQGEN)” on page 1262

DXXMQRETRIEVE Constructs XML documents from data that is stored in

DB2 tables that are specified in an enabled XML

collection, and sends the XML documents to an MQ

message queue. DXXMQRETRIEVE is intended for

XML documents with a length of up to 3 KB.


MQ message queue

(DXXMQRETRIEVE)” on page

1265

DXXMQGENCLOB Constructs XML documents from data that is stored in

DB2 tables that are specified in a document access

definition (DAD) file, and sends the XML documents

to an MQ message queue. DXXMQGENCLOB is

intended for XML documents with a length of up to

32 KB.

“Send large XML documents to

an MQ message queue

(DXXMQGENCLOB)” on page

1269

DXXMQRETRIEVECLOB Constructs XML documents from data that is stored in

DB2 tables that are specified in an enabled XML

collection, and sends the XML documents to an MQ

message queue. DXXMQRETRIEVECLOB is intended

for XML documents with a length of up to 32 KB.


MQ message queue

(DXXMQRETRIEVECLOB)” on

page 1272

v The XML schema support and XML decomposition stored procedures

These stored procedures register an XML schema in the XSR and use the schema

to decompose XML data:

Table 254. XML schema and XML decomposition stored procedures


XSR_REGISTER The XSR_REGISTER procedure is the first stored

procedure to be called as part of the XML schema

registration process.

“The XML schema

registration stored

procedure

(XSR_REGISTER)” on page

1276

XSR_ADDSCHEMADOC The XSR_ADDSCHEMADOC stored procedure is used

to add every XML schema other than the primary XML

schema document.

“The add XML schema

document stored procedure

(XSR_ADDSCHEMADOC)”

on page 1277

XSR_COMPLETE The XSR_COMPLETE procedure is the final stored

procedure to be called as part of the XML schema

registration process.

“The XML schema

registration completion

stored procedure

(XSR_COMPLETE)” on page

1279

XSR_REMOVE The XSR_REMOVE procedure is used to remove all

components of an XML schema.

XDBDECOMPXML The XDBDECOMPXML procedure extracts values from

serialized XML data and populates relational tables with

the values.

“The XML decomposition

stored procedure

(XDBDECOMPXML)” on

page 1281

Appendix J. DB2-supplied stored procedures 1225

|

||

||

|||

||||

|||||

||||

||||

||||

|||||

||||

||||

|||||

WLM environment refresh stored procedure (WLM_REFRESH)

The WLM_REFRESH stored procedure refreshes a WLM environment.

WLM_REFRESH can recycle the environment in which it runs, as well as any other

WLM environment.

Environment for WLM_REFRESH

WLM_REFRESH runs in a WLM-established stored procedures address space. The

load module for WLM_REFRESH, DSNTWR, must reside in an APF-authorized

library.

Authorization required for WLM_REFRESH

To execute the CALL statement, the SQL authorization ID of the process must have

READ access or higher to the z/OS Security Server System Authorization Facility

(SAF) resource profile ssid.WLM_REFRESH.WLM-environment-name in resource

class DSNR. This is a different resource profile from the ssid.WLMENV.WLM-environment-name resource profile, which DB2 uses to determine whether a stored

procedure or user-defined function is authorized to run in the specified WLM

environment.

WLM_REFRESH uses an extended MCS console to monitor the operating system

response to a WLM environment refresh request. The privilege to create an

extended MCS console is controlled by the resource profile MVS.MCSOPER.* in the

OPERCMDS class. If the MVS.MCSOPER.* profile exists, or if the specific profile

MVS.MCSOPER.DSNTWR exists, the task ID that is associated with the WLM

environment in which WLM_REFRESH runs must have READ access to it.

If the MVS.VARY.* profile exists, or if the specific profile MVS.VARY.WLM exists,

the task ID that is associated with the WLM environment in which

WLM_REFRESH runs must have CONTROL access to it.

For more information about permitting access to the extended MCS console, see

z/OS MVS Planning: Operations.

WLM_REFRESH syntax diagram

The WLM_REFRESH stored procedure refreshes a WLM environment.

WLM_REFRESH can recycle the environment in which it runs, as well as any other

WLM environment.

The following syntax diagram shows the SQL CALL statement for invoking

WLM_REFRESH. The linkage convention for WLM_REFRESH is GENERAL WITH

NULLS.

�� CALL WLM_REFRESH ( WLM-environment, ssid ,

NULL

'

'

status-message, return-code ) ��


|

WLM_REFRESH option descriptions

WLM-environment

Specifies the name of the WLM environment that you want to refresh. This is

an input parameter of type VARCHAR(32).

ssid

Specifies the subsystem ID of the DB2 subsystem with which the WLM

environment is associated. If this parameter is NULL or blank, DB2 uses one of

the following values for this parameter:

v In a non-data sharing environment, DB2 uses the subsystem ID of the

subsystem on which WLM_REFRESH runs.

v In a data sharing environment, DB2 uses the group attach name for the data

sharing group in which WLM_REFRESH runs.

This is an input parameter of type VARCHAR(4).

status-message

Contains an informational message about the execution of the WLM refresh.

This is an output parameter of type VARCHAR(120).

return-code

Contains the return code from the WLM_REFRESH call, which is one of the

following values:

0 WLM_REFRESH executed successfully.

4 One of the following conditions exists:

v The SAF resource profile ssid.WLM_REFRESH.wlm-environment is not

defined in resource class DSNR.

v The SQL authorization ID of the process (CURRENT SQLID) is not

defined to SAF.

v The wait time to obtain a response from z/OS was exceeded.

8 The SQL authorization ID of the process (CURRENT SQLID) is not

authorized to refresh the WLM environment.

990 DSNTWR received an unexpected SQLCODE while determining the

current SQLID.

993 One of the following conditions exists:

v The WLM-environment parameter value is null, blank, or contains

invalid characters.

v The ssid value contains invalid characters.

994 The extended MCS console was not activated within the number of

seconds indicated by message DSNT5461.

995 DSNTWR is not running as an authorized program.

996 DSNTWR could not activate an extended MCS console. See message

DSNT533I for more information.

997 DSNTWR made an unsuccessful request for a message from its

extended MCS console. See message DSNT533I for more information.

998 The extended MCS console for DSNTWR posted an alert. See message

DSNT534I for more information.

999 The operating system denied an authorized WLM_REFRESH request.

See message DSNT545I for more information.


return-code is an output parameter of type INTEGER.

Example of WLM_REFRESH invocation

Suppose that you want to refresh WLM environment WLMENV1, which is

associated with a DB2 subsystem with ID DSN. Assume that you already have

READ access to the DSN.WLM_REFRESH.WLMENV1 SAF profile. The CALL

statement for WLM_REFRESH looks like this:

strcpy(WLMENV,"WLMENV1");

strcpy(SSID,"DSN");

EXEC SQL CALL SYSPROC.WLM_REFRESH(:WLMENV, :SSID, :MSGTEXT, :RC);

For a complete example of setting up access to an SAF profile and calling

WLM_REFRESH, see job DSNTEJ6W, which is in data set DSN910.SDSNSAMP.

The CICS transaction invocation stored procedure (DSNACICS)

You can use the CICS transaction invocation stored procedure (DSNACICS) to

invoke CICS server programs. Use the exit routine DSNACICX to change the

values of DSNACICS input parameters before you pass those parameters to CICS.

The DSNACICS stored procedure

The CICS transaction invocation stored procedure (DSNACICS) invokes CICS

server programs.

DSNACICS gives workstation applications a way to invoke CICS server

programs while using TCP/IP as their communication protocol. The workstation

applications use TCP/IP and DB2 Connect to connect to a DB2 for z/OS

subsystem, and then call DSNACICS to invoke the CICS server programs.

The DSNACICS input parameters require knowledge of various CICS resource

definitions with which the workstation programmer might not be familiar. For this

reason, DSNACICS invokes the DSNACICX user exit routine. The system

programmer can write a version of DSNACICX that checks and overrides the

parameters that the DSNACICS caller passes. If no user version of DSNACICX is

provided, DSNACICS invokes the default version of DSNACICX, which does not

modify any parameters.

Environment

DSNACICS runs in a WLM-established stored procedure address space and uses

the Resource Recovery Services attachment facility to connect to DB2.

If you use CICS Transaction Server for OS/390® Version 1 Release 3 or later, you

can register your CICS system as a resource manager with recoverable resource

management services (RRMS). When you do that, changes to DB2 databases that

are made by the program that calls DSNACICS and the CICS server program that

DSNACICS invokes are in the same two-phase commit scope. This means that

when the calling program performs an SQL COMMIT or ROLLBACK, DB2 and

RRS inform CICS about the COMMIT or ROLLBACK.

If the CICS server program that DSNACICS invokes accesses DB2 resources, the

server program runs under a separate unit of work from the original unit of work

that calls the stored procedure. This means that the CICS server program might

deadlock with locks that the client program acquires.


Authorization

To execute the CALL statement, the owner of the package or plan that contains the

CALL statement must have one or more of the following privileges:

v The EXECUTE privilege on stored procedure DSNACICS

v Ownership of the stored procedure

v SYSADM authority

The CICS server program that DSNACICS calls runs under the same user ID as

DSNACICS. That user ID depends on the SECURITY parameter that you specify

when you define DSNACICS. See Part 2 of DB2 Installation Guide.

The DSNACICS caller also needs authorization from an external security system,

such as RACF, to use CICS resources. See Part 2 of DB2 Installation Guide.

Syntax

The following syntax diagram shows the SQL CALL statement for invoking this

stored procedure.

Because the linkage convention for DSNACICS is GENERAL WITH NULLS, if you

pass parameters in host variables, you need to include a null indicator with every

host variable. Null indicators for input host variables must be initialized before

you execute the CALL statement.

�� CALL DSNACICS ( parm-level ,

NULL pgm-name ,

NULL CICS-applid ,

NULL CICS-level ,

NULL �

� connect-type ,

NULL netname ,

NULL mirror-trans ,

NULL COMMAREA ,

NULL COMMAREA-total-len ,

NULL �

� sync-opts ,

NULL return-code, msg-area ) ��

Option descriptions

parm-level

Specifies the level of the parameter list that is supplied to the stored procedure.

This is an input parameter of type INTEGER. The value must be 1.

pgm-name

Specifies the name of the CICS program that DSNACICS invokes. This is the

name of the program that the CICS mirror transaction calls, not the CICS

transaction name.

This is an input parameter of type CHAR(8).

CICS-applid

Specifies the applid of the CICS system to which DSNACICS connects.


CICS-level

Specifies the level of the target CICS subsystem:


1 The CICS subsystem is CICS for MVS/ESA™ Version 4 Release 1, CICS

Transaction Server for OS/390 Version 1 Release 1, or CICS Transaction

Server for OS/390 Version 1 Release 2.

2 The CICS subsystem is CICS Transaction Server for OS/390 Version 1

Release 3 or later.

This is an input parameter of type INTEGER.

connect-type

Specifies whether the CICS connection is generic or specific. Possible values are

GENERIC or SPECIFIC.


netname

If the value of connection-type is SPECIFIC, specifies the name of the specific

connection that is to be used. This value is ignored if the value of

connection-type is GENERIC.


mirror-trans

Specifies the name of the CICS mirror transaction to invoke. This mirror

transaction calls the CICS server program that is specified in the pgm-name

parameter. mirror-trans must be defined to the CICS server region, and the

CICS resource definition for mirror-trans must specify DFHMIRS as the

program that is associated with the transaction.

If this parameter contains blanks, DSNACICS passes a mirror transaction

parameter value of null to the CICS EXCI interface. This allows an installation

to override the transaction name in various CICS user-replaceable modules. If a

CICS user exit routine does not specify a value for the mirror transaction

name, CICS invokes CICS-supplied default mirror transaction CSMI.


COMMAREA

Specifies the communication area (COMMAREA) that is used to pass data

between the DSNACICS caller and the CICS server program that DSNACICS

calls.

This is an input/output parameter of type VARCHAR(32704). In the length

field of this parameter, specify the number of bytes that DSNACICS sends to

the CICS server program.

commarea-total-len

Specifies the total length of the COMMAREA that the server program needs.

This is an input parameter of type INTEGER. This length must be greater than

or equal to the value that you specify in the length field of the COMMAREA

parameter and less than or equal to 32704. When the CICS server program

completes, DSNACICS passes the server program’s entire COMMAREA, which

is commarea-total-len bytes in length, to the stored procedure caller.

sync-opts

Specifies whether the calling program controls resource recovery, using

two-phase commit protocols that are supported by RRS. Possible values are:

1 The client program controls commit processing. The CICS server region

does not perform a syncpoint when the server program returns control

to CICS. Also, the server program cannot take any explicit syncpoints.

Doing so causes the server program to abnormally terminate.


2 The target CICS server region takes a syncpoint on successful

completion of the server program. If this value is specified, the server

program can take explicit syncpoints.

When CICS has been set up to be an RRS resource manager, the client

application can control commit processing using SQL COMMIT requests. DB2

for z/OS ensures that CICS is notified to commit any resources that the CICS

server program modifies during two-phase commit processing.

When CICS has not been set up to be an RRS resource manager, CICS forces

syncpoint processing of all CICS resources at completion of the CICS server

program. This commit processing is not coordinated with the commit

processing of the client program.

This option is ignored when CICS-level is 1. This is an input parameter of type

INTEGER.

return-code

Return code from the stored procedure. Possible values are:

0 The call completed successfully.

12 The request to run the CICS server program failed. The msg-area

parameter contains messages that describe the error.

This is an output parameter of type INTEGER.

msg-area

Contains messages if an error occurs during stored procedure execution. The

first messages in this area are generated by the stored procedure. Messages

that are generated by CICS or the DSNACICX user exit routine might follow

the first messages. The messages appear as a series of concatenated, viewable

text strings.

This is an output parameter of type VARCHAR(500).

User exit routine

DSNACICS always calls user exit routine DSNACICX. You can use DSNACICX to

change the values of DSNACICS input parameters before you pass those

parameters to CICS. If you do not supply your own version of DSNACICX,

DSNACICS calls the default DSNACICX, which modifies no values and does an

immediate return to DSNACICS. The source code for the default version of

DSNACICX is in member DSNASCIX in data set prefix.SDSNSAMP.. The source

code for a sample version of DSNACICX that is written in COBOL is in member

DSNASCIO in data set prefix.SDSNSAMP.

Example

The following PL/I example shows the variable declarations and SQL CALL

statement for invoking the CICS transaction that is associated with program

CICSPGM1.

/***********************/

/* DSNACICS PARAMETERS */

/***********************/

DECLARE PARM_LEVEL BIN FIXED(31);

DECLARE PGM_NAME CHAR(8);

DECLARE CICS_APPLID CHAR(8);

DECLARE CICS_LEVEL BIN FIXED(31);

DECLARE CONNECT_TYPE CHAR(8);

DECLARE NETNAME CHAR(8);

DECLARE MIRROR_TRANS CHAR(4);


DECLARE COMMAREA_TOTAL_LEN BIN FIXED(31);

DECLARE SYNC_OPTS BIN FIXED(31);

DECLARE RET_CODE BIN FIXED(31);

DECLARE MSG_AREA CHAR(500) VARYING;

DECLARE1 COMMAREA BASED(P1),

3 COMMAREA_LEN BIN FIXED(15),

3COMMAREA_INPUT CHAR(30),

3 COMMAREA_OUTPUT CHAR(100);

/***********************************************/

/* INDICATOR VARIABLES FOR DSNACICS PARAMETERS */

/***********************************************/

DECLARE 1 IND_VARS,

3 IND_PARM_LEVEL BIN FIXED(15),

3 IND_PGM_NAME BIN FIXED(15),

3 IND_CICS_APPLID BIN FIXED(15),

3 IND_CICS_LEVEL BIN FIXED(15),

3 IND_CONNECT_TYPE BINFIXED(15),

3 IND_NETNAME BIN FIXED(15),

3 IND_MIRROR_TRANSBIN FIXED(15),

3 IND_COMMAREA BIN FIXED(15),

3 IND_COMMAREA_TOTAL_LEN BIN FIXED(15),

3 IND_SYNC_OPTS BIN FIXED(15),

3 IND_RETCODE BIN FIXED(15),

3 IND_MSG_AREA BIN FIXED(15);

/**************************/

/* LOCAL COPY OF COMMAREA */

/**************************/

DECLARE P1 POINTER;

DECLARE COMMAREA_STG CHAR(130) VARYING;

/**************************************************************/

/* ASSIGN VALUES TO INPUT PARAMETERS PARM_LEVEL, PGM_NAME, */

/* MIRROR_TRANS, COMMAREA, COMMAREA_TOTAL_LEN, AND SYNC_OPTS. */

/* SET THE OTHER INPUT PARAMETERS TO NULL. THE DSNACICX */

/* USER EXIT MUST ASSIGN VALUES FOR THOSE PARAMETERS. */

/**************************************************************/

PARM_LEVEL = 1;

IND_PARM_LEVEL = 0;

PGM_NAME = ’CICSPGM1’;

IND_PGM_NAME = 0 ;

MIRROR_TRANS = ’MIRT’;

IND_MIRROR_TRANS = 0;

P1 = ADDR(COMMAREA_STG);

COMMAREA_INPUT = ’THIS IS THE INPUT FOR CICSPGM1’;

COMMAREA_OUTPUT = ’ ’;

COMMAREA_LEN = LENGTH(COMMAREA_INPUT);

IND_COMMAREA = 0;

COMMAREA_TOTAL_LEN = COMMAREA_LEN + LENGTH(COMMAREA_OUTPUT);

IND_COMMAREA_TOTAL_LEN = 0;

SYNC_OPTS= 1;

IND_SYNC_OPTS = 0;

IND_CICS_APPLID= -1;

IND_CICS_LEVEL = -1;

IND_CONNECT_TYPE = -1;

IND_NETNAME = -1;

/*****************************************/

/* INITIALIZE

OUTPUT PARAMETERS TO NULL. */

/*****************************************/


IND_RETCODE = -1;

IND_MSG_AREA= -1;

/*****************************************/

/* CALL DSNACICS TO INVOKE CICSPGM1. */

/*****************************************/

EXEC SQL

CALL SYSPROC.DSNACICS(:PARM_LEVEL :IND_PARM_LEVEL,

:PGM_NAME :IND_PGM_NAME,

:CICS_APPLID :IND_CICS_APPLID,

:CICS_LEVEL :IND_CICS_LEVEL,

:CONNECT_TYPE :IND_CONNECT_TYPE,

:NETNAME :IND_NETNAME,

:MIRROR_TRANS :IND_MIRROR_TRANS,

:COMMAREA_STG :IND_COMMAREA,

:COMMAREA_TOTAL_LEN :IND_COMMAREA_TOTAL_LEN,

:SYNC_OPTS :IND_SYNC_OPTS,

:RET_CODE :IND_RETCODE,

:MSG_AREA :IND_MSG_AREA);

Output

DSNACICS places the return code from DSNACICS execution in the return-code

parameter. If the value of the return code is non-zero, DSNACICS puts its own

error messages and any error messages that are generated by CICS and the

DSNACICX user exit routine in the msg-area parameter.

The COMMAREA parameter contains the COMMAREA for the CICS server

program that DSNACICS calls. The COMMAREA parameter has a VARCHAR

type. Therefore, if the server program puts data other than character data in the

COMMAREA, that data can become corrupted by code page translation as it is

passed to the caller. To avoid code page translation, you can change the

COMMAREA parameter in the CREATE PROCEDURE statement for DSNACICS to

VARCHAR(32704) FOR BIT DATA. However, if you do so, the client program

might need to do code page translation on any character data in the COMMAREA

to make it readable.

Restrictions

Because DSNACICS uses the distributed program link (DPL) function to invoke

CICS server programs, server programs that you invoke through DSNACICS can

contain only the CICS API commands that the DPL function supports. The list of

supported commands is documented in CICS Transaction Server for z/OS

Application Programming Reference.

Debugging

If you receive errors when you call DSNACICS, ask your system administrator to

add a DSNDUMP DD statement in the startup procedure for the address space in

which DSNACICS runs. The DSNDUMP DD statement causes DB2 to generate an

SVC dump whenever DSNACICS issues an error message.

The DSNACICX user exit routine

Use DSNACICX to change the values of DSNACICS input parameters before you

pass those parameters to CICS.


General considerations

The DSNACICX exit routine must follow these rules:

v It can be written in assembler, COBOL, PL/I, or C.

v It must follow the Language Environment calling linkage when the caller is an

assembler language program.

v The load module for DSNACICX must reside in an authorized program library

that is in the STEPLIB concatenation of the stored procedure address space

startup procedure.

You can replace the default DSNACICX in the prefix.SDSNLOAD, library, or you

can put the DSNACICX load module in a library that is ahead of

prefix.SDSNLOAD in the STEPLIB concatenation. It is recommended that you

put DSNACICX in the prefix.SDSNEXIT library. Sample installation job

DSNTIJEX contains JCL for assembling and link-editing the sample source code

for DSNACICX into prefix.SDSNEXIT. You need to modify the JCL for the

libraries and the compiler that you are using.

v The load module must be named DSNACICX.

v The exit routine must save and restore the caller’s registers. Only the contents of

register 15 can be modified.

v It must be written to be reentrant and link-edited as reentrant.

v It must be written and link-edited to execute as AMODE(31),RMODE(ANY).

v DSNACICX can contain SQL statements. However, if it does, you need to

change the DSNACICS procedure definition to reflect the appropriate SQL access

level for the types of SQL statements that you use in the user exit routine.

Specifying the exit routine

DSNACICS always calls an exit routine named DSNACICX. DSNACICS calls your

DSNACICX exit routine if it finds it before the default DSNACICX exit routine.

Otherwise, it calls the default DSNACICX exit routine.

When the exit routine is taken

The DSNACICX exit routine is taken whenever DSNACICS is called. The exit

routine is taken before DSNACICS invokes the CICS server program.

Loading a new version of the exit routine

DB2 loads DSNACICX only once, when DSNACICS is first invoked. If you change

DSNACICX, you can load the new version by quiescing and then resuming the

WLM application environment for the stored procedure address space in which

DSNACICS runs:

VARY WLM,APPLENV=DSNACICS-applenv-name,QUIESCE VARY

WLM,APPLENV=DSNACICS-applenv-name,RESUME

Parameter list

At invocation, registers are set as described in the following table

Table 255. Registers at invocation of DSNACICX

Register Contains

1 Address of pointer to the exit parameter list

(XPL).


Table 255. Registers at invocation of DSNACICX (continued)

Register Contains

13 Address of the register save area.

14 Return address.

15 Address of entry point of exit routine.

The following table shows the contents of the DSNACICX exit parameter list, XPL.

Member DSNDXPL in data set prefix.SDSNMACS contains an assembler language

mapping macro for XPL. Sample exit routine DSNASCIO in data set

prefix.SDSNSAMP includes a COBOL mapping macro for XPL.

Table 256. Contents of the XPL exit parameter list

Name Hex offset Data type Description

Corresponding

DSNACICS

parameter

XPL_EYEC 0 Character, 4 bytes Eye-catcher: ’XPL ’

XPL_LEN 4 Character, 4 bytes Length of the exit

parameter list

XPL_LEVEL 8 4-byte integer Level of the

parameter list

parm-level

XPL_PGMNAME C Character, 8 bytes Name of the CICS

server program

pgm-name

XPL_CICSAPPLID 14 Character, 8 bytes CICS VTAM® applid CICS-applid

XPL_CICSLEVEL 1C 4-byte integer Level of CICS code CICS-level

XPL_CONNECTTYPE 20 Character, 8 bytes Specific or generic

connection to CICS

connect-type

XPL_NETNAME 28 Character, 8 bytes Name of the specific

connection to CICS

netname

XPL_MIRRORTRAN 30 Character, 8 bytes Name of the mirror

transaction that

invokes the CICS

server program

mirror-trans

XPL_COMMAREAPTR 38 Address, 4 bytes Address of the

COMMAREA

1

XPL_COMMINLEN 3C 4-byte integer Length of the

COMMAREA that is

passed to the server

program

2

XPL_COMMTOTLEN 40 4-byte integer Total length of the

COMMAREA that is

returned to the caller

commarea-total-len

XPL_SYNCOPTS 44 4-byte integer Syncpoint control

option

sync-opts

XPL_RETCODE 48 4-byte integer Return code from the

exit routine

return-code

XPL_MSGLEN 4C 4-byte integer Length of the output

message area

return-code

XPL_MSGAREA 50 Character, 256 bytes Output message area msg-area3


Table 256. Contents of the XPL exit parameter list (continued)

Name Hex offset Data type Description

Corresponding

DSNACICS

parameter

Notes:

1. The area that this field points to is specified by DSNACICS parameter COMMAREA. This area does not include

the length bytes.

2. This is the same value that the DSNACICS caller specifies in the length bytes of the COMMAREA parameter.

3. Although the total length of msg-area is 500 bytes, DSNACICX can use only 256 bytes of that area.

IMS transactions stored procedure (DSNAIMS)

You can use the IMS transactions stored procedure (DSNAIMS) to invoke IMS

transactions and commands, without applications having to maintain their own

connections to IMS.

The DSNAIMS stored procedure

DSNAIMS is a stored procedure that allows DB2 applications to invoke IMS

transactions and commands easily, without maintaining their own connections to

IMS.

DSNAIMS uses the IMS Open Transaction Manager Access (OTMA) API to

connect to IMS and execute the transactions.

Environment

DSNAIMS runs in a WLM-established stored procedures address space. DSNAIMS

requires DB2 with RRSAF enabled and IMS version 7 or later with OTMA Callable

Interface enabled.

To use a two-phase commit process, you must have IMS Version 8 with UQ70789

or later.

Authorization

To set up and run DSNAIMS, you must be authorized the perform the following

steps:

1. Use the job DSNTIJIM to issue the CREATE PROCEDURE statement for

DSNAIMS and to grant the execution of DSNAIMS to PUBLIC. DSNTIJIM is

provided in the SDSNSAMP data set. You need to customize DSNTIJIM to fit

the parameters of your system.

2. Ensure that OTMA C/I is initialized. See IMS Open Transaction Manager Access

Guide and Reference for an explanation of the C/I initialization.

Syntax

The following syntax diagram shows the SQL CALL statement for invoking this

stored procedure:


||

�� CALL SYSPROC.DSNAIMS ( dsnaims-function, dsnaims-2pc ,

NULL xcf-group-name, �

� xcf-ims-name, racf-userid, racf-groupid ,

NULL ims-lterm ,

NULL ims-modname ,

NULL �

� ims-tran-name ,

NULL ims-data-in ,

NULL ims-data-out ,

NULL otma-tpipe-name ,

NULL �

� otma-dru-name ,

NULL user-data-in ,

NULL user-data-out, status-message, return-code ) ��

Option descriptions

dsnaims-function

A string that indicates whether the transaction is send-only, receive-only, or

send-and-receive. Possible values are:

SENDRECV

Sends and receives IMS data. SENDRECV invokes an IMS transaction

or command and returns the result to the caller. The transaction can be

an IMS full function or a fast path. SENDRECV does not support

multiple iterations of a conversational transaction

SEND Sends IMS data. SEND invokes an IMS transaction or command, but

does not receive IMS data. If result data exists, it can be retrieved with

the RECEIVE function. A send-only transaction cannot be an IMS fast

path transaction or a conversations transaction.

RECEIVE

Receives IMS data. The data can be the result of a transaction or

command initiated by the SEND function or an unsolicited output

message from an IMS application. The RECEIVE function does not

initiate an IMS transaction or command.

dsnaims-2pc

Specifies whether to use a two-phase commit process to perform the

transaction syncpoint service. Possible values are Y or N. For N, commits and

rollbacks that are issued by the IMS transaction do not affect commit and

rollback processing in the DB2 application that invokes DSNAIMS.

Furthermore, IMS resources are not affected by commits and rollbacks that are

issued by the calling DB2 application. If you specify Y, you must also specify

SENDRECV. To use a two-phase commit process, you must set the IMS control

region parameter (RRS) to Y.

This parameter is optional. The default is N.

xcf-group-name

Specifies the XCF group name that the IMS OTMA joins. You can obtain this

name by viewing the GRNAME parameter in IMS PROCLIB member

DFSPBxxx or by using the IMS command /DISPLAY OTMA.

xcf-ims-name

Specifies the XCF member name that IMS uses for the XCF group. If IMS is not

using the XRF or RSR feature, you can obtain the XCF member name from the

OTMANM parameter in IMS PROCLIB member DFSPBxxx. If IMS is using the

XRF or RSR feature, you can obtain the XCF member name from the USERVAR

parameter in IMS PROCLIB member DFSPBxxx.


|||

|

racf-userid

Specifies the RACF user ID that is used for IMS to perform the transaction or

command authorization checking. This parameter is required if DSNAIMS is

running APF-authorized. If DSNAIMS is running unauthorized, this parameter

is ignored and the EXTERNAL SECURITY setting for the DSNAIMS stored

procedure definition determines the user ID that is used by IMS.

racf-groupid

Specifies the RACF group ID that is used for IMS to perform the transaction or

command authorization checking. This field is used for stored procedures that

are APF-authorized. It is ignored for other stored procedures.

ims-lterm

Specifies an IMS LTERM name that is used to override the LTERM name in the

I/O program communication block of the IMS application program.

This field is used as an input and an output field:

v For SENDRECV, the value is sent to IMS on input and can be updated by

IMS on output.

v For SEND, the parameter is IN only.

v For RECEIVE, the parameter is OUT only.

An empty or NULL value tells IMS to ignore the parameter.

ims-modname

Specifies the formatting map name that is used by the server to map output

data streams, such as 3270 streams. Although this invocation does not have

IMS MFS support, the input MODNAME can be used as the map name to

define the output data stream. This name is an 8-byte message output

descriptor name that is placed in the I/O program communication block.

When the message is inserted, IMS places this name in the message prefix with

the map name in the program communication block of the IMS application

program.

For SENDRECV, the value is sent to IMS on input, and can be updated on

output. For SEND, the parameter is IN only. For RECEIVE it is OUT only. IMS

ignores the parameter when it is an empty or NULL value.

ims-tran-name

Specifies the name of an IMS transaction or command that is sent to IMS. If

the IMS command is longer than eight characters, specify the first eight

characters (including the ″/″ of the command). Specify the remaining

characters of the command in the ims-tran-name parameter. If you use an empty

or NULL value, you must specify the full transaction name or command in the

ims-data-in parameter.

ims-data-in

Specifies the data that is sent to IMS. This parameter is required in each of the

following cases:

v Input data is required for IMS

v No transaction name or command is passed in ims-tran-name

v The command is longer than eight characters

This parameter is ignored when for RECEIVE functions.

ims-data-out

Data returned after successful completion of the transaction. This parameter is

required for SENDRECV and RECEIVE functions. The parameter is ignored for

SEND functions.


otma-tpipe-name

Specifies an 8-byte user-defined communication session name that IMS uses for

the input and output data for the transaction or the command in a SEND or a

RECEIVE function. If the otma_tpipe_name parameter is used for a SEND

function to generate an IMS output message, the same otma_pipe_name must

be used to retrieve output data for the subsequent RECEIVE function.

otma-dru-name

Specifies the name of an IMS user-defined exit routine, OTMA destination

resolution user exit routine, if it is used. This IMS exit routine can format part

of the output prefix and can determine the output destination for an IMS

ALT_PCB output. If an empty or null value is passed, IMS ignores this

parameter.

user-data-in

This optional parameter contains any data that is to be included in the IMS

message prefix, so that the data can be accessed by IMS OTMA user exit

routines (DFSYIOE0 and DFSYDRU0) and can be tracked by IMS log records.

IMS applications that run in dependent regions do not access this data. The

specified user data is not included in the output message prefix. You can use

this parameter to store input and output correlator tokens or other information.

This parameter is ignored for RECEIEVE functions.

user-data-out

On output, this field contains the user-data-in in the IMS output prefix. IMS

user exit routines (DFSYIOE0 and DFSYDRU0) can also create user-data-out for

SENDRECV and RECEIVE functions. The parameter is not updated for SEND

functions.

status-message

Indicates any error message that is returned from the transaction or command,

OTMA, RRS, or DSNAIMS.

return-code

Indicates the return code that is returned for the transaction or command,

OTMA, RRS, or DSNAIMS.

Examples

The following examples show how to call DSNAIMS.

Example 1: Sample parameters for executing an IMS command:

CALL SYSPROC.DSNAIMS("SENDRECV", "N", "IMS7GRP", "IMS7TMEM",

"IMSCLNM", "", "", "", "", "",

"/LOG Hello World.", ims_data_out, "", "", "",

user_out, error_message, rc)

Example 2: Sample parameters for executing an IMS IVTNO transaction:

CALL SYSPROC.DSNAIMS("SENDRECV", "N", "IMS7GRP", "IMS7TMEM",

"IMSCLNM", "", "", "", "", "",

"IVTNO DISPLAY LAST1 "", ims_data_out

"", "", "", user_out, error_message, rc)

Example 3: Sample parameters for send-only IMS transaction:

CALL SYSPROC.DSNAIMS("SEND", "N", "IMS7GRP", "IMS7TMEM",

"IMSCLNM", "", "", "", "", "",

"IVTNO DISPLAY LAST1 "", ims_data_out,

"DSNAPIPE", "", "", user_out, error_message, rc)


Example 4: Sample parameters for receive-only IMS transaction:

CALL SYSPROC.DSNAIMS("RECEIVE", "N", "IMS7GRP", "IMS7TMEM",

"IMSCLNM", "", "", "", "", "",

"IVTNO DISPLAY LAST1 "", ims_data_out,

"DSNAPIPE", "", "", user_out, error_message, rc)

Connecting to multiple IMS subsystems with DSNAIMS

By default DSNAIMS connects to only one IMS subsystem at a time. The first

request to DSNAIMS determines to which IMS subsystem the stored procedure

connects. DSNAIMS attempts to reconnect to IMS only in the following cases:

v IMS is restarted and the saved connection is no longer valid

v WLM loads another DSNAIMS task

To connect to multiple IMS subsystems simultaneously, perform the following

steps:

1. Make a copy of the DB2-supplied job DSNTIJIM and customize it to your

environment.

2. Change the procedure name from SYSPROCC.DSNAIMS to another name, such

as DSNAIMSB.

3. Do no change the EXTERNAL NAME option. Leave it as DSNAIMS.

4. Run the new job to create a second instance of the stored procedure.

5. To ensure that you connect to the intended IMS target, consistently use the XFC

group and member names that you associate with each stored procedure

instance. For example:

CALL SYSPROC.DSNAIMS("SENDRECV", "N", "IMS7GRP", "IMS7TMEM", ...)

CALL SYSPROC.DSNAIMSB("SENDRECV", "N", "IMS8GRP", "IMS8TMEM", ...)

The DB2 EXPLAIN stored procedure

The information under this heading is Product-sensitive Programming Interface

and Associated Guidance Information, as defined in “Notices” on page 1287.

The DSN8EXP stored procedure is a sample stored procedure that lets users

perform an EXPLAIN on an SQL statement without having the authorization to

execute that SQL statement.

Environment

DSN8EXP must run in a WLM-established stored procedure address space.

Before you can invoke DSN8EXP, table sqlid.PLAN_TABLE must exist. sqlid is the

value that you specify for the sqlid input parameter when you call DSN8EXP.

Job DSNTESC in DSN8910.SDSNSAMP contains a sample CREATE TABLE

statement for the PLAN_TABLE.

Authorization required

To execute the CALL DSN8.DSN8EXP statement, the owner of the package or plan

that contains the CALL statement must have one or more of the following

privileges on each package that the stored procedure uses:

v The EXECUTE privilege on the package for DSN8EXP


v Ownership of the package

v PACKADM authority for the package collection

v SYSADM authority

In addition:

v The SQL authorization ID of the process in which DSN8EXP is called must have

the authority to execute SET CURRENT SQLID=sqlid.

v The SQL authorization ID of the process must also have one of the following

characteristics:

– Be the owner of a plan table named PLAN_TABLE

– Have an alias on a plan table named owner.PLAN_TABLE and have SELECT

and INSERT privileges on the table

DSN8EXP syntax diagram

The following syntax diagram shows the CALL statement for invoking DSN8EXP.

Because the linkage convention for DSN8EXP is GENERAL, you cannot pass null

values to the stored procedure.

DSN8EXP option descriptions

sqlid

Specifies:

v The authorization ID under which the EXPLAIN statement is to be executed

v The qualifier for the table into which EXPLAIN output is written:

sqlid.PLAN_TABLE

v The implicit qualifier for unqualified objects in the SQL statement on which

EXPLAIN is executed, if the value of parse is 'N'

sqlid is an input parameter of type CHAR(8).

queryno

Specifies a number that is to be used to identify sql-statement in the EXPLAIN

output. This number appears in the QUERYNO column in the PLAN_TABLE.

queryno is an input parameter of type INTEGER.

sql-statement

Specifies the SQL statement on which EXPLAIN is to be executed. sql-statement

is an input parameter of type VARCHAR(32700).

parse

Specifies whether DSN8EXP adds a qualifier for unqualified table or view

names in the input SQL statement. Valid values are 'Y' and 'N'. If the value of

parse is 'Y', qualifier must contain a valid SQL qualifier name.

If sql-statement is insert-within-select and common table expressions, you need

to disable the parsing functionality, and add the qualifier manually.

parse is an input parameter of type CHAR(1).

�� CALL DSN8EXP ( sqlid, queryno, sql-statement, parse, qualifier, sqlcode, sqlstate, �

� error-message ) ��


qualifier

Specifies the qualifier that DSN8EXP adds to unqualified table or view names

in the input SQL statement. If the value of parse is 'N', qualifier is ignored.

If the statement on which EXPLAIN is run contains an INSERT within a

SELECT or a common table expression, parse must be 'N', and table and view

qualifiers must be explicitly specified.

qualifier is an input parameter of type CHAR(8).

sqlcode

Contains the SQLCODE from execution of the EXPLAIN statement. sqlcode is

an output parameter of type INTEGER.

sqlstate

Contains the SQLSTATE from execution of the EXPLAIN statement. sqlstate is

an output parameter of type CHAR(5).

error-message

Contains information about DSN8EXP execution. If the SQLCODE from

execution of the EXPLAIN statement is not 0, error-message contains the error

message for the SQLCODE. error-message is an output parameter of type

VARCHAR(960).

Example of DSN8EXP invocation

The following C example shows how to call DSN8EXP to execute an EXPLAIN

statement.


char hvsqlid[9]; /* Qualifier for PLAN_TABLE */

long int hvqueryno; /* QUERYNO to give the SQL */

struct {

short int hvsql_stmt_len; /* Input SQL statement length */

char hvsql_stmt_txt[32701]; /* SQL statement text */

} hvsql_stmt ; /* SQL statement to EXPLAIN */

char hvparse[1]; /* Qualify object names */

/* indicator */

char hvqualifier[9]; /* Qualifier for unqualified */

/* objects */

long int hvsqlcode; /* SQLCODE from CALL DSN8EXP */

char hvsqlstate[6]; /* SQLSTATE from CALL DSN8EXP */

struct {

short int hvmsg_len; /* Error message length */

char hvmsg_text[961]; /* Error message text */

} hvmsg; /* Error message from failed */

/* CALL DSN8EXP */


short int i; .../* Set the input parameters */

strcpy(hvsqlid,"ADMF001 ");

hvqueryno=320;

strcpy(hvsql_stmt.hvsql_stmt_text,"SELECT CURRENT DATE FROM SYSDUMMY1");

hvsql_stmt.hvsql_stmt_len=strlen(hvsql_stmt.hvsql_stmt_text);

hvparse[0]=’Y’;

strcpy(hvqualifier,"SYSIBM");

/* Initialize the output parameters */

hvsqlcode=0;

for (i = 0; i < 5; i++) hvsqlstate[i] = ’0’;

hvsqlstate[5]=’\0’;

hvmsg.hvmsg_len=0;

for (i = 0; i < 960; i++) hvmsg.hvmsg_text[i] = ’ ’;

hvmsg.hvmsg_text[960] = ’\0’;

/* Call DSN8EXP to do EXPLAIN and put output in ADMF001.PLAN_TABLE */

EXEC SQL


CALL DSN8.DSN8EXP(:hvsqlid,

:hvqueryno,

:hvsql_stmt,

:hvparse,

:hvqualifier,

:hvsqlcode,

:hvsqlstate,

:hvmsg);

DSN8EXP output

If DSN8EXP executes successfully, sqlid.PLAN_TABLE contains the EXPLAIN

output. A user with SELECT authority on sqlid.PLAN_TABLE can obtain the results

of the EXPLAIN that was executed by DSN8EXP by executing this query:

SELECT * FROM sqlid.PLAN_TABLE WHERE QUERYNO=’queryno’;

If DSN8EXP does not execute successfully, sqlcode, sqlstate, and error-message contain

error information.

Store an XML document from an MQ message queue in DB2 tables

(DXXMQINSERT)

The DXXMQINSERT stored procedure returns a message that contains an XML

document from an MQ message queue, decomposes the document, and stores the

data in DB2 tables that are specified by an enabled XML collection.

Use DXXMQINSERT for an XML document with a length of up to 3 KB.

There are two versions of DXXMQINSERT:

v A single-phase commit version, with schema name DMQXML1C.

v A two-phase commit version, with schema name DMQXML2C.

Environment for DXXMQINSERT

DXXMQINSERT runs in a WLM-established stored procedure address space and

uses the Resource Recovery Services attachment facility to connect to DB2.

DXXMQINSERT requires that WebSphere MQ and XML Extender are installed.

Authorization required for DXXMQINSERT



v The EXECUTE privilege on stored procedure DXXMQINSERT


v SYSADM authority

DXXMQINSERT syntax diagram


DXXMQINSERT. Because the linkage convention for DXXMQINSERT is GENERAL

WITH NULLS, if you pass parameters in host variables, you need to include a null

indicator with every host variable. Null indicators for input host variables must be

initialized before you execute the CALL statement.


�� CALL DMQXML1C .DXXMQINSERT

DMQXML2C ( service-name ,

NULL policy-name ,

NULL �

� XML-collection-name, status ) ��

DXXMQINSERT option descriptions

service-name

Specifies the service point that is the logical WebSphere MQ destination from

which the message is to be retrieved. The service point is defined in the

DSNAMT repository file. If service-name is not listed in the DSNAMT

repository file, or service-name is not specified, DB2.DEFAULT.SERVICE is used.

service-name is an input parameter of type VARCHAR(48). service-name cannot

be blank, a null string, or have trailing blanks.

policy-name

Specifies the WebSphere MQ AMI service policy that is used to handle the

message. The service policy is defined in the DSNAMT repository file. If

policy-name is not listed in the DSNAMT repository file, or policy-name is not

specified, DB2.DEFAULT.POLICY is used.

policy-name is an input parameter of type VARCHAR(48). policy-name cannot be

blank, a null string, or have trailing blanks.

XML-collection-name

Specifies the name of the XML collection that specifies the DB2 tables into

which the decomposed XML document is to be inserted. XML-collection-name is


status

Contains information that indicates whether DXXMQINSERT ran successfully.

The format of status is dxx-rc:sqlcode:mq-num-msgs, where:

v dxx-rc is the return code from accessing XML Extender. dxx-rc values are

defined in dxxrc.h.

v sqlcode is 0 if DXXMQINSERT ran successfully, or the SQLCODE from the

most recent unsuccessful SQL statement if DXXMQINSERT ran

unsuccessfully.

v mq-num-msgs is the number of messages that were successfully sent to the

MQ message queue.

status is an output parameter of type CHAR(20).

Example of DXXMQINSERT invocation

The following example calls the single-phase commit version of DXXMQINSERT to

retrieve an XML document from an MQ message queue and decompose it into

DB2 tables that are specified by enabled collection sales_ord. For a complete

example of DXXMQINSERT invocation, see DSN8QXSI in DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"



char serviceName[48]; /* WebSphere MQ service name */

char policyName[48]; /* WebSphere MQ policy name */

char collectionName[30]; /* XML collection name */

char status[20]; /* Status of DXXMQINSERT call */


/* DXXMQINSERT is GENERAL WITH NULLS, so parameters need indicators */

short serviceName_ind; /* Indicator var for serviceName */

short policyName_ind; /* Indicator var for policyName */

short collectionName_ind; /* Indicator var for collectionName */

short status_ind; /* Indicator var for status */


/* Initialize status fields */

int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;

/* Get the service name and policy name for the MQ message queue */

strcpy(serviceName,"DB2.DEFAULT.SERVICE");

strcpy(policyName,"DB2.DEFAULT.POLICY");

/* Get the XML collection name */

strcpy(collectionName,"sales_ord");

/* Initialize the output variable */

status[0] = ’\0’;

/* Set the indicators to 0 for the parameters that have non-null */

/* values */

collectionName_ind = 0;

serviceName_ind = 0;

policyName_ind = 0;

/* Initialize the indicator for the output parameter */

status_ind = -1;

/* Call the store procedure */

EXEC SQL CALL DMQXML1C.DXXMQINSERT(:serviceName:serviceName_ind,

:policyName:policyName_ind,

:dadFileName:dadFileName_ind,

:overrideType:ovtype_ind,

:override:ov_ind,

:max_row:maxrow_ind,

:num_row:numrow_ind,

:status:status_ind);

printf("SQLCODE from CALL: %d\n",sqlca.sqlcode);

/* Get the status fields from the status parameter and print them */

sscanf(status,"%d:%d:%d",&dxx_rc,&dxx_sql,&dxx_mq);

printf("Status fields: dxx_rc=%d dxx_sql=%d dxx_mq=%d\n",dxx_rc,dxx_sql,dxx_mq);

DXXMQINSERT output

If DXXMQINSERT executes successfully, the mq-num-msgs field of the status

parameter is set to 1, to indicate that a message was retrieved from the MQ

message queue and inserted into DB2 tables. If DXXMQINSERT does not execute

successfully, the contents of the status parameter indicate the problem.

Store an XML document from an MQ message queue in DB2 tables

(DXXMQSHRED)

The DXXMQSHRED stored procedure returns a message that contains an XML

document from an MQ message queue, decomposes the document, and stores the

data in DB2 tables that are specified in a document access definition (DAD) file.

DXXMQSHRED does not require an enabled XML collection.

Use DXXMQSHRED for an XML document with a length of up to 3 KB.

There are two versions of DXXMQSHRED:



Environment for DXXMQSHRED

DXXMQSHRED runs in a WLM-established stored procedure address space and



DXXMQSHRED requires that WebSphere MQ and XML Extender are installed.

Authorization required for DXXMQSHRED



v The EXECUTE privilege on stored procedure DXXMQSHRED


v SYSADM authority

DXXMQSHRED syntax diagram


DXXMQSHRED. Because the linkage convention for DXXMQSHRED is GENERAL




�� CALL DMQXML1C .DXXMQSHRED


NULL policy-name ,

NULL DAD-file-name, �

� status ) ��

DXXMQSHRED option descriptions

service-name







policy-name







DAD-file-name

Specifies the name of the (DAD) file that maps the XML document to DB2

tables. DAD-file-name must be specified, and must be the name of a valid DAD

file that exists on the system on which DXXMQSHRED runs. DAD-file-name is


status

Contains information that indicates whether DXXMQSHRED ran successfully.

The format of status is dxx-rc:sqlcode:mq-num-msgs, where:


defined in dxxrc.h.


v sqlcode is 0 if DXXMQSHRED ran successfully, or the SQLCODE from the

most recent unsuccessful SQL statement if DXXMQSHRED ran

unsuccessfully.


MQ message queue.


Example of DXXMQSHRED invocation

The following example calls the single-phase commit version of DXXMQSHRED to

retrieve an XML document from an MQ message queue and decompose it into

DB2 tables that are specified by DAD file /tmp/neworder2.dad. For a complete

example of DXXMQSHRED invocation, see DSN8QXSI in DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"





char dadFileName[30]; /* DAD file name */

char status[20]; /* Status of DXXMQSHRED call */

/* DXXMQSHRED is GENERAL WITH NULLS, so parameters need indicators */



short dadFileName_ind; /* Indicator var for dadFileName */




int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;




/* Get the DAD file name */

strcpy(dadFileName,"/tmp/neworder2.dad");


status[0] = ’\0’;


/* values */



policyName_ind = 0;


status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQSHRED(:serviceName:serviceName_ind,








DXXMQSHRED output

If DXXMQSHRED executes successfully, the mq-num-msgs field of the status


message queue and inserted into DB2 tables. If DXXMQSHRED does not execute



Store a large XML document from an MQ message queue in DB2

tables (DXXMQINSERTCLOB)

The DXXMQINSERTCLOB stored procedure returns a message that contains an

XML document from an MQ message queue, decomposes the document, and

stores the data in DB2 tables that are specified by an enabled XML collection.

Use DXXMQINSERTCLOB for an XML document with a length of up to 1 MB.

There are two versions of DXXMQINSERTCLOB:



Environment for DXXMQINSERTCLOB

DXXMQINSERTCLOB runs in a WLM-established stored procedure address space

and uses the Resource Recovery Services attachment facility to connect to DB2.

DXXMQINSERTCLOB requires that WebSphere MQ and XML Extender are

installed.

Authorization required for DXXMQINSERTCLOB



v The EXECUTE privilege on stored procedure DXXMQINSERTCLOB


v SYSADM authority

DXXMQINSERTCLOB syntax diagram


DXXMQINSERTCLOB. Because the linkage convention for DXXMQINSERTCLOB

is GENERAL WITH NULLS, if you pass parameters in host variables, you need to

include a null indicator with every host variable. Null indicators for input host

variables must be initialized before you execute the CALL statement.

�� CALL DMQXML1C .DXXMQINSERTCLOB


NULL policy-name ,

NULL �


DXXMQINSERTCLOB option descriptions

service-name








policy-name







XML-collection-name


which the decomposed XML document is to be inserted. XML-collection-name

must be specified, and must be the name of an enabled collection that exists on

the system on which DXXMQINSERTCLOB runs. XML-collection-name is an

input parameter of type VARCHAR(80).

status

Contains information that indicates whether DXXMQINSERTCLOB ran

successfully. The format of status is dxx-rc:sqlcode:mq-num-msgs, where:


defined in dxxrc.h.

v sqlcode is 0 if DXXMQINSERTCLOB ran successfully, or the SQLCODE from

the most recent unsuccessful SQL statement if DXXMQINSERTCLOB ran

unsuccessfully.


MQ message queue.


Example of DXXMQINSERTCLOB invocation

The following example calls the single-phase commit version of

DXXMQINSERTCLOB to retrieve all XML documents from an MQ message queue

and decompose them into DB2 tables that are specified by enabled collection

sales_ord. For a complete example of DXXMQINSERTCLOB invocation, see

DSN8QXSI in DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"






char status[20]; /* Status of DXXMQINSERTCLOB call */

/* DXXMQINSERTCLOB is GENERAL WITH NULLS, so parameters need indicators */







int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;







status[0] = ’\0’;



/* values */



policyName_ind = 0;


status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQINSERTCLOB(:serviceName:serviceName_ind,


:collectionName:collectionName_ind,






DXXMQINSERTCLOB output

If DXXMQINSERTCLOB executes successfully, the mq-num-msgs field of the status


message queue and inserted into DB2 tables. If DXXMQINSERTCLOB does not

execute successfully, the contents of the status parameter indicate the problem.

Store a large XML document from an MQ message queue in DB2

tables (DXXMQSHREDCLOB)

The DXXMQSHREDCLOB stored procedure returns a message that contains an

XML document from an MQ message queue, decomposes the document, and

stores the data in DB2 tables that are specified in a document access definition

(DAD) file. DXXMQSHREDCLOB does not require an enabled XML collection.

Use DXXMQSHREDCLOB for an XML document with a length of up to 1 MB.

There are two versions of DXXMQSHREDCLOB:



Environment for DXXMQSHREDCLOB

DXXMQSHREDCLOB runs in a WLM-established stored procedure address space


DXXMQSHREDCLOB requires that WebSphere MQ and XML Extender are

installed.

Authorization required for DXXMQSHREDCLOB



v The EXECUTE privilege on stored procedure DXXMQSHREDCLOB


v SYSADM authority

DXXMQSHREDCLOB syntax diagram


DXXMQSHREDCLOB. Because the linkage convention for DXXMQSHREDCLOB is

GENERAL WITH NULLS, if you pass parameters in host variables, you need to




�� CALL DMQXML1C .DXXMQSHREDCLOB


NULL policy-name ,


� status ) ��

DXXMQSHREDCLOB option descriptions

service-name







policy-name







DAD-file-name


tables. DAD-file-name is an input parameter of type VARCHAR(80).

status

Contains information that indicates whether DXXMQSHREDCLOB ran



defined in dxxrc.h.

v sqlcode is 0 if DXXMQSHREDCLOB ran successfully, or the SQLCODE from

the most recent unsuccessful SQL statement if DXXMQSHREDCLOB ran

unsuccessfully.


MQ message queue.


Example of DXXMQSHREDCLOB invocation


DXXMQSHREDCLOB to retrieve an XML document from an MQ message queue

and decompose it into DB2 tables that are specified by DAD file

/tmp/neworder2.dad. For a complete example of DXXMQSHREDCLOB

invocation, see DSN8QXSI in DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"







char status[20]; /* Status of DXXMQSHREDCLOB call */

/* DXXMQSHREDCLOB is GENERAL WITH NULLS, so parameters need indicators */







int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;







status[0] = ’\0’;


/* values */



policyName_ind = 0;


status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQSHREDCLOB(:serviceName:serviceName_ind,








DXXMQSHREDCLOB output

If DXXMQSHREDCLOB executes successfully, the mq-num-msgs field of the status


message queue and inserted into DB2 tables. If DXXMQSHREDCLOB does not


Store XML documents from an MQ message queue in DB2 tables

(DXXMQINSERTALL)

The DXXMQINSERTALL stored procedure returns messages that contains XML

documents from an MQ message queue, decomposes the documents, and stores

the data in DB2 tables that are specified by an enabled XML collection.

Use DXXMQINSERTALL for XML documents with a length of up to 3 KB.

There are two versions of DXXMQINSERTALL:



Environment for DXXMQINSERTALL

DXXMQINSERTALL runs in a WLM-established stored procedure address space



DXXMQINSERTALL requires that WebSphere MQ and XML Extender are installed.

Authorization required for DXXMQINSERTALL



v The EXECUTE privilege on stored procedure DXXMQINSERTALL


v SYSADM authority

DXXMQINSERTALL syntax diagram


DXXMQINSERTALL. Because the linkage convention for DXXMQINSERTALL is




�� CALL DMQXML1C .DXXMQINSERTALL


NULL policy-name ,

NULL �


DXXMQINSERTALL option descriptions

service-name


which the messages are to be retrieved. The service point is defined in the





policy-name


messages. The service policy is defined in the DSNAMT repository file. If





XML-collection-name


which the decomposed XML documents are to be inserted. XML-collection-name

must be specified, and must be the name of a valid XML collection that exists

on the system on which DXXMQINSERTALL runs.XML-collection-name is an


status

Contains information that indicates whether DXXMQINSERTALL ran



defined in dxxrc.h.


v sqlcode is 0 if DXXMQINSERTALL ran successfully, or the SQLCODE from

the most recent unsuccessful SQL statement if DXXMQINSERTALL ran

unsuccessfully.


MQ message queue.


Example of DXXMQINSERTALL invocation


DXXMQINSERTALL to retrieve all XML documents from an MQ message queue

and decompose them into DB2 tables that are specified by enabled collection

sales_ord. For a complete example of DXXMQINSERTALL invocation, see


#include "dxx.h"

#include "dxxrc.h"






char status[20]; /* Status of DXXMQINSERTALL call */

/* DXXMQINSERTALL is GENERAL WITH NULLS, so parameters need indicators */







int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;







status[0] = ’\0’;


/* values */



policyName_ind = 0;

/* Initialize the indicators for the output parameter */

status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQINSERTALL(:serviceName:serviceName_ind,








DXXMQINSERTALL output

If DXXMQINSERTALL executes successfully, the mq-num-msgs field of the status

parameter is set to the number of messages that were retrieved from the MQ

message queue and decomposed. If DXXMQINSERTALL does not execute



Store XML documents from an MQ message queue in DB2 tables

(DXXMQSHREDALL)

The DXXMQSHREDALL stored procedure returns messages that contain XML

documents from an MQ message queue, decomposes the documents, and stores

the data in DB2 tables that are specified in a document access definition (DAD)

file. DXXMQSHREDALL does not require an enabled XML collection.

Use DXXMQSHREDALL for XML documents with a length of up to 3 KB.

There are two versions of DXXMQSHREDALL:



Environment for DXXMQSHREDALL

DXXMQSHREDALL runs in a WLM-established stored procedure address space


DXXMQSHREDALL requires that WebSphere MQ and XML Extender are installed.

Authorization required for DXXMQSHREDALL



v The EXECUTE privilege on stored procedure DXXMQSHREDALL


v SYSADM authority

DXXMQSHREDALL syntax diagram


DXXMQSHREDALL. Because the linkage convention for DXXMQSHREDALL is




�� CALL DMQXML1C .DXXMQSHREDALL


NULL policy-name ,


� status ) ��

DXXMQSHREDALL option descriptions

service-name


which messages are to be retrieved. The service point is defined in the






policy-name







DAD-file-name



file that exists on the system on which DXXMQSHREDALL runs.DAD-file-name


status

Contains information that indicates whether DXXMQSHREDALL ran



defined in dxxrc.h.

v sqlcode is 0 if DXXMQSHREDALL ran successfully, or the SQLCODE from

the most recent unsuccessful SQL statement if DXXMQSHREDALL ran

unsuccessfully.


MQ message queue.


Example of DXXMQSHREDALL invocation


DXXMQSHREDALL to retrieve XML documents from an MQ message queue and

decompose them into DB2 tables that are specified by DAD file

/tmp/neworder2.dad. For a complete example of DXXMQSHREDALL invocation,

see DSN8QXSI in DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"






char status[20]; /* Status of DXXMQSHREDALL call */

/* DXXMQSHREDALL is GENERAL WITH NULLS, so parameters need indicators */







int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;







status[0] = ’\0’;


/* values */




policyName_ind = 0;


status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQSHREDALL(:serviceName:serviceName_ind,








DXXMQSHREDALL output

If DXXMQSHREDALL executes successfully, the mq-num-msgs field of the status

parameter is set to the number of messages that were retrieved from the MQ

message queue and inserted into DB2 tables. If DXXMQSHREDALL does not


Store large XML documents from an MQ message queue in DB2 tables

(DXXMQSHREDALLCLOB)

The DXXMQSHREDALLCLOB stored procedure returns messages that contain

XML documents from an MQ message queue, decomposes the documents, and

stores the data in DB2 tables that are specified in a document access definition

(DAD) file. DXXMQSHREDALLCLOB does not require an enabled XML collection.

Use DXXMQSHREDALLCLOB for XML documents with a length of up to 1 MB.

There are two versions of DXXMQSHREDALLCLOB:



Environment for DXXMQSHREDALLCLOB

DXXMQSHREDALLCLOB runs in a WLM-established stored procedure address

space and uses the Resource Recovery Services attachment facility to connect to

DB2.

DXXMQSHREDALLCLOB requires that WebSphere MQ and XML Extender are

installed.

Authorization required for DXXMQSHREDALLCLOB



v The EXECUTE privilege on stored procedure DXXMQSHREDALLCLOB


v SYSADM authority

DXXMQSHREDALLCLOB syntax diagram


DXXMQSHREDALLCLOB. Because the linkage convention for

DXXMQSHREDALLCLOB is GENERAL WITH NULLS, if you pass parameters in

host variables, you need to include a null indicator with every host variable. Null


indicators for input host variables must be initialized before you execute the CALL

statement.

�� CALL DMQXML1C .DXXMQSHREDALLCLOB


NULL policy-name ,

NULL �

� DAD-file-name, status ) ��

DXXMQSHREDALLCLOB option descriptions

service-name


which messages are to be retrieved. The service point is defined in the





policy-name







DAD-file-name



file that exists on the system on which DXXMQSHREDALLCLOB runs.

DAD-file-name is an input parameter of type VARCHAR(80).

status

Contains information that indicates whether DXXMQSHREDALLCLOB ran



defined in dxxrc.h.

v sqlcode is 0 if DXXMQSHREDALLCLOB ran successfully, or the SQLCODE

from the most recent unsuccessful SQL statement if

DXXMQSHREDALLCLOB ran unsuccessfully.


MQ message queue.


Example of DXXMQSHREDALLCLOB invocation


DXXMQSHREDALLCLOB to retrieve XML documents from an MQ message queue

and decompose them into DB2 tables that are specified by DAD file

/tmp/neworder2.dad. For a complete example of DXXMQSHREDALLCLOB

invocation, see DSN8QXSI in DSN910.SDSNSAMP.


#include "dxx.h"

#include "dxxrc.h"






char status[20]; /* Status of DXXMQSHREDALLCLOB call */

/* DXXMQSHREDALLCLOB is GENERAL WITH NULLS, so parameters need indicators */







int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;







status[0] = ’\0’;


/* values */



policyName_ind = 0;


status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQSHREDALLCLOB(:serviceName:serviceName_ind,








DXXMQSHREDALLCLOB output

If DXXMQSHREDALLCLOB executes successfully, the mq-num-msgs field of the

status parameter is set to the number of messages that were retrieved from the MQ

message queue and inserted into DB2 tables. If DXXMQSHREDALLCLOB does not


Store large XML documents from an MQ message queue in DB2 tables

(DXXMQINSERTALLCLOB)

The DXXMQINSERTALLCLOB stored procedure returns messages that contains

XML documents from an MQ message queue, decomposes the documents, and

stores the data in DB2 tables that are specified by an enabled XML collection.

Use DXXMQINSERTALLCLOB for XML documents with a length of up to 1 MB.

There are two versions of DXXMQINSERTALLCLOB:




Environment for DXXMQINSERTALLCLOB

DXXMQINSERTALLCLOB runs in a WLM-established stored procedure address


DB2.

DXXMQINSERTALLCLOB requires that WebSphere MQ and XML Extender are

installed.

Authorization required for DXXMQINSERTALLCLOB



v The EXECUTE privilege on stored procedure DXXMQINSERTALLCLOB


v SYSADM authority

DXXMQINSERTALLCLOB syntax diagram


DXXMQINSERTALLCLOB. Because the linkage convention for

DXXMQINSERTALLCLOB is GENERAL WITH NULLS, if you pass parameters in



statement.

�� CALL DMQXML1C .DXXMQINSERTALLCLOB


NULL policy-name ,

NULL �


DXXMQINSERTALLCLOB option descriptions

service-name


which the messages are to be retrieved. The service point is defined in the





policy-name







XML-collection-name


which the decomposed XML documents are to be inserted. XML-collection-name

must be specified, and must be the name of a valid XML collection that exists


on the system on which DXXMQINSERTALLCLOB runs. XML-collection-name is


status

Contains information that indicates whether DXXMQINSERTALLCLOB ran



defined in dxxrc.h.

v sqlcode is 0 if DXXMQINSERTALLCLOB ran successfully, or the SQLCODE


DXXMQINSERTALLCLOB ran unsuccessfully.


MQ message queue.


Example of DXXMQINSERTALLCLOB invocation


DXXMQINSERTALLCLOB to retrieve all XML documents from an MQ message

queue and decompose them into DB2 tables that are specified by enabled collection

sales_ord. For a complete example of DXXMQINSERTALLCLOB invocation, see


#include "dxx.h"

#include "dxxrc.h"






char status[20]; /* Status of DXXMQINSERTALLCLOB call */

/* DXXMQINSERTALLCLOB is GENERAL WITH NULLS, so parameters need indicators */







int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;







status[0] = ’\0’;


/* values */



policyName_ind = 0;

/* Initialize the indicators for the output parameter */

status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQINSERTALLCLOB(:serviceName:serviceName_ind,









DXXMQINSERTALLCLOB output

If DXXMQINSERTALLCLOB executes successfully, the mq-num-msgs field of the

status parameter is set to the number of messages that were retrieved from the MQ

message queue and decomposed. If DXXMQINSERTALLCLOB does not execute


Send XML documents to an MQ message queue (DXXMQGEN)

The DXXMQGEN stored procedure constructs XML documents from data that is

stored in DB2 tables that are specified in a document access definition (DAD) file,

and sends the XML documents to an MQ message queue.

Use DXXMQGEN for XML documents with a length of up to 3 KB.

There are two versions of DXXMQGEN:



Environment for DXXMQGEN

DXXMQGEN runs in a WLM-established stored procedure address space and uses

the Resource Recovery Services attachment facility to connect to DB2.

DXXMQGEN requires that WebSphere MQ and XML Extender are installed.

Authorization required for DXXMQGEN



v The EXECUTE privilege on stored procedure DXXMQGEN


v SYSADM authority

DXXMQGEN syntax diagram


DXXMQGEN. Because the linkage convention for DXXMQGEN is GENERAL




�� CALL DMQXML1C .DXXMQGEN


NULL policy-name ,


� override-type ,

NULL override ,

NULL max-rows ,

NULL num-msgs, status ) ��


DXXMQGEN option descriptions

service-name

Specifies the service point that is the logical WebSphere MQ destination to

which the message is to be sent. The service point is defined in the DSNAMT

repository file. If service-name is not listed in the DSNAMT repository file, or

service-name is not specified, DB2.DEFAULT.SERVICE is used.



policy-name







DAD-file-name

Specifies the name of the (DAD) file that maps the XML documents to DB2


file that exists on the system on which DXXMQGEN runs. DAD-file-name is an


override-type

Specifies what the override parameter does. Possible values are:

NO_OVERRIDE

The override parameter does not override the condition in the DAD file.

This is the default.

SQL_OVERRIDE

The DAD file uses SQL mapping, and the override parameter contains

an SQL statement that overrides the SQL statement in the DAD file.

XML_OVERRIDE

The DAD file uses RDB_node mapping, and the override parameter

contains conditions that override the RDB_node mapping in the DAD

file.

override-type is an input parameter of type INTEGER. The integer equivalents

of the override-type values are defined in the dxx.h file.

override

Specifies a string that overrides the condition in the DAD file. The contents of

the string depend on the value of the override-type parameter:

v If override-type is NO_OVERRIDE, override contains a null string. This is the

default.

v If override-type is SQL_OVERRIDE, override contains a valid SQL statement

that overrides the SQL statement in the DAD file.

v If override-type is XML_OVERRIDE, override contains one or more expressions

that are separated by AND. Each expression must be enclosed in double

quotation marks. This override value overrides the RDB_node mapping in the

DAD file.

override is an input parameter of type VARCHAR(1024).


max-rows

Specifies the maximum number of XML documents that DXXMQGEN can send

to the MQ message queue. The default is 1.

max-rows is an input parameter of type INTEGER.

num-rows

The actual number of XML documents that DXXMQGEN sends to the MQ

message queue.

num-rows is an output parameter of type INTEGER.

status

Contains information that indicates whether DXXMQGEN ran successfully. The

format of status is dxx-rc:sqlcode:mq-num-msgs, where:


defined in dxxrc.h.

v sqlcode is 0 if DXXMQGEN ran successfully, or the SQLCODE from the most

recent unsuccessful SQL statement if DXXMQGEN ran unsuccessfully.


MQ message queue.


Example of DXXMQGEN invocation

The following example calls the single-phase commit version of DXXMQGEN to

generate XML documents and send them to an MQ message queue. The calling

program does not override the definitions in the DAD file. For a complete example

of DXXMQGEN invocation, see DSN8QXGR in DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"






short overrideType; /* defined in dxx.h */

char override[2]; /* Override string for DAD */

short max_row; /* Maximum number of documents*/

short num_row; /* Actual number of documents */

char status[20]; /* Status of DXXMQGEN call */

/* DXXMQGEN is GENERAL WITH NULLS, so parameters need indicators */




short ovtype_ind; /* Indicator var for overrideType */

short ov_ind; /* Indicator var for override */

short maxrow_ind; /* Indicator var for maxrow */

short numrow_ind; /* Indicator var for numrow */



/* Status fields */

int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;




/* Get the name of the DAD file for the DB2 tables */

strcpy(dadFileName,"/tmp/getstart_xcollection.dad");

/* Put null in the override parameter because we are not going */

/* to override the values in the DAD file */

override[0] = ’\0’;


overrideType = NO_OVERRIDE;

/* Indicate that we do not want to transfer more than 500 */

/* documents */

max_row = 500;

/* Initialize the output variables */

num_row = 0;

status[0] = ’\0’;


/* values */

dadFileName_ind = 0;


policyName_ind = 0;

maxrow_ind = 0;

/* Initialize the indicators for the output parameters */

numrow_ind = -1;

status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQGEN(:serviceName:serviceName_ind,




:override:ov_ind,








DXXMQGEN output

If DXXMQGEN executes successfully, the number of documents indicated by the

mq-num-msgs field of the status parameter are extracted from DB2 tables and

inserted into the MQ message queue. If DXXMQGEN does not execute


Send XML documents to an MQ message queue (DXXMQRETRIEVE)

The DXXMQRETRIEVE stored procedure constructs XML documents from data

that is stored in DB2 tables that are specified in an enabled XML collection, and

sends the XML documents to an MQ message queue.

Use DXXMQRETRIEVE for XML documents with a length of up to 3KB.

There are two versions of DXXMQRETRIEVE:



Environment for DXXMQRETRIEVE

DXXMQRETRIEVE runs in a WLM-established stored procedure address space and


DXXMQRETRIEVE requires that WebSphere MQ and XML Extender are installed.

Authorization required for DXXMQRETRIEVE



v The EXECUTE privilege on stored procedure DXXMQRETRIEVE



v SYSADM authority

DXXMQRETRIEVE syntax diagram


DXXMQRETRIEVE. Because the linkage convention for DXXMQRETRIEVE is




�� CALL DMQXML1C .DXXMQRETRIEVE


NULL policy-name ,

NULL �

� XML-collection-name, override-type ,

NULL override ,

NULL max-rows ,


DXXMQRETRIEVE option descriptions

service-name







policy-name







XML-collection-name

Specifies the name of the XML collection that specifies the DB2 tables from

which the XML documents are to be retrieved. XML-collection-name must be

specified, and must be the name of a valid XML collection that exists on the

system on which DXXMQRETRIEVE runs. XML-collection-name is an input

parameter of type VARCHAR(80).

override-type


NO_OVERRIDE

The override parameter does not override the XML collection. This is

the default.

SQL_OVERRIDE


an SQL statement that overrides the SQL statement in the XML

collection.


XML_OVERRIDE


contains conditions that override the conditions in the XML collection.



override-type


NO_OVERRIDE



SQL_OVERRIDE



XML_OVERRIDE



file.



override




default.






DAD file.


max-rows

Specifies the maximum number of XML documents that DXXMQRETRIEVE

can send to the MQ message queue. The default is 1.


num-rows

The actual number of XML documents that DXXMQRETRIEVE sends to the

MQ message queue.


status

Contains information that indicates whether DXXMQRETRIEVE ran



defined in dxxrc.h.

v sqlcode is 0 if DXXMQRETRIEVE ran successfully, or the SQLCODE from the

most recent unsuccessful SQL statement if DXXMQRETRIEVE ran

unsuccessfully.



MQ message queue.


Example of DXXMQRETRIEVE invocation

The following example calls the single-phase commit version of DXXMQRETRIEVE

to generate XML documents and send them to an MQ message queue. The calling

program does not override the definitions in the DAD file. For a complete example

of DXXMQRETRIEVE invocation, see DSN8QXGR in DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"










char status[20]; /* Status of DXXMQRETRIEVE call */

/* DXXMQRETRIEVE is GENERAL WITH NULLS, so parameters need indicators */



short collectionName_ind; /* Indicator var for dadFileName */







/* Status fields */

int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;











/* documents */

max_row = 500;


num_row = 0;

status[0] = ’\0’;


/* values */



policyName_ind = 0;

maxrow_ind = 0;


numrow_ind = -1;

status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQRETRIEVE(:serviceName:serviceName_ind,





:override:ov_ind,








DXXMQRETRIEVE output

If DXXMQRETRIEVE executes successfully, the number of documents indicated by

the mq-num-msgs field of the status parameter are extracted from DB2 tables and

inserted into the MQ message queue. If DXXMQRETRIEVE does not execute


Send large XML documents to an MQ message queue

(DXXMQGENCLOB)

The DXXMQGENCLOB stored procedure constructs XML documents from data

that is stored in DB2 tables that are specified in a document access definition

(DAD) file, and sends the XML documents to an MQ message queue.

Use DXXMQGENCLOB for XML documents with a record length of up to 32 KB.

There are two versions of DXXMQGENCLOB:



Environment for DXXMQGENCLOB

DXXMQGENCLOB runs in a WLM-established stored procedure address space


DXXMQGENCLOB requires that WebSphere MQ and XML Extender are installed.

Authorization required for DXXMQGENCLOB



v The EXECUTE privilege on stored procedure DXXMQGENCLOB


v SYSADM authority

DXXMQGENCLOB syntax diagram


DXXMQGENCLOB. Because the linkage convention for DXXMQGENCLOB is





�� CALL DMQXML1C .DXXMQGENCLOB


NULL policy-name ,


� override-type ,

NULL override ,

NULL max-rows ,


DXXMQGENCLOB option descriptions

service-name







policy-name







DAD-file-name

Specifies the name of the (DAD) file that maps the XML documents to DB2


file that exists on the system on which DXXMQGENCLOB runs. DAD-file-name


override-type


NO_OVERRIDE



SQL_OVERRIDE



XML_OVERRIDE



file.



override




default.







DAD file.


max-rows

Specifies the maximum number of XML documents that DXXMQGENCLOB

can send to the MQ message queue. The default is 1.


num-rows

The actual number of XML documents that DXXMQGENCLOB sends to the

MQ message queue.


status

Contains information that indicates whether DXXMQGENCLOB ran



defined in dxxrc.h.

v sqlcode is 0 if DXXMQGENCLOB ran successfully, or the SQLCODE from the

most recent unsuccessful SQL statement if DXXMQGENCLOB ran

unsuccessfully.


MQ message queue.


Example of DXXMQGENCLOB invocation

The following example calls the two-phase commit version of DXXMQGENCLOB

to generate CLOB XML documents and send them to an MQ message queue. The

calling program does not override the definitions in the DAD file. For a complete

example of DXXMQGENCLOB invocation, see DSN8QXGR in

DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"










char status[20]; /* Status of DXXMQGENCLOB call */

/* DXXMQGENCLOB is GENERAL WITH NULLS, so parameters need indicators */










/* Status fields */

int dxx_rc=0;


int dxx_sql=0;

int dxx_mq=0;




/* Get the name of the DAD file for the DB2 tables */

strcpy(dadFileName,"/tmp/getstart_xcollection.dad");






/* documents */

max_row = 500;


num_row = 0;

status[0] = ’\0’;


/* values */

dadFileName_ind = 0;


policyName_ind = 0;

maxrow_ind = 0;


numrow_ind = -1;

status_ind = -1;


EXEC SQL CALL DMQXML2C.DXXMQGENCLOB(:serviceName:serviceName_ind,




:override:ov_ind,








DXXMQGENCLOB output

If DXXMQGENCLOB executes successfully, the number of documents indicated by

the mq-num-msgs field of the status parameter are extracted from DB2 tables and

inserted into the MQ message queue. If DXXMQGENCLOB does not execute


Send XML documents to an MQ message queue

(DXXMQRETRIEVECLOB)

The DXXMQRETRIEVECLOB stored procedure constructs XML documents from

data that is stored in DB2 tables that are specified in an enabled XML collection,

and sends the XML documents to an MQ message queue.

Use DXXMQRETRIEVECLOB for XML documents with a length of up to 32 KB.

There are two versions of DXXMQRETRIEVECLOB:




Environment for DXXMQRETRIEVECLOB

DXXMQRETRIEVECLOB runs in a WLM-established stored procedure address


DB2.

DXXMQRETRIEVECLOB requires that WebSphere MQ and XML Extender are

installed.

Authorization required for DXXMQRETRIEVECLOB



v The EXECUTE privilege on stored procedure DXXMQRETRIEVECLOB


v SYSADM authority

DXXMQRETRIEVECLOB syntax diagram


DXXMQRETRIEVECLOB. Because the linkage convention for

DXXMQRETRIEVECLOB is GENERAL WITH NULLS, if you pass parameters in



statement.

�� CALL DMQXML1C .DXXMQRETRIEVECLOB


NULL policy-name ,

NULL �

� XML-collection-name, override-type ,

NULL override ,

NULL max-rows ,


DXXMQRETRIEVECLOB option descriptions

service-name







policy-name







XML-collection-name

Specifies the name of the XML collection that specifies the DB2 tables from

which the XML documents are to be retrieved. XML-collection-name must be

specified, and must be the name of a valid XML collection that exists on the


system on which DXXMQRETRIEVECLOB runs. XML-collection-name is an


override-type


NO_OVERRIDE



SQL_OVERRIDE



XML_OVERRIDE



file.



override




default.






DAD file.


max-rows

Specifies the maximum number of XML documents that

DXXMQRETRIEVECLOB can send to the MQ message queue. The default is 1.


num-rows

The actual number of XML documents that DXXMQRETRIEVECLOB sends to

the MQ message queue.


status

Contains information that indicates whether DXXMQRETRIEVECLOB ran



defined in dxxrc.h.

v sqlcode is 0 if DXXMQRETRIEVECLOB ran successfully, or the SQLCODE


DXXMQRETRIEVECLOB ran unsuccessfully.


MQ message queue.



Example of DXXMQRETRIEVECLOB invocation


DXXMQRETRIEVECLOB to generate XML documents and send them to an MQ

message queue. The calling program does not override the definitions in the DAD

file. For a complete example of DXXMQRETRIEVECLOB invocation, see

DSN8QXGR in DSN910.SDSNSAMP.

#include "dxx.h"

#include "dxxrc.h"










char status[20]; /* Status of DXXMQRETRIEVECLOB call */

/* DXXMQRETRIEVECLOB is GENERAL WITH NULLS, so parameters need indicators */



short collectionName_ind; /* Indicator var for dadFileName */







/* Status fields */

int dxx_rc=0;

int dxx_sql=0;

int dxx_mq=0;











/* documents */

max_row = 500;


num_row = 0;

status[0] = ’\0’;


/* values */



policyName_ind = 0;

maxrow_ind = 0;


numrow_ind = -1;

status_ind = -1;


EXEC SQL CALL DMQXML1C.DXXMQRETRIEVECLOB(:serviceName:serviceName_ind,




:override:ov_ind,









DXXMQRETRIEVECLOB output

If DXXMQRETRIEVECLOB executes successfully, the number of documents

indicated by the mq-num-msgs field of the status parameter are extracted from DB2

tables and inserted into the MQ message queue. If DXXMQRETRIEVECLOB does

not execute successfully, the contents of the status parameter indicate the problem.

The XML schema registration stored procedure (XSR_REGISTER)

The XSR_REGISTER procedure is the first stored procedure to be called as part of

the XML schema registration process, which registers XML schemas with the XSR.

The user that calls this stored procedure is considered the creator of this XML

schema. DB2 obtains the namespace attribute from the schema document when

XSR_COMPLETE is invoked.

Environment for XSR_REGISTER:

XSR_REGISTER runs in a WLM-established stored procedures address space.

Authorization required for XSR_REGISTER:

The user ID of the caller of the procedure must have the EXECUTE privilege on

the XSR_REGISTER stored procedure.

XSR_REGISTER syntax diagram:

The following syntax diagram shows the CALL statement for invoking

XSR_REGISTER.

XSR_REGISTER option descriptions:

rschema

An input argument of type VARCHAR(128) that specifies the SQL schema for

the XML schema. If a value is specified, it must be SYSXSR.

name

An input and output argument of type VARCHAR(128) that specifies the name

of the XML schema. The complete SQL identifier for the XML schema is

″rschema.name″ and should be unique among all objects in the XSR. This

argument accepts a NULL value. When a NULL value is provided for this

argument, a unique value is generated and stored within the XSR. Rules for

valid characters and delimiters that apply to any SQL identifier also apply to

this argument.

�� SYSPROC

CALL

.

XSR_REGISTER

(

rschema

,

NULL

name

,

NULL

schemalocation

,

NULL

�

� content , docproperty )

NULL ��


||||||||||||||||||||||||||||||||||||||||||||||

||||||||||||||||||||

|||

|

|||||

|

|

|

||

|

|||

|

|||

||||||||

schemalocation

An input argument of type VARCHAR(1000), which can have a NULL value,

that indicates the schema location of the primary XML schema document. This

argument is the ″external name″ of the XML schema, that is, the primary

document can be identified in the XML instance documents with the

xsi:schemaLocation attribute.

content

An input parameter of type BLOB(30M) that contains the content of the

primary XML schema document. This argument cannot have a NULL value; an

XML schema document must be supplied.

docproperty

An input parameter of type BLOB(5M) that indicates the properties for the

primary XML schema document. This parameter can have a NULL value;

otherwise, the value is an XML document.

Example of XSR_REGISTER:

The following example calls the XSR_REGISTER stored procedure:

CALL SYSPROC.XSR_REGISTER(

’SYSXSR’,

’POschema’,

’http://myPOschema/PO.xsd’,

:content_host_var,

:docproperty_host_var)

The add XML schema document stored procedure

(XSR_ADDSCHEMADOC)

Each XML schema in the XSR can consist of one or more XML schema documents.

When an XML schema consists of multiple documents, the

XSR_ADDSCHEMADOC stored procedure is used to add every XML schema other

than the primary XML schema document.

Environment for XSR_ADDSCHEMADOC:

XSR_ADDSCHEMADOC runs in a WLM-established stored procedures address

space.

Authorization required for XSR_ADDSCHEMADOC:

The user ID of the caller of the procedure must have the EXECUTE privilege on

the XSR_ADDSCHEMADOC stored procedure.

XSR_ADDSCHEMADOC syntax diagram:


XSR_ADDSCHEMADOC.


||||||

||||

||||

|

|

||||||

||

|

||||

|

||

|

||

|

|||

XSR_ADDSCHEMADOC option descriptions:

rschema



name

An input argument of type VARCHAR(128) that specifies the name of the XML

schema. The complete SQL identifier for the XML schema is ″rschema.name″.

The XML schema name must already exist as a result of calling the

XSR_REGISTER stored procedure, and XML schema registration cannot yet be

completed. This argument cannot have a NULL value. Rules for valid

characters and delimiters that apply to any SQL identifier also apply to this

argument.

schemalocation

An input argument of type VARCHAR(1000), which can have a NULL value,

that indicates the schema location of the primary XML schema document to

which the XML schema document is being added. This argument is the

″external name″ of the XML schema, that is, the primary document can be

identified in the XML instance documents with the xsi:schemaLocation

attribute. The document that references the schemalocation must use valid a

URI format.

content

An input parameter of type BLOB(30M) that contains the content of the XML

schema document being added. This argument cannot have a NULL value; an

XML schema document must be supplied.

docproperty

An input parameter of type BLOB(5M) that indicates the properties for the

XML schema document being added. This parameter can have a NULL value;

otherwise, the value is an XML document.

Example of XSR_ADDSCHEMADOC:

The following example calls the XSR_ADDSCHEMADOC stored procedure:

CALL SYSPROC.XSR_COMPLETE(

’SYSXSR’,

’POschema’,

:schemaproperty_host_var,

0)

�� SYSPROC

CALL

.

XSR_ADDSCHEMADOC

(

rschema

,

NULL

name

,

schemalocation

,

NULL

�

� content , docproperty )

NULL ��


||||||||||||||||||||||||||||||||||||||||

||||||||||||||||||||

||||

|||

||||||||

||||||||

||||

||||

|

|

|||||

The XML schema registration completion stored procedure

(XSR_COMPLETE)

The XSR_COMPLETE procedure is the final stored procedure to be called as part

of the XML schema registration process, which registers XML schemas with the

XSR. An XML schema is not available for validation until the schema registration

completes through a call to this stored procedure.

Environment for XSR_COMPLETE:

:

XSR_COMPLETE runs in a WLM-established stored procedures address space.

Authorization required for XSR_COMPLETE:

The user ID of the caller of the procedure must be the definer of the XSR object as

recorded in the catalog view SYSCAT.XSROBJECTS.

XSR_COMPLETE syntax diagram:


XSR_COMPLETE.

�� SYSPROC

CALL

.

XSR_COMPLETE

(

rschema

,

name

,

schemaproperties

,

�

� issuedfordecomposition ) ��

XSR_COMPLETE option descriptions:

rschema



name


schema. The complete SQL identifier for the XML schema, for which a

completion check is to be performed, is ″rschema.name″. The XML schema

name must already exist as a result of calling the XSR_REGISTER stored

procedure, and XML schema registration cannot yet be completed. This

argument cannot have a NULL value. Rules for valid characters and delimiters

that apply to any SQL identifier also apply to this argument.

schemaproperties

An input argument of type BLOB(5M) that specifies properties, if any,

associated with the XML schema. The value for this argument is either NULL,

if there are no associated properties, or an XML document representing the

properties for the XML schema.

isusedforshred

An input parameter of type integer that indicates if an XML schema is to be

used for shredding. If an XML schema is to be used for shredding, this value

should be set to 1; otherwise, it should be set to zero.


||

|

||||

|

|

|

|

||

|

|||

|||||||||||||||||||||||||||||

||||||||||

||||

|||

||||||||

|||||

||||

Example of XSR_COMPLETE:

The following example calls the XSR_COMPLETE stored procedure:

CALL SYSPROC.XSR_COMPLETE(

’SYSXSR’,

’POschema’,

:schemaproperty_host_var,

0)

The XML schema removal stored procedure (XSR_REMOVE)

The XSR_REMOVE procedure is used to remove all components of an XML

schema. After the XML schema is removed, you can reuse the name of the

removed XML schema when you register a new XML schema.

Environment for XSR_REMOVE:

XSR_REMOVE runs in a WLM-established stored procedures address space.

Authorization required for XSR_REMOVE:

If a user is authorized to invoke the XSR_REMOVE procedure, that user can

remove any XML schema. Therefore, the execute privilege on the XSR_REMOVE

procedure should be granted carefully.

XSR_REMOVE syntax diagram:


XSR_REMOVE.

XSR_REMOVE option descriptions:

rschema

An input argument of type VARCHAR (128) that specifies the SQL schema for


name

An input argument of type VARCHAR (128) that specifies the name of the

XML schema. The complete SQL identifier for the XML schema, for which a

completion check is to be performed, is ″rschema.name″. The XML schema

name must already exist as a result of calling the XSR_REGISTER stored

procedure, and XML schema registration cannot yet be completed. This

argument cannot have a NULL value. Rules for valid characters and delimiters

that apply to any SQL identifier also apply to this argument.

Example of XSR_REMOVE:

The following example calls the XSR_REMOVE stored procedure:

CALL SYSPROC.XSR_REMOVE(

’SYSXSR’,

’POschema’)

�� SYSPROC

CALL

.

XSR_REMOVE

(

rschema

,

NULL

name

)

��


|||||||||||||||||||||||||||||||

|||

|

|

|||||

||

|||

|

|

|

|||

|

|||

|

|||

||||||||

|

|

|||

The XML decomposition stored procedure (XDBDECOMPXML)

The XDBDECOMPXML procedure extracts values from serialized XML data and

populates relational tables with the values. The stored procedure uses an XML

schema, which contains annotations that indicate which columns and tables should

be used to store the decomposed XML values. The referenced XML schema must

exist in the XSR and must be enabled for decomposition. You can enable an XML

schema for decomposition by using the XSR_COMPLETE stored procedure. If your

XML schema references tables that did not exist when you invoked the

XSR_COMPLETE stored procedure, DB2 will return an error.

Environment for XDBDECOMPXML:

XDBDECOMPXML runs in a WLM-established stored procedures address space.

Authorization required for XDBDECOMPXML:

To invoke the XDBDECOMPXML stored procedure, you must have:

v The EXECUTE privilege on XDBDECOMPXML

v The INSERT privilege on tables that are specified in the annotations

XDBDECOMPXML syntax diagram:


XDBDECOMPXML.

XDBDECOMPXML option descriptions:

rschema



name


schema. The complete SQL identifier for the XML schema, for which

decomposition is to be performed, is "rschema.name". The XML schema name

must already exist and be enabled for decomposition as a result of calling the

XSR_COMPLETE stored procedure. This argument cannot have a NULL value.

Rules for valid characters and delimiters that apply to any SQL identifier also

apply to this argument.

xmldoc

An input parameter of type CLOB AS LOCATOR that points to the XML value

that is to be decomposed. This parameter cannot be null.

documentid

An input parameter of type VARCHAR(1024) that contains a string that the

caller can use to identify the input XML document. This parameter can be null.

�� SYSPROC

CALL

.

XDBDECOMPXML

(

rschema

,

NULL

name

,

xmldoc

,

documentid

)

NULL

��


|||||||||||||||||||||||||||||||||||||||||||||

|||

||

||||||||

|

|

|

|||

|

|||

|

|||

||||||||

|||

|||


Appendix K. How to use the DB2 library

Titles of books in the library begin with DB2 Version 9.1 for z/OS. However,

references from one book in the library to another are shortened and do not

include the product name, version, and release. Instead, they point directly to the

section that holds the information. For a complete list of books in the library, and

the sections in each book, see the bibliography at the back of this book.

If you are new to DB2 for z/OS, Introduction to DB2 for z/OS provides a

comprehensive introduction to DB2 Version 9.1 for z/OS. Topics included in this

book explain the basic concepts that are associated with relational database

management systems in general, and with DB2 for z/OS in particular.

The most rewarding task associated with a database management system is asking

questions of it and getting answers, the task called end use. Other tasks are also

necessary—defining the parameters of the system, putting the data in place, and so

on. The tasks that are associated with DB2 are grouped into the following major

categories.

Installation: If you are involved with DB2 only to install the system, DB2

Installation Guide might be all you need.

If you will be using data sharing capabilities you also need DB2 Data Sharing:

Planning and Administration, which describes installation considerations for data

sharing.

End use: End users issue SQL statements to retrieve data. They can also insert,

update, or delete data, with SQL statements. They might need an introduction to

SQL, detailed instructions for using SPUFI, and an alphabetized reference to the

types of SQL statements. This information is found in this book, and DB2 SQL

Reference.

End users can also issue SQL statements through the DB2 Query Management

Facility (QMF™) or some other program, and the library for that licensed program

might provide all the instruction or reference material they need. For a list of the

titles in the DB2 QMF library, see the bibliography at the end of this book.

Application programming: Some users access DB2 without knowing it, using

programs that contain SQL statements. DB2 application programmers write those

programs. Because they write SQL statements, they need the same resources that

end users do.

Application programmers also need instructions for many other topics:

v How to transfer data between DB2 and a host program—written in Java, C, or

COBOL, for example

v How to prepare to compile a program that embeds SQL statements

v How to process data from two systems simultaneously, for example, DB2 and

IMS or DB2 and CICS

v How to write distributed applications across operating systems

v How to write applications that use Open Database Connectivity (ODBC) to

access DB2 servers


||||

v How to write applications that use JDBC and SQLJ with the Java programming

language to access DB2 servers

v How to write applications to store XML data on DB2 servers and retrieve XML

data from DB2 servers.

The material needed for writing a host program containing SQL is in DB2

Application Programming and SQL Guide.

The material needed for writing applications that use JDBC and SQLJ to access

DB2 servers is in DB2 Application Programming Guide and Reference for Java. The

material needed for writing applications that use DB2 CLI or ODBC to access DB2

servers is in DB2 ODBC Guide and Reference. The material needed for working with

XML data in DB2 is in DB2 XML Guide. For handling errors, see DB2 Messages and

DB2 Codes.

If you will be working in a distributed environment, you will need DB2 Reference

for Remote DRDA Requesters and Servers.

Information about writing applications across operating systems can be found in

IBM DB2 SQL Reference for Cross-Platform Development.

System and database administration: Administration covers almost everything else.

DB2 Administration Guide divides some of those tasks among the following

sections:

v Part 2 of DB2 Administration Guide discusses the decisions that must be made

when designing a database and tells how to implement the design by creating

and altering DB2 objects, loading data, and adjusting to changes.

v Part 3 of DB2 Administration Guide describes ways of controlling access to the

DB2 system and to data within DB2, to audit aspects of DB2 usage, and to

answer other security and auditing concerns.

v Part 4 of DB2 Administration Guide describes the steps in normal day-to-day

operation and discusses the steps one should take to prepare for recovery in the

event of some failure.

explains how to monitor the performance of the DB2 system and its parts. It also

lists things that can be done to make some parts run faster.

If you will be using the RACF access control module for DB2 authorization

checking, you will need DB2 RACF Access Control Module Guide.

If you are involved with DB2 only to design the database, or plan operational

procedures, you need DB2 Administration Guide. If you also want to carry out your

own plans by creating DB2 objects, granting privileges, running utility jobs, and so

on, you also need:

v DB2 SQL Reference, which describes the SQL statements you use to create, alter,

and drop objects and grant and revoke privileges

v DB2 Utility Guide and Reference, which explains how to run utilities

v DB2 Command Reference, which explains how to run commands

If you will be using data sharing, you need DB2 Data Sharing: Planning and

Administration, which describes how to plan for and implement data sharing.

Additional information about system and database administration can be found in

DB2 Messages and DB2 Codes, which list messages and codes issued by DB2, with

explanations and suggested responses.


||

||

||

Diagnosis: Diagnosticians detect and describe errors in the DB2 program. They

might also recommend or apply a remedy. The documentation for this task is in

DB2 Diagnosis Guide and Reference and DB2 Messages and DB2 Codes.

Appendix K. How to use the DB2 library 1285


Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in

other countries. Consult your local IBM representative for information on the

products and services currently available in your area. Any reference to an IBM

product, program, or service is not intended to state or imply that only that IBM

product, program, or service may be used. Any functionally equivalent product,

program, or service that does not infringe any IBM intellectual property right may

be used instead. However, it is the user’s responsibility to evaluate and verify the

operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter

described in this document. The furnishing of this document does not give you

any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785

U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM

Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other

country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER

EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS

FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or

implied warranties in certain transactions, therefore, this statement may not apply

to you.

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.

Any references in this information to non-IBM Web sites are provided for

convenience only and do not in any manner serve as an endorsement of those Web

sites. The materials at those Web sites are not part of the materials for this IBM

product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it

believes appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purpose

of enabling: (i) the exchange of information between independently created

programs and other programs (including this one) and (ii) the mutual use of the

information which has been exchanged, should contact:

IBM Corporation

J46A/G4

555 Bailey Avenue

San Jose, CA 95141-1003

U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material

available for it are provided by IBM under terms of the IBM Customer Agreement,

IBM International Program License Agreement, or any equivalent agreement

between us.

This information contains examples of data and reports used in daily business

operations. To illustrate them as completely as possible, the examples include the

names of individuals, companies, brands, and products. All of these names are

fictitious and any similarity to the names and addresses used by an actual business

enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,

modify, and distribute these sample programs in any form without payment to

IBM, for the purposes of developing, using, marketing or distributing application

programs conforming to the application programming interface for the operating

platform for which the sample programs are written. These examples have not

been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or

imply reliability, serviceability, or function of these programs.

Programming interface information

This information is intended to help you to write programs that contain SQL

statements. This book primarily documents General-use Programming Interface

and Associated Guidance Information provided by DB2 Version 9.1 for z/OS (DB2

V9.1 for z/OS). However, this book also documents Product-sensitive

Programming Interface and Associated Guidance Information.

General-use Programming Interfaces allow the customer to write programs that

obtain the services of DB2 for z/OS.

General-use Programming Interface and Associated Guidance Information is

identified where it occurs by one of two markings. The first marking is as follows:

General-use Programming Interface

General-use Programming Interface and Associated Guidance Information...

End of General-use Programming Interface


The alternative marking for General-use Programming Interface and Associated

Guidance Information is as follows:

General-use Programming Interface and Associated Guidance Information

Product-sensitive Programming Interfaces allow the customer installation to

perform tasks such as diagnosing, modifying, monitoring, repairing, tailoring, or

tuning of this IBM software product. Use of such interfaces creates dependencies

on the detailed design or implementation of the IBM software product.

Product-sensitive Programming Interfaces should be used only for these

specialized purposes. Because of their dependencies on detailed design and

implementation, it is to be expected that programs written to such interfaces may

need to be changed in order to run with new product releases or versions, or as a

result of service.

Product-sensitive Programming Interface and Associated Guidance Information is

identified where it occurs, either by an introductory statement to a chapter or

section or by the following marking:

Product-sensitive Programming Interface

Product-sensitive Programming Interface and Associated Guidance Information ...

End of Product-sensitive Programming Interface

Trademarks

Company, product, or service names identified in the DB2 Version 9.1 for z/OS

information may be trademarks or service marks of International Business

Machines Corporation or other companies. Information about the trademarks of

IBM Corporation in the United States, other countries, or both is located at

http://www.ibm.com/legal/copytrade.shtml.

The following terms are trademarks or registered trademarks of other companies,

and have been used at least once in the DB2 for z/OS library:

v Microsoft®, Windows, Windows NT, and the Windows logo are trademarks of

Microsoft Corporation in the United States, other countries, or both.

v Intel®, Intel logo, Intel Inside®, Intel Inside logo, Intel Centrino™, Intel Centrino

logo, Celeron®, Intel Xeon™, Intel SpeedStep®, Itanium®, and Pentium® are

trademarks or registered trademarks of Intel Corporation or its subsidiaries in

the United States and other countries.

v Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in

the United States, other countries, or both.

v UNIX is a registered trademark of The Open Group in the United States and

other countries.

v Linux is a registered trademark of Linus Torvalds in the United States, other

countries, or both.

Other company, product, or service names may be trademarks or service marks of

others.

Notices 1289


Glossary

abend See abnormal end of task.

abend reason code

A 4-byte hexadecimal code that uniquely identifies a problem with DB2.

abnormal end of task (abend)

Termination of a task, job, or subsystem because of an error condition that

recovery facilities cannot resolve during execution.

access method services

The facility that is used to define, alter, delete, print, and reproduce VSAM

key-sequenced data sets.

access path

The path that is used to locate data that is specified in SQL statements. An

access path can be indexed or sequential.

active log

The portion of the DB2 log to which log records are written as they are

generated. The active log always contains the most recent log records. See

also archive log.

address space

A range of virtual storage pages that is identified by a number (ASID) and

a collection of segment and page tables that map the virtual pages to real

pages of the computer’s memory.

address space connection

The result of connecting an allied address space to DB2. See also allied

address space and task control block.

address space identifier (ASID)

A unique system-assigned identifier for an address space.

AFTER trigger

A trigger that is specified to be activated after a defined trigger event (an

insert, update, or delete operation on the table that is specified in a trigger

definition). Contrast with BEFORE trigger and INSTEAD OF trigger.

agent In DB2, the structure that associates all processes that are involved in a

DB2 unit of work. See also allied agent and system agent.

aggregate function

An operation that derives its result by using values from one or more

rows. Contrast with scalar function.

alias An alternative name that can be used in SQL statements to refer to a table

or view in the same or a remote DB2 subsystem. An alias can be qualified

with a schema qualifier and can thereby be referenced by other users.

Contrast with synonym.

allied address space

An area of storage that is external to DB2 and that is connected to DB2. An

allied address space can request DB2 services. See also address space.

allied agent

An agent that represents work requests that originate in allied address

spaces. See also system agent.


||

|||

||||

||||

allied thread

A thread that originates at the local DB2 subsystem and that can access

data at a remote DB2 subsystem.

allocated cursor

A cursor that is defined for a stored procedure result set by using the SQL

ALLOCATE CURSOR statement.

ambiguous cursor

A database cursor for which DB2 cannot determine whether it is used for

update or read-only purposes.

APAR See authorized program analysis report.

APF See authorized program facility.

API See application programming interface.

APPL A VTAM network definition statement that is used to define DB2 to VTAM

as an application program that uses SNA LU 6.2 protocols.

application

A program or set of programs that performs a task; for example, a payroll

application.

application plan

The control structure that is produced during the bind process. DB2 uses

the application plan to process SQL statements that it encounters during

statement execution.

application process

The unit to which resources and locks are allocated. An application process

involves the execution of one or more programs.

application programming interface (API)

A functional interface that is supplied by the operating system or by a

separately orderable licensed program that allows an application program

that is written in a high-level language to use specific data or functions of

the operating system or licensed program.

application requester

The component on a remote system that generates DRDA requests for data

on behalf of an application.

application server

The target of a request from a remote application. In the DB2 environment,

the application server function is provided by the distributed data facility

and is used to access DB2 data from remote applications.

archive log

The portion of the DB2 log that contains log records that have been copied

from the active log. See also active log.

ASCII An encoding scheme that is used to represent strings in many

environments, typically on PCs and workstations. Contrast with EBCDIC

and Unicode.

ASID See address space identifier.

attachment facility

An interface between DB2 and TSO, IMS, CICS, or batch address spaces.

An attachment facility allows application programs to access DB2.


attribute

A characteristic of an entity. For example, in database design, the phone

number of an employee is an attribute of that employee.

authorization ID

A string that can be verified for connection to DB2 and to which a set of

privileges is allowed. An authorization ID can represent an individual or

an organizational group.

authorized program analysis report (APAR)

A report of a problem that is caused by a suspected defect in a current

release of an IBM supplied program.

authorized program facility (APF)

A facility that allows an installation to identify system or user programs

that can use sensitive system functions.

automatic bind

(More correctly automatic rebind.) A process by which SQL statements are

bound automatically (without a user issuing a BIND command) when an

application process begins execution and the bound application plan or

package it requires is not valid.

automatic query rewrite

A process that examines an SQL statement that refers to one or more base

tables or materialized query tables, and, if appropriate, rewrites the query

so that it performs better.

auxiliary index

An index on an auxiliary table in which each index entry refers to a LOB

or XML document.

auxiliary table

A table that contains columns outside the actual table in which they are

defined. Auxiliary tables can contain either LOB or XML data.

backout

The process of undoing uncommitted changes that an application process

made. A backout is often performed in the event of a failure on the part of

an application process, or as a result of a deadlock situation.

backward log recovery

The final phase of restart processing during which DB2 scans the log in a

backward direction to apply UNDO log records for all aborted changes.

base table

A table that is created by the SQL CREATE TABLE statement and that

holds persistent data. Contrast with clone table, materialized query table,

result table, temporary table, and transition table.

base table space

A table space that contains base tables.

basic row format

A row format in which values for columns are stored in the row in the

order in which the columns are defined by the CREATE TABLE statement.

Contrast with reordered row format.

basic sequential access method (BSAM)

An access method for storing or retrieving data blocks in a continuous

sequence, using either a sequential-access or a direct-access device.

Glossary 1293

|||

||

||

||||

BEFORE trigger

A trigger that is specified to be activated before a defined trigger event (an

insert, an update, or a delete operation on the table that is specified in a

trigger definition). Contrast with AFTER trigger and INSTEAD OF trigger.

binary large object (BLOB)

A binary string data type that contains a sequence of bytes that can range

in size from 0 bytes to 2 GB, less 1 byte. This string does not have an

associated code page and character set. BLOBs can contain, for example,

image, audio, or video data. In general, BLOB values are used whenever a

binary string might exceed the limits of the VARBINARY type.

binary string

A sequence of bytes that is not associated with a CCSID. Binary string data

type can be further classified as BINARY, VARBINARY, or BLOB.

bind A process by which a usable control structure with SQL statements is

generated; the structure is often called an access plan, an application plan,

or a package. During this bind process, access paths to the data are

selected, and some authorization checking is performed. See also automatic

bind.

bit data

v Data with character type CHAR or VARCHAR that is defined with the

FOR BIT DATA clause. Note that using BINARY or VARBINARY rather

than FOR BIT DATA is highly recommended.

v Data with character type CHAR or VARCHAR that is defined with the

FOR BIT DATA clause.

v A form of character data. Binary data is generally more highly

recommended than character-for-bit data.

BLOB See binary large object.

block fetch

A capability in which DB2 can retrieve, or fetch, a large set of rows

together. Using block fetch can significantly reduce the number of

messages that are being sent across the network. Block fetch applies only

to non-rowset cursors that do not update data.

bootstrap data set (BSDS)

A VSAM data set that contains name and status information for DB2 and

RBA range specifications for all active and archive log data sets. The BSDS

also contains passwords for the DB2 directory and catalog, and lists of

conditional restart and checkpoint records.

BSAM

See basic sequential access method.

BSDS See bootstrap data set.

buffer pool

An area of memory into which data pages are read, modified, and held

during processing.

built-in data type

A data type that IBM supplies. Among the built-in data types for DB2 for

z/OS are string, numeric, XML, ROWID, and datetime. Contrast with

distinct type.

built-in function

A function that is generated by DB2 and that is in the SYSIBM schema.


||||

|||||

||

|||||

|||

||

||

||||

||

|||

|

Contrast with user-defined function. See also function, cast function,

external function, sourced function, and SQL function.

business dimension

A category of data, such as products or time periods, that an organization

might want to analyze.

cache structure

A coupling facility structure that stores data that can be available to all

members of a Sysplex. A DB2 data sharing group uses cache structures as

group buffer pools.

CAF See call attachment facility.

call attachment facility (CAF)

A DB2 attachment facility for application programs that run in TSO or

z/OS batch. The CAF is an alternative to the DSN command processor and

provides greater control over the execution environment. Contrast with

Recoverable Resource Manager Services attachment facility.

call-level interface (CLI)

A callable application programming interface (API) for database access,

which is an alternative to using embedded SQL.

cascade delete

A process by which DB2 enforces referential constraints by deleting all

descendent rows of a deleted parent row.

CASE expression

An expression that is selected based on the evaluation of one or more

conditions.

cast function

A function that is used to convert instances of a (source) data type into

instances of a different (target) data type.

castout

The DB2 process of writing changed pages from a group buffer pool to

disk.

castout owner

The DB2 member that is responsible for casting out a particular page set or

partition.

catalog

In DB2, a collection of tables that contains descriptions of objects such as

tables, views, and indexes.

catalog table

Any table in the DB2 catalog.

CCSID

See coded character set identifier.

CDB See communications database.

CDRA

See Character Data Representation Architecture.

CEC See central processor complex.

central electronic complex (CEC)

See central processor complex.

Glossary 1295

||

central processor complex (CPC)

A physical collection of hardware that consists of main storage, one or

more central processors, timers, and channels.

central processor (CP)

The part of the computer that contains the sequencing and processing

facilities for instruction execution, initial program load, and other machine

operations.

CFRM See coupling facility resource management.

CFRM policy

The allocation rules for a coupling facility structure that are declared by a

z/OS administrator.

character conversion

The process of changing characters from one encoding scheme to another.

Character Data Representation Architecture (CDRA)

An architecture that is used to achieve consistent representation,

processing, and interchange of string data.

character large object (CLOB)

A character string data type that contains a sequence of bytes that

represent characters (single-byte, multibyte, or both) that can range in size

from 0 bytes to 2 GB, less 1 byte. In general, CLOB values are used

whenever a character string might exceed the limits of the VARCHAR

type.

character set

A defined set of characters.

character string

A sequence of bytes that represent bit data, single-byte characters, or a

mixture of single-byte and multibyte characters. Character data can be

further classified as CHARACTER, VARCHAR, or CLOB.

check constraint

A user-defined constraint that specifies the values that specific columns of

a base table can contain.

check integrity

The condition that exists when each row in a table conforms to the check

constraints that are defined on that table.

check pending

A state of a table space or partition that prevents its use by some utilities

and by some SQL statements because of rows that violate referential

constraints, check constraints, or both.

checkpoint

A point at which DB2 records status information on the DB2 log; the

recovery process uses this information if DB2 abnormally terminates.

child lock

For explicit hierarchical locking, a lock that is held on either a table, page,

row, or a large object (LOB). Each child lock has a parent lock. See also

parent lock.

CI See control interval.

CICS Represents (in this information): CICS Transaction Server for z/OS:

Customer Information Control System Transaction Server for z/OS.


|||||

|||

CICS attachment facility

A facility that provides a multithread connection to DB2 to allow

applications that run in the CICS environment to execute DB2 statements.

claim A notification to DB2 that an object is being accessed. Claims prevent

drains from occurring until the claim is released, which usually occurs at a

commit point. Contrast with drain.

claim class

A specific type of object access that can be one of the following isolation

levels:

v Cursor stability (CS)

v Repeatable read (RR)

v Write

class of service

A VTAM term for a list of routes through a network, arranged in an order

of preference for their use.

clause In SQL, a distinct part of a statement, such as a SELECT clause or a

WHERE clause.

CLI See call-level interface.

client See requester.

CLOB See character large object.

clone object

An object that is associated with a clone table, including the clone table

itself and check constraints, indexes, and BEFORE triggers on the clone

table.

clone table

A table that is structurally identical to a base table. The base and clone

table each have separate underlying VSAM data sets, which are identified

by their data set instance numbers. Contrast with base table.

closed application

An application that requires exclusive use of certain statements on certain

DB2 objects, so that the objects are managed solely through the external

interface of that application.

clustering index

An index that determines how rows are physically ordered (clustered) in a

table space. If a clustering index on a partitioned table is not a partitioning

index, the rows are ordered in cluster sequence within each data partition

instead of spanning partitions.

CM* See compatibility mode*.

CM See compatibility mode.

C++ member

A data object or function in a structure, union, or class.

C++ member function

An operator or function that is declared as a member of a class. A member

function has access to the private and protected data members and to the

member functions of objects in its class. Member functions are also called

methods.

Glossary 1297

||

||||

||||

|

|

C++ object

A region of storage. An object is created when a variable is defined or a

new function is invoked.

An instance of a class.

coded character set

A set of unambiguous rules that establish a character set and the

one-to-one relationships between the characters of the set and their coded

representations.

coded character set identifier (CCSID)

A 16-bit number that uniquely identifies a coded representation of graphic

characters. It designates an encoding scheme identifier and one or more

pairs that consist of a character set identifier and an associated code page

identifier.

code page

A set of assignments of characters to code points. Within a code page, each

code point has only one specific meaning. In EBCDIC, for example, the

character A is assigned code point X’C1’, and character B is assigned code

point X’C2’.

code point

In CDRA, a unique bit pattern that represents a character in a code page.

code unit

The fundamental binary width in a computer architecture that is used for

representing character data, such as 7 bits, 8 bits, 16 bits, or 32 bits.

Depending on the character encoding form that is used, each code point in

a coded character set can be represented by one or more code units.

coexistence

During migration, the period of time in which two releases exist in the

same data sharing group.

cold start

A process by which DB2 restarts without processing any log records.

Contrast with warm start.

collection

A group of packages that have the same qualifier.

column

The vertical component of a table. A column has a name and a particular

data type (for example, character, decimal, or integer).

column function

See aggregate function.

″come from″ checking

An LU 6.2 security option that defines a list of authorization IDs that are

allowed to connect to DB2 from a partner LU.

command

A DB2 operator command or a DSN subcommand. A command is distinct

from an SQL statement.

command prefix

A 1- to 8-character command identifier. The command prefix distinguishes

the command as belonging to an application or subsystem rather than to

z/OS.


command recognition character (CRC)

A character that permits a z/OS console operator or an IMS subsystem

user to route DB2 commands to specific DB2 subsystems.

command scope

The scope of command operation in a data sharing group.

commit

The operation that ends a unit of work by releasing locks so that the

database changes that are made by that unit of work can be perceived by

other processes. Contrast with rollback.

commit point

A point in time when data is considered consistent.

common service area (CSA)

In z/OS, a part of the common area that contains data areas that are

addressable by all address spaces. Most DB2 use is in the extended CSA,

which is above the 16-MB line.

communications database (CDB)

A set of tables in the DB2 catalog that are used to establish conversations

with remote database management systems.

comparison operator

A token (such as =, >, or <) that is used to specify a relationship between

two values.

compatibility mode* (CM*)

A stage of the version-to-version migration process that applies to a DB2

subsystem or data sharing group that was in enabling-new-function mode

(ENFM), enabling-new-function mode* (ENFM*), or new-function mode

(NFM) at one time. Fallback to a prior version is not supported. When in

compatibility mode*, a DB2 data sharing group cannot coexist with

members that are still at the prior version level. Contrast with

compatibility mode, enabling-new-function mode, enabling-new-function

mode*, and new-function mode.

compatibility mode (CM)

The first stage of the version-to-version migration process. In a DB2 data

sharing group, members in compatibility mode can coexist with members

that are still at the prior version level. Fallback to the prior version is also

supported. When in compatibility mode, the DB2 subsystem cannot use

any new functions of the new version. Contrast with compatibility mode*,

enabling-new-function mode, enabling-new-function mode*, and

new-function mode.

composite key

An ordered set of key columns or expressions of the same table.

compression dictionary

The dictionary that controls the process of compression and

decompression. This dictionary is created from the data in the table space

or table space partition.

concurrency

The shared use of resources by more than one application process at the

same time.

conditional restart

A DB2 restart that is directed by a user-defined conditional restart control

record (CRCR).

Glossary 1299

|||

|||||||||

||||||||

|

connection

In SNA, the existence of a communication path between two partner LUs

that allows information to be exchanged (for example, two DB2 subsystems

that are connected and communicating by way of a conversation).

connection context

In SQLJ, a Java object that represents a connection to a data source.

connection declaration clause

In SQLJ, a statement that declares a connection to a data source.

connection handle

The data object containing information that is associated with a connection

that DB2 ODBC manages. This includes general status information,

transaction status, and diagnostic information.

connection ID

An identifier that is supplied by the attachment facility and that is

associated with a specific address space connection.

consistency token

A timestamp that is used to generate the version identifier for an

application. See also version.

constant

A language element that specifies an unchanging value. Constants are

classified as string constants or numeric constants. Contrast with variable.

constraint

A rule that limits the values that can be inserted, deleted, or updated in a

table. See referential constraint, check constraint, and unique constraint.

context

An application’s logical connection to the data source and associated DB2

ODBC connection information that allows the application to direct its

operations to a data source. A DB2 ODBC context represents a DB2 thread.

contracting conversion

A process that occurs when the length of a converted string is smaller than

that of the source string. For example, this process occurs when an

EBCDIC mixed-data string that contains DBCS characters is converted to

ASCII mixed data; the converted string is shorter because the shift codes

are removed.

control interval (CI)

v A unit of information that VSAM transfers between virtual and auxiliary

storage.

v In a key-sequenced data set or file, the set of records that an entry in the

sequence-set index record points to.

conversation

Communication, which is based on LU 6.2 or Advanced

Program-to-Program Communication (APPC), between an application and

a remote transaction program over an SNA logical unit-to-logical unit

(LU-LU) session that allows communication while processing a transaction.

coordinator

The system component that coordinates the commit or rollback of a unit of

work that includes work that is done on one or more other systems.

coprocessor

See SQL statement coprocessor.


copy pool

A collection of names of storage groups that are processed collectively for

fast replication operations.

copy target

A named set of SMS storage groups that are to be used as containers for

copy pool volume copies. A copy target is an SMS construct that lets you

define which storage groups are to be used as containers for volumes that

are copied by using FlashCopy functions.

copy version

A point-in-time FlashCopy copy that is managed by HSM. Each copy pool

has a version parameter that specifies the number of copy versions to be

maintained on disk.

correlated columns

A relationship between the value of one column and the value of another

column.

correlated subquery

A subquery (part of a WHERE or HAVING clause) that is applied to a row

or group of rows of a table or view that is named in an outer subselect

statement.

correlation ID

An identifier that is associated with a specific thread. In TSO, it is either an

authorization ID or the job name.

correlation name

An identifier that is specified and used within a single SQL statement as

the exposed name for objects such as a table, view, table function reference,

nested table expression, or result of a data change statement. Correlation

names are useful in an SQL statement to allow two distinct references to

the same base table and to allow an alternative name to be used to

represent an object.

cost category

A category into which DB2 places cost estimates for SQL statements at the

time the statement is bound. The cost category is externalized in the

COST_CATEGORY column of the DSN_STATEMNT_TABLE when a

statement is explained.

coupling facility

A special PR/SM logical partition (LPAR) that runs the coupling facility

control program and provides high-speed caching, list processing, and

locking functions in a Parallel Sysplex.

coupling facility resource management (CFRM)

A component of z/OS that provides the services to manage coupling

facility resources in a Parallel Sysplex. This management includes the

enforcement of CFRM policies to ensure that the coupling facility and

structure requirements are satisfied.

CP See central processor.

CPC See central processor complex.

CRC See command recognition character.

created temporary table

A persistent table that holds temporary data and is defined with the SQL

statement CREATE GLOBAL TEMPORARY TABLE. Information about

Glossary 1301

||

||||||

|||

created temporary tables is stored in the DB2 catalog and can be shared

across application processes. Contrast with declared temporary table. See

also temporary table.

cross-system coupling facility (XCF)

A component of z/OS that provides functions to support cooperation

between authorized programs that run within a Sysplex.

cross-system extended services (XES)

A set of z/OS services that allow multiple instances of an application or

subsystem, running on different systems in a Sysplex environment, to

implement high-performance, high-availability data sharing by using a

coupling facility.

CS See cursor stability.

CSA See common service area.

CT See cursor table.

current data

Data within a host structure that is current with (identical to) the data

within the base table.

current status rebuild

The second phase of restart processing during which the status of the

subsystem is reconstructed from information on the log.

cursor A control structure that an application program uses to point to a single

row or multiple rows within some ordered set of rows of a result table. A

cursor can be used to retrieve, update, or delete rows from a result table.

cursor sensitivity

The degree to which database updates are visible to the subsequent

FETCH statements in a cursor.

cursor stability (CS)

The isolation level that provides maximum concurrency without the ability

to read uncommitted data. With cursor stability, a unit of work holds locks

only on its uncommitted changes and on the current row of each of its

cursors. See also read stability, repeatable read, and uncommitted read.

cursor table (CT)

The internal representation of a cursor.

cycle A set of tables that can be ordered so that each table is a descendent of the

one before it, and the first table is a descendent of the last table. A

self-referencing table is a cycle with a single member. See also referential

cycle.

database

A collection of tables, or a collection of table spaces and index spaces.

database access thread (DBAT)

A thread that accesses data at the local subsystem on behalf of a remote

subsystem.

database administrator (DBA)

An individual who is responsible for designing, developing, operating,

safeguarding, maintaining, and using a database.


|

database alias

The name of the target server if it is different from the location name. The

database alias is used to provide the name of the database server as it is

known to the network.

database descriptor (DBD)

An internal representation of a DB2 database definition, which reflects the

data definition that is in the DB2 catalog. The objects that are defined in a

database descriptor are table spaces, tables, indexes, index spaces,

relationships, check constraints, and triggers. A DBD also contains

information about accessing tables in the database.

database exception status

In a data sharing environment, an indication that something is wrong with

a database.

database identifier (DBID)

An internal identifier of the database.

database management system (DBMS)

A software system that controls the creation, organization, and

modification of a database and the access to the data that is stored within

it.

database request module (DBRM)

A data set member that is created by the DB2 precompiler and that

contains information about SQL statements. DBRMs are used in the bind

process.

database server

The target of a request from a local application or a remote intermediate

database server.

data currency

The state in which the data that is retrieved into a host variable in a

program is a copy of the data in the base table.

data dictionary

A repository of information about an organization’s application programs,

databases, logical data models, users, and authorizations.

data partition

A VSAM data set that is contained within a partitioned table space.

data-partitioned secondary index (DPSI)

A secondary index that is partitioned according to the underlying data.

Contrast with nonpartitioned secondary index.

data set instance number

A number that indicates the data set that contains the data for an object.

data sharing

A function of DB2 for z/OS that enables applications on different DB2

subsystems to read from and write to the same data concurrently.

data sharing group

A collection of one or more DB2 subsystems that directly access and

change the same data while maintaining data integrity.

data sharing member

A DB2 subsystem that is assigned by XCF services to a data sharing group.

Glossary 1303

||

data source

A local or remote relational or non-relational data manager that is capable

of supporting data access via an ODBC driver that supports the ODBC

APIs. In the case of DB2 for z/OS, the data sources are always relational

database managers.

data type

An attribute of columns, constants, variables, parameters, special registers,

and the results of functions and expressions.

data warehouse

A system that provides critical business information to an organization.

The data warehouse system cleanses the data for accuracy and currency,

and then presents the data to decision makers so that they can interpret

and use it effectively and efficiently.

DBA See database administrator.

DBAT See database access thread.

DB2 catalog

A collection of tables that are maintained by DB2 and contain descriptions

of DB2 objects, such as tables, views, and indexes.

DBCLOB

See double-byte character large object.

DB2 command

An instruction to the DB2 subsystem that a user enters to start or stop

DB2, to display information on current users, to start or stop databases, to

display information on the status of databases, and so on.

DBCS See double-byte character set.

DBD See database descriptor.

DB2I See DB2 Interactive.

DBID See database identifier.

DB2 Interactive (DB2I)

An interactive service within DB2 that facilitates the execution of SQL

statements, DB2 (operator) commands, and programmer commands, and

the invocation of utilities.

DBMS

See database management system.

DBRM

See database request module.

DB2 thread

The database manager structure that describes an application’s connection,

traces its progress, processes resource functions, and delimits its

accessibility to the database manager resources and services. Most DB2 for

z/OS functions execute under a thread structure.

DCLGEN

See declarations generator.

DDF See distributed data facility.

deadlock

Unresolvable contention for the use of a resource, such as a table or an

index.


||||

declarations generator (DCLGEN)

A subcomponent of DB2 that generates SQL table declarations and

COBOL, C, or PL/I data structure declarations that conform to the table.

The declarations are generated from DB2 system catalog information.

declared temporary table

A non-persistent table that holds temporary data and is defined with the

SQL statement DECLARE GLOBAL TEMPORARY TABLE. Information

about declared temporary tables is not stored in the DB2 catalog and can

be used only by the application process that issued the DECLARE

statement. Contrast with created temporary table. See also temporary table.

default value

A predetermined value, attribute, or option that is assumed when no other

value is specified. A default value can be defined for column data in DB2

tables by specifying the DEFAULT keyword in an SQL statement that

changes data (such as INSERT, UPDATE, and MERGE).

deferred embedded SQL

SQL statements that are neither fully static nor fully dynamic. These

statements are embedded within an application and are prepared during

the execution of the application.

deferred write

The process of asynchronously writing changed data pages to disk.

degree of parallelism

The number of concurrently executed operations that are initiated to

process a query.

delete hole

The location on which a cursor is positioned when a row in a result table

is refetched and the row no longer exists on the base table. See also update

hole.

delete rule

The rule that tells DB2 what to do to a dependent row when a parent row

is deleted. Delete rules include CASCADE, RESTRICT, SET NULL, or NO

ACTION.

delete trigger

A trigger that is defined with the triggering delete SQL operation.

delimited identifier

A sequence of characters that are enclosed within escape characters such as

double quotation marks (″).

delimiter token

A string constant, a delimited identifier, an operator symbol, or any of the

special characters that are shown in DB2 syntax diagrams.

denormalization

The intentional duplication of columns in multiple tables to increase data

redundancy. Denormalization is sometimes necessary to minimize

performance problems. Contrast with normalization.

dependent

An object (row, table, or table space) that has at least one parent. The object

is also said to be a dependent (row, table, or table space) of its parent. See

also parent row, parent table, and parent table space.

Glossary 1305

||||

dependent row

A row that contains a foreign key that matches the value of a primary key

in the parent row.

dependent table

A table that is a dependent in at least one referential constraint.

descendent

An object that is a dependent of an object or is the dependent of a

descendent of an object.

descendent row

A row that is dependent on another row, or a row that is a descendent of a

dependent row.

descendent table

A table that is a dependent of another table, or a table that is a descendent

of a dependent table.

deterministic function

A user-defined function whose result is dependent on the values of the

input arguments. That is, successive invocations with the same input

values produce the same answer. Sometimes referred to as a not-variant

function. Contrast with nondeterministic function (sometimes called a

variant function).

dimension

A data category such as time, products, or markets. The elements of a

dimension are referred to as members. See also dimension table.

dimension table

The representation of a dimension in a star schema. Each row in a

dimension table represents all of the attributes for a particular member of

the dimension. See also dimension, star schema, and star join.

directory

The DB2 system database that contains internal objects such as database

descriptors and skeleton cursor tables.

disk A direct-access storage device that records data magnetically.

distinct type

A user-defined data type that is represented as an existing type (its source

type), but is considered to be a separate and incompatible type for

semantic purposes.

distributed data

Data that resides on a DBMS other than the local system.

distributed data facility (DDF)

A set of DB2 components through which DB2 communicates with another

relational database management system.

Distributed Relational Database Architecture (DRDA)

A connection protocol for distributed relational database processing that is

used by IBM relational database products. DRDA includes protocols for

communication between an application and a remote relational database

management system, and for communication between relational database

management systems. See also DRDA access.

DNS See domain name server.


DOCID

See document ID.

document ID

A value that uniquely identifies a row that contains an XML column. This

value is stored with the row and never changes.

domain

The set of valid values for an attribute.

domain name

The name by which TCP/IP applications refer to a TCP/IP host within a

TCP/IP network.

domain name server (DNS)

A special TCP/IP network server that manages a distributed directory that

is used to map TCP/IP host names to IP addresses.

double-byte character large object (DBCLOB)

A graphic string data type in which a sequence of bytes represent

double-byte characters that range in size from 0 bytes to 2 GB, less 1 byte.

In general, DBCLOB values are used whenever a double-byte character

string might exceed the limits of the VARGRAPHIC type.

double-byte character set (DBCS)

A set of characters, which are used by national languages such as Japanese

and Chinese, that have more symbols than can be represented by a single

byte. Each character is 2 bytes in length. Contrast with single-byte

character set and multibyte character set.

double-precision floating point number

A 64-bit approximate representation of a real number.

DPSI See data-partitioned secondary index.

drain The act of acquiring a locked resource by quiescing access to that object.

Contrast with claim.

drain lock

A lock on a claim class that prevents a claim from occurring.

DRDA

See Distributed Relational Database Architecture.

DRDA access

An open method of accessing distributed data that you can use to connect

to another database server to execute packages that were previously bound

at the server location.

DSN

v The default DB2 subsystem name.

v The name of the TSO command processor of DB2.

v The first three characters of DB2 module and macro names.

dynamic cursor

A named control structure that an application program uses to change the

size of the result table and the order of its rows after the cursor is opened.

Contrast with static cursor.

dynamic dump

A dump that is issued during the execution of a program, usually under

the control of that program.

Glossary 1307

||

|||

||||

dynamic SQL

SQL statements that are prepared and executed at run time. In dynamic

SQL, the SQL statement is contained as a character string in a host variable

or as a constant, and it is not precompiled.

EA-enabled table space

A table space or index space that is enabled for extended addressability

and that contains individual partitions (or pieces, for LOB table spaces)

that are greater than 4 GB.

EB See exabyte.

EBCDIC

Extended binary coded decimal interchange code. An encoding scheme

that is used to represent character data in the z/OS, VM, VSE, and iSeries

environments. Contrast with ASCII and Unicode.

embedded SQL

SQL statements that are coded within an application program. See static

SQL.

enabling-new-function mode (ENFM)

A transitional stage of the version-to-version migration process during

which the DB2 subsystem or data sharing group is preparing to use the

new functions of the new version. When in enabling-new-function mode, a

DB2 data sharing group cannot coexist with members that are still at the

prior version level. Fallback to a prior version is not supported, and new

functions of the new version are not available for use in

enabling-new-function mode. Contrast with compatibility mode,

compatibility mode*, enabling-new-function mode*, and new-function

mode.

enabling-new-function mode* (ENFM*)

A transitional stage of the version-to-version migration process that applies

to a DB2 subsystem or data sharing group that was in new-function mode

(NFM) at one time. When in enabling-new-function mode*, a DB2

subsystem or data sharing group is preparing to use the new functions of

the new version but cannot yet use them. A data sharing group that is in

enabling-new-function mode* cannot coexist with members that are still at

the prior version level. Fallback to a prior version is not supported.

Contrast with compatibility mode, compatibility mode*,

enabling-new-function mode, and new-function mode.

enclave

In Language Environment , an independent collection of routines, one of

which is designated as the main routine. An enclave is similar to a

program or run unit. See also WLM enclave.

encoding scheme

A set of rules to represent character data (ASCII, EBCDIC, or Unicode).

ENFM See enabling-new-function mode.

ENFM*

See enabling-new-function mode*.

entity A person, object, or concept about which information is stored. In a

relational database, entities are represented as tables. A database includes

information about the entities in an organization or business, and their

relationships to each other.


|||

||||||||||

||||||||||

|

|

||||

enumerated list

A set of DB2 objects that are defined with a LISTDEF utility control

statement in which pattern-matching characters (*, %;, _, or ?) are not used.

environment

A collection of names of logical and physical resources that are used to

support the performance of a function.

environment handle

A handle that identifies the global context for database access. All data that

is pertinent to all objects in the environment is associated with this handle.

equijoin

A join operation in which the join-condition has the form expression =

expression. See also join, full outer join, inner join, left outer join, outer join,

and right outer join.

error page range

A range of pages that are considered to be physically damaged. DB2 does

not allow users to access any pages that fall within this range.

escape character

The symbol, a double quotation (″) for example, that is used to enclose an

SQL delimited identifier.

exabyte

A unit of measure for processor, real and virtual storage capacities, and

channel volume that has a value of 1 152 921 504 606 846 976 bytes or 260.

exception

An SQL operation that involves the EXCEPT set operator, which combines

two result tables. The result of an exception operation consists of all of the

rows that are in only one of the result tables.

exception table

A table that holds rows that violate referential constraints or check

constraints that the CHECK DATA utility finds.

exclusive lock

A lock that prevents concurrently executing application processes from

reading or changing data. Contrast with share lock.

executable statement

An SQL statement that can be embedded in an application program,

dynamically prepared and executed, or issued interactively.

execution context

In SQLJ, a Java object that can be used to control the execution of SQL

statements.

exit routine

A user-written (or IBM-provided default) program that receives control

from DB2 to perform specific functions. Exit routines run as extensions of

DB2.

expanding conversion

A process that occurs when the length of a converted string is greater than

that of the source string. For example, this process occurs when an ASCII

mixed-data string that contains DBCS characters is converted to an

EBCDIC mixed-data string; the converted string is longer because shift

codes are added.

Glossary 1309

||

|||

explicit hierarchical locking

Locking that is used to make the parent-child relationship between

resources known to IRLM. This kind of locking avoids global locking

overhead when no inter-DB2 interest exists on a resource.

explicit privilege

A privilege that has a name and is held as the result of an SQL GRANT

statement and revoked as the result of an SQL REVOKE statement. For

example, the SELECT privilege.

exposed name

A correlation name or a table or view name for which a correlation name is

not specified.

expression

An operand or a collection of operators and operands that yields a single

value.

Extended Recovery Facility (XRF)

A facility that minimizes the effect of failures in z/OS, VTAM, the host

processor, or high-availability applications during sessions between

high-availability applications and designated terminals. This facility

provides an alternative subsystem to take over sessions from the failing

subsystem.

Extensible Markup Language (XML)

A standard metalanguage for defining markup languages that is a subset

of Standardized General Markup Language (SGML).

external function

A function that has its functional logic implemented in a programming

language application that resides outside the database, in the file system of

the database server. The association of the function with the external code

application is specified by the EXTERNAL clause in the CREATE

FUNCTION statement. External functions can be classified as external

scalar functions and external table functions. Contrast with sourced

function, built-in function, and SQL function.

external procedure

A procedure that has its procedural logic implemented in an external

programming language application. The association of the procedure with

the external application is specified by a CREATE PROCEDURE statement

with a LANGUAGE clause that has a value other than SQL and an

EXTERNAL clause that implicitly or explicitly specifies the name of the

external application. Contrast with external SQL procedure and native SQL

procedure.

external routine

A user-defined function or stored procedure that is based on code that is

written in an external programming language.

external SQL procedure

An SQL procedure that is processed using a generated C program that is a

representation of the procedure. When an external SQL procedure is called,

the C program representation of the procedure is executed in a stored

procedures address space. Contrast with external procedure and native

SQL procedure.


|||

|||||||

|||||||

||||||

failed member state

A state of a member of a data sharing group in which the member’s task,

address space, or z/OS system terminates before the state changes from

active to quiesced.

fallback

The process of returning to a previous release of DB2 after attempting or

completing migration to a current release. Fallback is supported only from

a subsystem that is in compatibility mode.

false global lock contention

A contention indication from the coupling facility that occurs when

multiple lock names are hashed to the same indicator and when no real

contention exists.

fan set

A direct physical access path to data, which is provided by an index, hash,

or link; a fan set is the means by which DB2 supports the ordering of data.

federated database

The combination of a DB2 server (in Linux, UNIX, and Windows

environments) and multiple data sources to which the server sends queries.

In a federated database system, a client application can use a single SQL

statement to join data that is distributed across multiple database

management systems and can view the data as if it were local.

fetch orientation

The specification of the desired placement of the cursor as part of a FETCH

statement. The specification can be before or after the rows of the result

table (with BEFORE or AFTER). The specification can also have either a

single-row fetch orientation (for example, NEXT, LAST, or ABSOLUTE n)

or a rowset fetch orientation (for example, NEXT ROWSET, LAST

ROWSET, or ROWSET STARTING AT ABSOLUTE n).

field procedure

A user-written exit routine that is designed to receive a single value and

transform (encode or decode) it in any way the user can specify.

file reference variable

A host variable that is declared with one of the derived data types

(BLOB_FILE, CLOB_FILE, DBCLOB_FILE); file reference variables direct

the reading of a LOB from a file or the writing of a LOB into a file.

filter factor

A number between zero and one that estimates the proportion of rows in a

table for which a predicate is true.

fixed-length string

A character, graphic, or binary string whose length is specified and cannot

be changed. Contrast with varying-length string.

FlashCopy

A function on the IBM Enterprise Storage Server that can, in conjunction

with the BACKUP SYSTEM utility, create a point-in-time copy of data

while an application is running.

foreign key

A column or set of columns in a dependent table of a constraint

relationship. The key must have the same number of columns, with the

Glossary 1311

|||

||||||

||||

||

|||

same descriptions, as the primary key of the parent table. Each foreign key

value must either match a parent key value in the related parent table or

be null.

forest An ordered set of subtrees of XML nodes.

forward log recovery

The third phase of restart processing during which DB2 processes the log

in a forward direction to apply all REDO log records.

free space

The total amount of unused space in a page; that is, the space that is not

used to store records or control information is free space.

full outer join

The result of a join operation that includes the matched rows of both tables

that are being joined and preserves the unmatched rows of both tables. See

also join, equijoin, inner join, left outer join, outer join, and right outer join.

fullselect

A subselect, a fullselect in parentheses, or a number of both that are

combined by set operators. Fullselect specifies a result table. If a set

operator is not used, the result of the fullselect is the result of the specified

subselect or fullselect.

fully escaped mapping

A mapping from an SQL identifier to an XML name when the SQL

identifier is a column name.

function

A mapping, which is embodied as a program (the function body) that is

invocable by means of zero or more input values (arguments) to a single

value (the result). See also aggregate function and scalar function.

Functions can be user-defined, built-in, or generated by DB2. (See also

built-in function, cast function, external function, sourced function, SQL

function, and user-defined function.)

function definer

The authorization ID of the owner of the schema of the function that is

specified in the CREATE FUNCTION statement.

function package

A package that results from binding the DBRM for a function program.

function package owner

The authorization ID of the user who binds the function program’s DBRM

into a function package.

function signature

The logical concatenation of a fully qualified function name with the data

types of all of its parameters.

GB Gigabyte. A value of (1 073 741 824 bytes).

GBP See group buffer pool.

GBP-dependent

The status of a page set or page set partition that is dependent on the

group buffer pool. Either read/write interest is active among DB2

subsystems for this page set, or the page set has changed pages in the

group buffer pool that have not yet been cast out to disk.


|||||

generalized trace facility (GTF)

A z/OS service program that records significant system events such as I/O

interrupts, SVC interrupts, program interrupts, or external interrupts.

generic resource name

A name that VTAM uses to represent several application programs that

provide the same function in order to handle session distribution and

balancing in a Sysplex environment.

getpage

An operation in which DB2 accesses a data page.

global lock

A lock that provides concurrency control within and among DB2

subsystems. The scope of the lock is across all DB2 subsystems of a data

sharing group.

global lock contention

Conflicts on locking requests between different DB2 members of a data

sharing group when those members are trying to serialize shared

resources.

governor

See resource limit facility.

graphic string

A sequence of DBCS characters. Graphic data can be further classified as

GRAPHIC, VARGRAPHIC, or DBCLOB.

GRECP

See group buffer pool recovery pending.

gross lock

The shared, update, or exclusive mode locks on a table, partition, or table

space.

group buffer pool duplexing

The ability to write data to two instances of a group buffer pool structure:

a primary group buffer pool and a secondary group buffer pool. z/OS

publications refer to these instances as the “old” (for primary) and “new”

(for secondary) structures.

group buffer pool (GBP)

A coupling facility cache structure that is used by a data sharing group to

cache data and to ensure that the data is consistent for all members.

group buffer pool recovery pending (GRECP)

The state that exists after the buffer pool for a data sharing group is lost.

When a page set is in this state, changes that are recorded in the log must

be applied to the affected page set before the page set can be used.

group level

The release level of a data sharing group, which is established when the

first member migrates to a new release.

group name

The z/OS XCF identifier for a data sharing group.

group restart

A restart of at least one member of a data sharing group after the loss of

either locks or the shared communications area.

GTF See generalized trace facility.

Glossary 1313

||

||

||||

handle

In DB2 ODBC, a variable that refers to a data structure and associated

resources. See also statement handle, connection handle, and environment

handle.

help panel

A screen of information that presents tutorial text to assist a user at the

workstation or terminal.

heuristic damage

The inconsistency in data between one or more participants that results

when a heuristic decision to resolve an indoubt LUW at one or more

participants differs from the decision that is recorded at the coordinator.

heuristic decision

A decision that forces indoubt resolution at a participant by means other

than automatic resynchronization between coordinator and participant.

histogram statistics

A way of summarizing data distribution. This technique divides up the

range of possible values in a data set into intervals, such that each interval

contains approximately the same percentage of the values. A set of

statistics are collected for each interval.

hole A row of the result table that cannot be accessed because of a delete or an

update that has been performed on the row. See also delete hole and

update hole.

home address space

The area of storage that z/OS currently recognizes as dispatched.

host The set of programs and resources that are available on a given TCP/IP

instance.

host expression

A Java variable or expression that is referenced by SQL clauses in an SQLJ

application program.

host identifier

A name that is declared in the host program.

host language

A programming language in which you can embed SQL statements.

host program

An application program that is written in a host language and that

contains embedded SQL statements.

host structure

In an application program, a structure that is referenced by embedded SQL

statements.

host variable

In an application program written in a host language, an application

variable that is referenced by embedded SQL statements.

host variable array

An array of elements, each of which corresponds to a value for a column.

The dimension of the array determines the maximum number of rows for

which the array can be used.

IBM System z9 Integrated Processor (zIIP)

A specialized processor that can be used for some DB2 functions.


|||||

|

IDCAMS

An IBM program that is used to process access method services

commands. It can be invoked as a job or jobstep, from a TSO terminal, or

from within a user’s application program.

IDCAMS LISTCAT

A facility for obtaining information that is contained in the access method

services catalog.

identity column

A column that provides a way for DB2 to automatically generate a numeric

value for each row. Identity columns are defined with the AS IDENTITY

clause. Uniqueness of values can be ensured by defining a unique index

that contains only the identity column. A table can have no more than one

identity column.

IFCID See instrumentation facility component identifier.

IFI See instrumentation facility interface.

IFI call

An invocation of the instrumentation facility interface (IFI) by means of

one of its defined functions.

image copy

An exact reproduction of all or part of a table space. DB2 provides utility

programs to make full image copies (to copy the entire table space) or

incremental image copies (to copy only those pages that have been

modified since the last image copy).

IMS attachment facility

A DB2 subcomponent that uses z/OS subsystem interface (SSI) protocols

and cross-memory linkage to process requests from IMS to DB2 and to

coordinate resource commitment.

in-abort

A status of a unit of recovery. If DB2 fails after a unit of recovery begins to

be rolled back, but before the process is completed, DB2 continues to back

out the changes during restart.

in-commit

A status of a unit of recovery. If DB2 fails after beginning its phase 2

commit processing, it ″knows,″ when restarted, that changes made to data

are consistent. Such units of recovery are termed in-commit.

independent

An object (row, table, or table space) that is neither a parent nor a

dependent of another object.

index A set of pointers that are logically ordered by the values of a key. Indexes

can provide faster access to data and can enforce uniqueness on the rows

in a table.

index-controlled partitioning

A type of partitioning in which partition boundaries for a partitioned table

are controlled by values that are specified on the CREATE INDEX

statement. Partition limits are saved in the LIMITKEY column of the

SYSIBM.SYSINDEXPART catalog table.

index key

The set of columns in a table that is used to determine the order of index

entries.

Glossary 1315

|||||

index partition

A VSAM data set that is contained within a partitioning index space.

index space

A page set that is used to store the entries of one index.

indicator column

A 4-byte value that is stored in a base table in place of a LOB column.

indicator variable

A variable that is used to represent the null value in an application

program. If the value for the selected column is null, a negative value is

placed in the indicator variable.

indoubt

A status of a unit of recovery. If DB2 fails after it has finished its phase 1

commit processing and before it has started phase 2, only the commit

coordinator knows if an individual unit of recovery is to be committed or

rolled back. At restart, if DB2 lacks the information it needs to make this

decision, the status of the unit of recovery is indoubt until DB2 obtains this

information from the coordinator. More than one unit of recovery can be

indoubt at restart.

indoubt resolution

The process of resolving the status of an indoubt logical unit of work to

either the committed or the rollback state.

inflight

A status of a unit of recovery. If DB2 fails before its unit of recovery

completes phase 1 of the commit process, it merely backs out the updates

of its unit of recovery at restart. These units of recovery are termed inflight.

inheritance

The passing downstream of class resources or attributes from a parent class

in the class hierarchy to a child class.

initialization file

For DB2 ODBC applications, a file containing values that can be set to

adjust the performance of the database manager.

inline copy

A copy that is produced by the LOAD or REORG utility. The data set that

the inline copy produces is logically equivalent to a full image copy that is

produced by running the COPY utility with read-only access (SHRLEVEL

REFERENCE).

inner join

The result of a join operation that includes only the matched rows of both

tables that are being joined. See also join, equijoin, full outer join, left outer

join, outer join, and right outer join.

inoperative package

A package that cannot be used because one or more user-defined functions

or procedures that the package depends on were dropped. Such a package

must be explicitly rebound. Contrast with invalid package.

insensitive cursor

A cursor that is not sensitive to inserts, updates, or deletes that are made

to the underlying rows of a result table after the result table has been

materialized.


insert trigger

A trigger that is defined with the triggering SQL operation, an insert.

install The process of preparing a DB2 subsystem to operate as a z/OS

subsystem.

INSTEAD OF trigger

A trigger that is associated with a single view and is activated by an insert,

update, or delete operation on the view and that can define how to

propagate the insert, update, or delete operation on the view to the

underlying tables of the view. Contrast with BEFORE trigger and AFTER

trigger.

instrumentation facility component identifier (IFCID)

A value that names and identifies a trace record of an event that can be

traced. As a parameter on the START TRACE and MODIFY TRACE

commands, it specifies that the corresponding event is to be traced.

instrumentation facility interface (IFI)

A programming interface that enables programs to obtain online trace data

about DB2, to submit DB2 commands, and to pass data to DB2.

Interactive System Productivity Facility (ISPF)

An IBM licensed program that provides interactive dialog services in a

z/OS environment.

inter-DB2 R/W interest

A property of data in a table space, index, or partition that has been

opened by more than one member of a data sharing group and that has

been opened for writing by at least one of those members.

intermediate database server

The target of a request from a local application or a remote application

requester that is forwarded to another database server.

internal resource lock manager (IRLM)

A z/OS subsystem that DB2 uses to control communication and database

locking.

internationalization

The support for an encoding scheme that is able to represent the code

points of characters from many different geographies and languages. To

support all geographies, the Unicode standard requires more than 1 byte to

represent a single character. See also Unicode.

intersection

An SQL operation that involves the INTERSECT set operator, which

combines two result tables. The result of an intersection operation consists

of all of the rows that are in both result tables.

invalid package

A package that depends on an object (other than a user-defined function)

that is dropped. Such a package is implicitly rebound on invocation.

Contrast with inoperative package.

IP address

A value that uniquely identifies a TCP/IP host.

IRLM See internal resource lock manager.

isolation level

The degree to which a unit of work is isolated from the updating

Glossary 1317

||||||

||||

|

operations of other units of work. See also cursor stability, read stability,

repeatable read, and uncommitted read.

ISPF See Interactive System Productivity Facility.

iterator

In SQLJ, an object that contains the result set of a query. An iterator is

equivalent to a cursor in other host languages.

iterator declaration clause

In SQLJ, a statement that generates an iterator declaration class. An iterator

is an object of an iterator declaration class.

JAR See Java Archive.

Java Archive (JAR)

A file format that is used for aggregating many files into a single file.

JDBC A Sun Microsystems database application programming interface (API) for

Java that allows programs to access database management systems by

using callable SQL.

join A relational operation that allows retrieval of data from two or more tables

based on matching column values. See also equijoin, full outer join, inner

join, left outer join, outer join, and right outer join.

KB Kilobyte. A value of 1024 bytes.

Kerberos

A network authentication protocol that is designed to provide strong

authentication for client/server applications by using secret-key

cryptography.

Kerberos ticket

A transparent application mechanism that transmits the identity of an

initiating principal to its target. A simple ticket contains the principal’s

identity, a session key, a timestamp, and other information, which is sealed

using the target’s secret key.

key A column, an ordered collection of columns, or an expression that is

identified in the description of a table, index, or referential constraint. The

same column or expression can be part of more than one key.

key-sequenced data set (KSDS)

A VSAM file or data set whose records are loaded in key sequence and

controlled by an index.

KSDS See key-sequenced data set.

large object (LOB)

A sequence of bytes representing bit data, single-byte characters,

double-byte characters, or a mixture of single- and double-byte characters.

A LOB can be up to 2 GB minus 1 byte in length. See also binary large

object, character large object, and double-byte character large object.

last agent optimization

An optimized commit flow for either presumed-nothing or presumed-abort

protocols in which the last agent, or final participant, becomes the commit

coordinator. This flow saves at least one message.

latch A DB2 mechanism for controlling concurrent events or the use of system

resources.

LCID See log control interval definition.


|||

LDS See linear data set.

leaf page

An index page that contains pairs of keys and RIDs and that points to

actual data. Contrast with nonleaf page.

left outer join


that are being joined, and that preserves the unmatched rows of the first

table. See also join, equijoin, full outer join, inner join, outer join, and right

outer join.

limit key

The highest value of the index key for a partition.

linear data set (LDS)

A VSAM data set that contains data but no control information. A linear

data set can be accessed as a byte-addressable string in virtual storage.

linkage editor

A computer program for creating load modules from one or more object

modules or load modules by resolving cross references among the modules

and, if necessary, adjusting addresses.

link-edit

The action of creating a loadable computer program using a linkage editor.

list A type of object, which DB2 utilities can process, that identifies multiple

table spaces, multiple index spaces, or both. A list is defined with the

LISTDEF utility control statement.

list structure

A coupling facility structure that lets data be shared and manipulated as

elements of a queue.

L-lock See logical lock.

load module

A program unit that is suitable for loading into main storage for execution.

The output of a linkage editor.

LOB See large object.

LOB locator

A mechanism that allows an application program to manipulate a large

object value in the database system. A LOB locator is a fullword integer

value that represents a single LOB value. An application program retrieves

a LOB locator into a host variable and can then apply SQL operations to

the associated LOB value using the locator.

LOB lock

A lock on a LOB value.

LOB table space

A table space that contains all the data for a particular LOB column in the

related base table.

local A way of referring to any object that the local DB2 subsystem maintains. A

local table, for example, is a table that is maintained by the local DB2

subsystem. Contrast with remote.

locale The definition of a subset of a user’s environment that combines a CCSID

and characters that are defined for a specific language and country.

Glossary 1319

local lock

A lock that provides intra-DB2 concurrency control, but not inter-DB2

concurrency control; that is, its scope is a single DB2.

local subsystem

The unique relational DBMS to which the user or application program is

directly connected (in the case of DB2, by one of the DB2 attachment

facilities).

location

The unique name of a database server. An application uses the location

name to access a DB2 database server. A database alias can be used to

override the location name when accessing a remote server.

location alias

Another name by which a database server identifies itself in the network.

Applications can use this name to access a DB2 database server.

lock A means of controlling concurrent events or access to data. DB2 locking is

performed by the IRLM.

lock duration

The interval over which a DB2 lock is held.

lock escalation

The promotion of a lock from a row, page, or LOB lock to a table space

lock because the number of page locks that are concurrently held on a

given resource exceeds a preset limit.

locking

The process by which the integrity of data is ensured. Locking prevents

concurrent users from accessing inconsistent data. See also claim, drain,

and latch.

lock mode

A representation for the type of access that concurrently running programs

can have to a resource that a DB2 lock is holding.

lock object

The resource that is controlled by a DB2 lock.

lock promotion

The process of changing the size or mode of a DB2 lock to a higher, more

restrictive level.

lock size

The amount of data that is controlled by a DB2 lock on table data; the

value can be a row, a page, a LOB, a partition, a table, or a table space.

lock structure

A coupling facility data structure that is composed of a series of lock

entries to support shared and exclusive locking for logical resources.

log A collection of records that describe the events that occur during DB2

execution and that indicate their sequence. The information thus recorded

is used for recovery in the event of a failure during DB2 execution.

log control interval definition

A suffix of the physical log record that tells how record segments are

placed in the physical control interval.

logical claim

A claim on a logical partition of a nonpartitioning index.


logical index partition

The set of all keys that reference the same data partition.

logical lock (L-lock)

The lock type that transactions use to control intra- and inter-DB2 data

concurrency between transactions. Contrast with physical lock (P-lock).

logically complete

A state in which the concurrent copy process is finished with the

initialization of the target objects that are being copied. The target objects

are available for update.

logical page list (LPL)

A list of pages that are in error and that cannot be referenced by

applications until the pages are recovered. The page is in logical error

because the actual media (coupling facility or disk) might not contain any

errors. Usually a connection to the media has been lost.

logical partition

A set of key or RID pairs in a nonpartitioning index that are associated

with a particular partition.

logical recovery pending (LRECP)

The state in which the data and the index keys that reference the data are

inconsistent.

logical unit (LU)

An access point through which an application program accesses the SNA

network in order to communicate with another application program. See

also LU name.

logical unit of work identifier (LUWID)

A name that uniquely identifies a thread within a network. This name

consists of a fully-qualified LU network name, an LUW instance number,

and an LUW sequence number.

logical unit of work

The processing that a program performs between synchronization points.

log initialization

The first phase of restart processing during which DB2 attempts to locate

the current end of the log.

log record header (LRH)

A prefix, in every log record, that contains control information.

log record sequence number (LRSN)

An identifier for a log record that is associated with a data sharing

member. DB2 uses the LRSN for recovery in the data sharing environment.

log truncation

A process by which an explicit starting RBA is established. This RBA is the

point at which the next byte of log data is to be written.

LPL See logical page list.

LRECP

See logical recovery pending.

LRH See log record header.

LRSN See log record sequence number.

LU See logical unit.

Glossary 1321

LU name

Logical unit name, which is the name by which VTAM refers to a node in

a network.

LUW See logical unit of work.

LUWID

See logical unit of work identifier.

mapping table

A table that the REORG utility uses to map the associations of the RIDs of

data records in the original copy and in the shadow copy. This table is

created by the user.

mass delete

The deletion of all rows of a table.

materialize

v The process of putting rows from a view or nested table expression into

a work file for additional processing by a query.

v The placement of a LOB value into contiguous storage. Because LOB

values can be very large, DB2 avoids materializing LOB data until doing

so becomes absolutely necessary.

materialized query table

A table that is used to contain information that is derived and can be

summarized from one or more source tables. Contrast with base table.

MB Megabyte (1 048 576 bytes).

MBCS See multibyte character set.

member name

The z/OS XCF identifier for a particular DB2 subsystem in a data sharing

group.

menu A displayed list of available functions for selection by the operator. A

menu is sometimes called a menu panel.

metalanguage

A language that is used to create other specialized languages.

migration

The process of converting a subsystem with a previous release of DB2 to

an updated or current release. In this process, you can acquire the

functions of the updated or current release without losing the data that

you created on the previous release.

mixed data string

A character string that can contain both single-byte and double-byte

characters.

mode name

A VTAM name for the collection of physical and logical characteristics and

attributes of a session.

modify locks

An L-lock or P-lock with a MODIFY attribute. A list of these active locks is

kept at all times in the coupling facility lock structure. If the requesting

DB2 subsystem fails, that DB2 subsystem’s modify locks are converted to

retained locks.


multibyte character set (MBCS)

A character set that represents single characters with more than a single

byte. UTF-8 is an example of an MBCS. Characters in UTF-8 can range

from 1 to 4 bytes in DB2. Contrast with single-byte character set and

double-byte character set. See also Unicode.

multidimensional analysis

The process of assessing and evaluating an enterprise on more than one

level.

Multiple Virtual Storage (MVS)

An element of the z/OS operating system. This element is also called the

Base Control Program (BCP).

multisite update

Distributed relational database processing in which data is updated in

more than one location within a single unit of work.

multithreading

Multiple TCBs that are executing one copy of DB2 ODBC code

concurrently (sharing a processor) or in parallel (on separate central

processors).

MVS See Multiple Virtual Storage.

native SQL procedure

An SQL procedure that is processed by converting the procedural

statements to a native representation that is stored in the database

directory, as is done with other SQL statements. When a native SQL

procedure is called, the native representation is loaded from the directory,

and DB2 executes the procedure. Contrast with external procedure and

external SQL procedure.

nested table expression

A fullselect in a FROM clause (surrounded by parentheses).

network identifier (NID)

The network ID that is assigned by IMS or CICS, or if the connection type

is RRSAF, the RRS unit of recovery ID (URID).

new-function mode (NFM)

The normal mode of operation that exists after successful completion of a

version-to-version migration. At this stage, all new functions of the new

version are available for use. A DB2 data sharing group cannot coexist with

members that are still at the prior version level, and fallback to a prior

version is not supported. Contrast with compatibility mode, compatibility

mode*, enabling-new-function mode, and enabling-new-function mode*.

NFM See new-function mode.

NID See network identifier.

node ID index

See XML node ID index.

nondeterministic function

A user-defined function whose result is not solely dependent on the values

of the input arguments. That is, successive invocations with the same

argument values can produce a different answer. This type of function is

sometimes called a variant function. Contrast with deterministic function

(sometimes called a not-variant function).

Glossary 1323

|||||||

|||||||

|

||

nonleaf page

A page that contains keys and page numbers of other pages in the index

(either leaf or nonleaf pages). Nonleaf pages never point to actual data.

Contrast with leaf page.

nonpartitioned index

An index that is not physically partitioned. Both partitioning indexes and

secondary indexes can be nonpartitioned.

nonpartitioned secondary index (NPSI)

An index on a partitioned table space that is not the partitioning index and

is not partitioned. Contrast with data-partitioned secondary index.

nonpartitioning index

See secondary index.

nonscrollable cursor

A cursor that can be moved only in a forward direction. Nonscrollable

cursors are sometimes called forward-only cursors or serial cursors.

normalization

A key step in the task of building a logical relational database design.

Normalization helps you avoid redundancies and inconsistencies in your

data. An entity is normalized if it meets a set of constraints for a particular

normal form (first normal form, second normal form, and so on). Contrast

with denormalization.

not-variant function

See deterministic function.

NPSI See nonpartitioned secondary index.

NUL The null character (’\0’), which is represented by the value X’00’. In C, this

character denotes the end of a string.

null A special value that indicates the absence of information.

null terminator

In C, the value that indicates the end of a string. For EBCDIC, ASCII, and

Unicode UTF-8 strings, the null terminator is a single-byte value (X’00’).

For Unicode UTF-16 or UCS-2 (wide) strings, the null terminator is a

double-byte value (X’0000’).

ODBC

See Open Database Connectivity.

ODBC driver

A dynamically-linked library (DLL) that implements ODBC function calls

and interacts with a data source.

OLAP See online analytical processing.

online analytical processing (OLAP)

The process of collecting data from one or many sources; transforming and

analyzing the consolidated data quickly and interactively; and examining

the results across different dimensions of the data by looking for patterns,

trends, and exceptions within complex relationships of that data.

Open Database Connectivity (ODBC)

A Microsoft database application programming interface (API) for C that

allows access to database management systems by using callable SQL.

ODBC does not require the use of an SQL preprocessor. In addition, ODBC

provides an architecture that lets users add modules called database drivers,


||||

||

|||||

which link the application to their choice of database management systems

at run time. This means that applications no longer need to be directly

linked to the modules of all the database management systems that are

supported.

ordinary identifier

An uppercase letter followed by zero or more characters, each of which is

an uppercase letter, a digit, or the underscore character. An ordinary

identifier must not be a reserved word.

ordinary token

A numeric constant, an ordinary identifier, a host identifier, or a keyword.

originating task

In a parallel group, the primary agent that receives data from other

execution units (referred to as parallel tasks) that are executing portions of

the query in parallel.

outer join


that are being joined and preserves some or all of the unmatched rows of

the tables that are being joined. See also join, equijoin, full outer join, inner

join, left outer join, and right outer join.

overloaded function

A function name for which multiple function instances exist.

package

An object containing a set of SQL statements that have been statically

bound and that is available for processing. A package is sometimes also

called an application package.

package list

An ordered list of package names that may be used to extend an

application plan.

package name

The name of an object that is used for an application package or an SQL

procedure package. An application package is a bound version of a

database request module (DBRM) that is created by a BIND PACKAGE or

REBIND PACKAGE command. An SQL procedural language package is

created by a CREATE or ALTER PROCEDURE statement for a native SQL

procedure. The name of a package consists of a location name, a collection

ID, a package ID, and a version ID.

page A unit of storage within a table space (4 KB, 8 KB, 16 KB, or 32 KB) or

index space (4 KB, 8 KB, 16 KB, or 32 KB). In a table space, a page contains

one or more rows of a table. In a LOB or XML table space, a LOB or XML

value can span more than one page, but no more than one LOB or XML

value is stored on a page.

page set

Another way to refer to a table space or index space. Each page set

consists of a collection of VSAM data sets.

page set recovery pending (PSRCP)

A restrictive state of an index space. In this case, the entire page set must

be recovered. Recovery of a logical part is prohibited.

panel A predefined display image that defines the locations and characteristics of

display fields on a display surface (for example, a menu panel).

Glossary 1325

|||||||

|||||

parallel complex

A cluster of machines that work together to handle multiple transactions

and applications.

parallel group

A set of consecutive operations that execute in parallel and that have the

same number of parallel tasks.

parallel I/O processing

A form of I/O processing in which DB2 initiates multiple concurrent

requests for a single user query and performs I/O processing concurrently

(in parallel) on multiple data partitions.

parallelism assistant

In Sysplex query parallelism, a DB2 subsystem that helps to process parts

of a parallel query that originates on another DB2 subsystem in the data

sharing group.

parallelism coordinator

In Sysplex query parallelism, the DB2 subsystem from which the parallel

query originates.

Parallel Sysplex

A set of z/OS systems that communicate and cooperate with each other

through certain multisystem hardware components and software services

to process customer workloads.

parallel task

The execution unit that is dynamically created to process a query in

parallel. A parallel task is implemented by a z/OS service request block.

parameter marker

A question mark (?) that appears in a statement string of a dynamic SQL

statement. The question mark can appear where a variable could appear if

the statement string were a static SQL statement.

parameter-name

An SQL identifier that designates a parameter in a routine that is written

by a user. Parameter names are required for SQL procedures and SQL

functions, and they are used in the body of the routine to refer to the

values of the parameters. Parameter names are optional for external

routines.

parent key

A primary key or unique key in the parent table of a referential constraint.

The values of a parent key determine the valid values of the foreign key in

the referential constraint.

parent lock

For explicit hierarchical locking, a lock that is held on a resource that

might have child locks that are lower in the hierarchy. A parent lock is

usually the table space lock or the partition intent lock. See also child lock.

parent row

A row whose primary key value is the foreign key value of a dependent

row.

parent table

A table whose primary key is referenced by the foreign key of a dependent

table.


|||

|||||

parent table space

A table space that contains a parent table. A table space containing a

dependent of that table is a dependent table space.

participant

An entity other than the commit coordinator that takes part in the commit

process. The term participant is synonymous with agent in SNA.

partition

A portion of a page set. Each partition corresponds to a single,

independently extendable data set. The maximum size of a partition

depends on the number of partitions in the partitioned page set. All

partitions of a given page set have the same maximum size.

partition-by-growth table space

A table space whose size can grow to accommodate data growth. DB2 for

z/OS manages partition-by-growth table spaces by automatically adding

new data sets when the database needs more space to satisfy an insert

operation. Contrast with range-partitioned table space. See also universal

table space.

partitioned data set (PDS)

A data set in disk storage that is divided into partitions, which are called

members. Each partition can contain a program, part of a program, or data.

A program library is an example of a partitioned data set.

partitioned index

An index that is physically partitioned. Both partitioning indexes and

secondary indexes can be partitioned.

partitioned page set

A partitioned table space or an index space. Header pages, space map

pages, data pages, and index pages reference data only within the scope of

the partition.

partitioned table space

A table space that is based on a single table and that is subdivided into

partitions, each of which can be processed independently by utilities.

Contrast with segmented table space and universal table space.

partitioning index

An index in which the leftmost columns are the partitioning columns of

the table. The index can be partitioned or nonpartitioned.

partner logical unit

An access point in the SNA network that is connected to the local DB2

subsystem by way of a VTAM conversation.

path See SQL path.

PDS See partitioned data set.

physical consistency

The state of a page that is not in a partially changed state.

physical lock (P-lock)

A type of lock that DB2 acquires to provide consistency of data that is

cached in different DB2 subsystems. Physical locks are used only in data

sharing environments. Contrast with logical lock (L-lock).

physically complete

The state in which the concurrent copy process is completed and the

output data set has been created.

Glossary 1327

||||

||||||

|||

|||

piece A data set of a nonpartitioned page set.

plan See application plan.

plan allocation

The process of allocating DB2 resources to a plan in preparation for

execution.

plan member

The bound copy of a DBRM that is identified in the member clause.

plan name

The name of an application plan.

P-lock See physical lock.

point of consistency

A time when all recoverable data that an application accesses is consistent

with other data. The term point of consistency is synonymous with sync

point or commit point.

policy See CFRM policy.

postponed abort UR

A unit of recovery that was inflight or in-abort, was interrupted by system

failure or cancellation, and did not complete backout during restart.

precision

In SQL, the total number of digits in a decimal number (called the size in

the C language). In the C language, the number of digits to the right of the

decimal point (called the scale in SQL). The DB2 information uses the SQL

terms.

precompilation

A processing of application programs containing SQL statements that takes

place before compilation. SQL statements are replaced with statements that

are recognized by the host language compiler. Output from this

precompilation includes source code that can be submitted to the compiler

and the database request module (DBRM) that is input to the bind process.

predicate

An element of a search condition that expresses or implies a comparison

operation.

prefix A code at the beginning of a message or record.

preformat

The process of preparing a VSAM linear data set for DB2 use, by writing

specific data patterns.

prepare

The first phase of a two-phase commit process in which all participants are

requested to prepare for commit.

prepared SQL statement

A named object that is the executable form of an SQL statement that has

been processed by the PREPARE statement.

primary authorization ID

The authorization ID that is used to identify the application process to

DB2.

primary group buffer pool

For a duplexed group buffer pool, the structure that is used to maintain


||

the coherency of cached data. This structure is used for page registration

and cross-invalidation. The z/OS equivalent is old structure. Compare with

secondary group buffer pool.

primary index

An index that enforces the uniqueness of a primary key.

primary key

In a relational database, a unique, nonnull key that is part of the definition

of a table. A table cannot be defined as a parent unless it has a unique key

or primary key.

principal

An entity that can communicate securely with another entity. In Kerberos,

principals are represented as entries in the Kerberos registry database and

include users, servers, computers, and others.

principal name

The name by which a principal is known to the DCE security services.

privilege

The capability of performing a specific function, sometimes on a specific

object. See also explicit privilege.

privilege set

v For the installation SYSADM ID, the set of all possible privileges.

v For any other authorization ID, including the PUBLIC authorization ID,

the set of all privileges that are recorded for that ID in the DB2 catalog.

process

In DB2, the unit to which DB2 allocates resources and locks. Sometimes

called an application process, a process involves the execution of one or

more programs. The execution of an SQL statement is always associated

with some process. The means of initiating and terminating a process are

dependent on the environment.

program

A single, compilable collection of executable statements in a programming

language.

program temporary fix (PTF)

A solution or bypass of a problem that is diagnosed as a result of a defect

in a current unaltered release of a licensed program. An authorized

program analysis report (APAR) fix is corrective service for an existing

problem. A PTF is preventive service for problems that might be

encountered by other users of the product. A PTF is temporary, because a

permanent fix is usually not incorporated into the product until its next

release.

protected conversation

A VTAM conversation that supports two-phase commit flows.

PSRCP

See page set recovery pending.

PTF See program temporary fix.

QSAM

See queued sequential access method.

query A component of certain SQL statements that specifies a result table.

Glossary 1329

|

||

query block

The part of a query that is represented by one of the FROM clauses. Each

FROM clause can have multiple query blocks, depending on DB2

processing of the query.

query CP parallelism

Parallel execution of a single query, which is accomplished by using

multiple tasks. See also Sysplex query parallelism.

query I/O parallelism

Parallel access of data, which is accomplished by triggering multiple I/O

requests within a single query.

queued sequential access method (QSAM)

An extended version of the basic sequential access method (BSAM). When

this method is used, a queue of data blocks is formed. Input data blocks

await processing, and output data blocks await transfer to auxiliary storage

or to an output device.

quiesce point

A point at which data is consistent as a result of running the DB2

QUIESCE utility.

RACF Resource Access Control Facility. A component of the z/OS Security Server.

range-partitioned table space

A type of universal table space that is based on partitioning ranges and

that contains a single table. Contrast with partition-by-growth table space.

See also universal table space.

RBA See relative byte address.

RCT See resource control table.

RDO See resource definition online.

read stability (RS)

An isolation level that is similar to repeatable read but does not completely

isolate an application process from all other concurrently executing

application processes. See also cursor stabilityrepeatable read, and

uncommitted read.

rebind

The creation of a new application plan for an application program that has

been bound previously. If, for example, you have added an index for a

table that your application accesses, you must rebind the application in

order to take advantage of that index.

rebuild

The process of reallocating a coupling facility structure. For the shared

communications area (SCA) and lock structure, the structure is

repopulated; for the group buffer pool, changed pages are usually cast out

to disk, and the new structure is populated only with changed pages that

were not successfully cast out.

record The storage representation of a row or other data.

record identifier (RID)

A unique identifier that DB2 uses to identify a row of data in a table.

Compare with row identifier.


||||

||

record identifier (RID) pool

An area of main storage that is used for sorting record identifiers during

list-prefetch processing.

record length

The sum of the length of all the columns in a table, which is the length of

the data as it is physically stored in the database. Records can be fixed

length or varying length, depending on how the columns are defined. If all

columns are fixed-length columns, the record is a fixed-length record. If

one or more columns are varying-length columns, the record is a

varying-length record.

Recoverable Resource Manager Services attachment facility (RRSAF)

A DB2 subcomponent that uses Resource Recovery Services to coordinate

resource commitment between DB2 and all other resource managers that

also use RRS in a z/OS system.

recovery

The process of rebuilding databases after a system failure.

recovery log

A collection of records that describes the events that occur during DB2

execution and indicates their sequence. The recorded information is used

for recovery in the event of a failure during DB2 execution.

recovery manager

A subcomponent that supplies coordination services that control the

interaction of DB2 resource managers during commit, abort, checkpoint,

and restart processes. The recovery manager also supports the recovery

mechanisms of other subsystems (for example, IMS) by acting as a

participant in the other subsystem’s process for protecting data that has

reached a point of consistency.

A coordinator or a participant (or both), in the execution of a two-phase

commit, that can access a recovery log that maintains the state of the

logical unit of work and names the immediate upstream coordinator and

downstream participants.

recovery pending (RECP)

A condition that prevents SQL access to a table space that needs to be

recovered.

recovery token

An identifier for an element that is used in recovery (for example, NID or

URID).

RECP See recovery pending.

redo A state of a unit of recovery that indicates that changes are to be reapplied

to the disk media to ensure data integrity.

reentrant code

Executable code that can reside in storage as one shared copy for all

threads. Reentrant code is not self-modifying and provides separate storage

areas for each thread. See also threadsafe.

referential constraint

The requirement that nonnull values of a designated foreign key are valid

only if they equal values of the primary key of a designated table.

referential cycle

A set of referential constraints such that each base table in the set is a

Glossary 1331

||

descendent of itself. The tables that are involved in a referential cycle are

ordered so that each table is a descendent of the one before it, and the first

table is a descendent of the last table.

referential integrity

The state of a database in which all values of all foreign keys are valid.

Maintaining referential integrity requires the enforcement of referential

constraints on all operations that change the data in a table on which the

referential constraints are defined.

referential structure

A set of tables and relationships that includes at least one table and, for

every table in the set, all the relationships in which that table participates

and all the tables to which it is related.

refresh age

The time duration between the current time and the time during which a

materialized query table was last refreshed.

registry

See registry database.

registry database

A database of security information about principals, groups, organizations,

accounts, and security policies.

relational database

A database that can be perceived as a set of tables and manipulated in

accordance with the relational model of data.

relational database management system (RDBMS)

A collection of hardware and software that organizes and provides access

to a relational database.

relational schema

See SQL schema.

relationship

A defined connection between the rows of a table or the rows of two

tables. A relationship is the internal representation of a referential

constraint.

relative byte address (RBA)

The offset of a data record or control interval from the beginning of the

storage space that is allocated to the data set or file to which it belongs.

remigration

The process of returning to a current release of DB2 following a fallback to

a previous release. This procedure constitutes another migration process.

remote

Any object that is maintained by a remote DB2 subsystem (that is, by a

DB2 subsystem other than the local one). A remote view, for example, is a

view that is maintained by a remote DB2 subsystem. Contrast with local.

remote subsystem

Any relational DBMS, except the local subsystem, with which the user or

application can communicate. The subsystem need not be remote in any

physical sense, and might even operate on the same processor under the

same z/OS system.

reoptimization

The DB2 process of reconsidering the access path of an SQL statement at


|||

||

run time; during reoptimization, DB2 uses the values of host variables,

parameter markers, or special registers.

reordered row format

A row format that facilitates improved performance in retrieval of rows

that have varying-length columns. DB2 rearranges the column order, as

defined in the CREATE TABLE statement, so that the fixed-length columns

are stored at the beginning of the row and the varying-length columns are

stored at the end of the row. Contrast with basic row format.

REORG pending (REORP)

A condition that restricts SQL access and most utility access to an object

that must be reorganized.

REORP

See REORG pending.

repeatable read (RR)

The isolation level that provides maximum protection from other executing

application programs. When an application program executes with

repeatable read protection, rows that the program references cannot be

changed by other programs until the program reaches a commit point. See

also cursor stability, read stability, and uncommitted read.

repeating group

A situation in which an entity includes multiple attributes that are

inherently the same. The presence of a repeating group violates the

requirement of first normal form. In an entity that satisfies the requirement

of first normal form, each attribute is independent and unique in its

meaning and its name. See also normalization.

replay detection mechanism

A method that allows a principal to detect whether a request is a valid

request from a source that can be trusted or whether an untrustworthy

entity has captured information from a previous exchange and is replaying

the information exchange to gain access to the principal.

request commit

The vote that is submitted to the prepare phase if the participant has

modified data and is prepared to commit or roll back.

requester

The source of a request to access data at a remote server. In the DB2

environment, the requester function is provided by the distributed data

facility.

resource

The object of a lock or claim, which could be a table space, an index space,

a data partition, an index partition, or a logical partition.

resource allocation

The part of plan allocation that deals specifically with the database

resources.

resource control table

A construct of previous versions of the CICS attachment facility that

defines authorization and access attributes for transactions or transaction

groups. Beginning in CICS Transaction Server Version 1.3, resources are

defined by using resource definition online instead of the resource control

table. See also resource definition online.

Glossary 1333

||||||

|||||

resource definition online (RDO)

The recommended method of defining resources to CICS by creating

resource definitions interactively, or by using a utility, and then storing

them in the CICS definition data set. In earlier releases of CICS, resources

were defined by using the resource control table (RCT), which is no longer

supported.

resource limit facility (RLF)

A portion of DB2 code that prevents dynamic manipulative SQL statements

from exceeding specified time limits. The resource limit facility is

sometimes called the governor.

resource limit specification table (RLST)

A site-defined table that specifies the limits to be enforced by the resource

limit facility.

resource manager

v A function that is responsible for managing a particular resource and

that guarantees the consistency of all updates made to recoverable

resources within a logical unit of work. The resource that is being

managed can be physical (for example, disk or main storage) or logical

(for example, a particular type of system service).

v A participant, in the execution of a two-phase commit, that has

recoverable resources that could have been modified. The resource

manager has access to a recovery log so that it can commit or roll back

the effects of the logical unit of work to the recoverable resources.

restart pending (RESTP)

A restrictive state of a page set or partition that indicates that restart

(backout) work needs to be performed on the object.

RESTP

See restart pending.

result set

The set of rows that a stored procedure returns to a client application.

result set locator

A 4-byte value that DB2 uses to uniquely identify a query result set that a

stored procedure returns.

result table

The set of rows that are specified by a SELECT statement.

retained lock

A MODIFY lock that a DB2 subsystem was holding at the time of a

subsystem failure. The lock is retained in the coupling facility lock

structure across a DB2 for z/OS failure.

RID See record identifier.

RID pool

See record identifier pool.

right outer join


that are being joined and preserves the unmatched rows of the second join

operand. See also join, equijoin, full outer join, inner join, left outer join,

and outer join.

RLF See resource limit facility.


|||||

RLST See resource limit specification table.

role A database entity that groups together one or more privileges and that can

be assigned to a primary authorization ID or to PUBLIC. The role is

available only in a trusted context.

rollback

The process of restoring data that was changed by SQL statements to the

state at its last commit point. All locks are freed. Contrast with commit.

root page

The index page that is at the highest level (or the beginning point) in an

index.

routine

A database object that encapsulates procedural logic and SQL statements, is

stored on the database server, and can be invoked from an SQL statement

or by using the CALL statement. The main classes of routines are

procedures and functions.

row The horizontal component of a table. A row consists of a sequence of

values, one for each column of the table.

row identifier (ROWID)

A value that uniquely identifies a row. This value is stored with the row

and never changes.

row lock

A lock on a single row of data.

row-positioned fetch orientation


statement, with respect to a single row (for example, NEXT, LAST, or

ABSOLUTE n). Contrast with rowset-positioned fetch orientation.

rowset

A set of rows for which a cursor position is established.

rowset cursor

A cursor that is defined so that one or more rows can be returned as a

rowset for a single FETCH statement, and the cursor is positioned on the

set of rows that is fetched.

rowset-positioned fetch orientation


statement, with respect to a rowset (for example, NEXT ROWSET, LAST

ROWSET, or ROWSET STARTING AT ABSOLUTE n). Contrast with

row-positioned fetch orientation.

row trigger

A trigger that is defined with the trigger granularity FOR EACH ROW.

RRSAF

See Recoverable Resource Manager Services attachment facility.

RS See read stability.

savepoint

A named entity that represents the state of data and schemas at a

particular point in time within a unit of work.

SBCS See single-byte character set.

SCA See shared communications area.

Glossary 1335

||||

||||

|||

||||

scalar function

An SQL operation that produces a single value from another value and is

expressed as a function name, followed by a list of arguments that are

enclosed in parentheses.

scale In SQL, the number of digits to the right of the decimal point (called the

precision in the C language). The DB2 information uses the SQL definition.

schema

The organization or structure of a database.

A collection of, and a way of qualifying, database objects such as tables,

views, routines, indexes or triggers that define a database. A database

schema provides a logical classification of database objects.

scrollability

The ability to use a cursor to fetch in either a forward or backward

direction. The FETCH statement supports multiple fetch orientations to

indicate the new position of the cursor. See also fetch orientation.

scrollable cursor

A cursor that can be moved in both a forward and a backward direction.

search condition

A criterion for selecting rows from a table. A search condition consists of

one or more predicates.

secondary authorization ID

An authorization ID that has been associated with a primary authorization

ID by an authorization exit routine.

secondary group buffer pool

For a duplexed group buffer pool, the structure that is used to back up

changed pages that are written to the primary group buffer pool. No page

registration or cross-invalidation occurs using the secondary group buffer

pool. The z/OS equivalent is new structure.

secondary index

A nonpartitioning index that is useful for enforcing a uniqueness

constraint, for clustering data, or for providing access paths to data for

queries. A secondary index can be partitioned or nonpartitioned. See also

data-partitioned secondary index (DPSI) and nonpartitioned secondary

index (NPSI).

section

The segment of a plan or package that contains the executable structures

for a single SQL statement. For most SQL statements, one section in the

plan exists for each SQL statement in the source program. However, for

cursor-related statements, the DECLARE, OPEN, FETCH, and CLOSE

statements reference the same section because they each refer to the

SELECT statement that is named in the DECLARE CURSOR statement.

SQL statements such as COMMIT, ROLLBACK, and some SET statements

do not use a section.

security label

A classification of users’ access to objects or data rows in a multilevel

security environment.″

segment

A group of pages that holds rows of a single table. See also segmented

table space.


|||

segmented table space

A table space that is divided into equal-sized groups of pages called

segments. Segments are assigned to tables so that rows of different tables

are never stored in the same segment. Contrast with partitioned table space

and universal table space.

self-referencing constraint

A referential constraint that defines a relationship in which a table is a

dependent of itself.

self-referencing table

A table with a self-referencing constraint.

sensitive cursor

A cursor that is sensitive to changes that are made to the database after the

result table has been materialized.

sequence

A user-defined object that generates a sequence of numeric values

according to user specifications.

sequential data set

A non-DB2 data set whose records are organized on the basis of their

successive physical positions, such as on magnetic tape. Several of the DB2

database utilities require sequential data sets.

sequential prefetch

A mechanism that triggers consecutive asynchronous I/O operations. Pages

are fetched before they are required, and several pages are read with a

single I/O operation.

serialized profile

A Java object that contains SQL statements and descriptions of host

variables. The SQLJ translator produces a serialized profile for each

connection context.

server The target of a request from a remote requester. In the DB2 environment,

the server function is provided by the distributed data facility, which is

used to access DB2 data from remote applications.

service class

An eight-character identifier that is used by the z/OS Workload Manager

to associate user performance goals with a particular DDF thread or stored

procedure. A service class is also used to classify work on parallelism

assistants.

service request block

A unit of work that is scheduled to execute.

session

A link between two nodes in a VTAM network.

session protocols

The available set of SNA communication requests and responses.

set operator

The SQL operators UNION, EXCEPT, and INTERSECT corresponding to

the relational operators union, difference, and intersection. A set operator

derives a result table by combining two other result tables.

shared communications area (SCA)

A coupling facility list structure that a DB2 data sharing group uses for

inter-DB2 communication.

Glossary 1337

|

||||

share lock

A lock that prevents concurrently executing application processes from

changing data, but not from reading data. Contrast with exclusive lock.

shift-in character

A special control character (X’0F’) that is used in EBCDIC systems to

denote that the subsequent bytes represent SBCS characters. See also

shift-out character.

shift-out character

A special control character (X’0E’) that is used in EBCDIC systems to

denote that the subsequent bytes, up to the next shift-in control character,

represent DBCS characters. See also shift-in character.

sign-on

A request that is made on behalf of an individual CICS or IMS application

process by an attachment facility to enable DB2 to verify that it is

authorized to use DB2 resources.

simple page set

A nonpartitioned page set. A simple page set initially consists of a single

data set (page set piece). If and when that data set is extended to 2 GB,

another data set is created, and so on, up to a total of 32 data sets. DB2

considers the data sets to be a single contiguous linear address space

containing a maximum of 64 GB. Data is stored in the next available

location within this address space without regard to any partitioning

scheme.

simple table space

A table space that is neither partitioned nor segmented. Creation of simple

table spaces is not supported in DB2 Version 9.1 for z/OS. Contrast with

partitioned table space, segmented table space, and universal table space.

single-byte character set (SBCS)

A set of characters in which each character is represented by a single byte.

Contrast with double-byte character set or multibyte character set.

single-precision floating point number

A 32-bit approximate representation of a real number.

SMP/E

See System Modification Program/Extended.

SNA See Systems Network Architecture.

SNA network

The part of a network that conforms to the formats and protocols of

Systems Network Architecture (SNA).

socket A callable TCP/IP programming interface that TCP/IP network

applications use to communicate with remote TCP/IP partners.

sourced function

A function that is implemented by another built-in or user-defined function

that is already known to the database manager. This function can be a

scalar function or an aggregate function; it returns a single value from a set

of values (for example, MAX or AVG). Contrast with built-in function,

external function, and SQL function.

source program

A set of host language statements and SQL statements that is processed by

an SQL precompiler.


|||||

source table

A table that can be a base table, a view, a table expression, or a

user-defined table function.

source type

An existing type that DB2 uses to represent a distinct type.

space A sequence of one or more blank characters.

special register

A storage area that DB2 defines for an application process to use for

storing information that can be referenced in SQL statements. Examples of

special registers are SESSION_USER and CURRENT DATE.

specific function name

A particular user-defined function that is known to the database manager

by its specific name. Many specific user-defined functions can have the

same function name. When a user-defined function is defined to the

database, every function is assigned a specific name that is unique within

its schema. Either the user can provide this name, or a default name is

used.

SPUFI See SQL Processor Using File Input.

SQL See Structured Query Language.

SQL authorization ID (SQL ID)

The authorization ID that is used for checking dynamic SQL statements in

some situations.

SQLCA

See SQL communication area.

SQL communication area (SQLCA)

A structure that is used to provide an application program with

information about the execution of its SQL statements.

SQL connection

An association between an application process and a local or remote

application server or database server.

SQLDA

See SQL descriptor area.

SQL descriptor area (SQLDA)

A structure that describes input variables, output variables, or the columns

of a result table.

SQL escape character

The symbol that is used to enclose an SQL delimited identifier. This

symbol is the double quotation mark (″). See also escape character.

SQL function

A user-defined function in which the CREATE FUNCTION statement

contains the source code. The source code is a single SQL expression that

evaluates to a single value. The SQL user-defined function can return the

result of an expression. See also built-in function, external function, and

sourced function.

SQL ID

See SQL authorization ID.

SQLJ Structured Query Language (SQL) that is embedded in the Java

programming language.

Glossary 1339

|||

|||||

SQL path

An ordered list of schema names that are used in the resolution of

unqualified references to user-defined functions, distinct types, and stored

procedures. In dynamic SQL, the SQL path is found in the CURRENT

PATH special register. In static SQL, it is defined in the PATH bind option.

SQL procedure

A user-written program that can be invoked with the SQL CALL statement.

An SQL procedure is written in the SQL procedural language. Two types of

SQL procedures are supported: external SQL procedures and native SQL

procedures. See also external procedure and native SQL procedure.

SQL processing conversation

Any conversation that requires access of DB2 data, either through an

application or by dynamic query requests.

SQL Processor Using File Input (SPUFI)

A facility of the TSO attachment subcomponent that enables the DB2I user

to execute SQL statements without embedding them in an application

program.

SQL return code

Either SQLCODE or SQLSTATE.

SQL routine

A user-defined function or stored procedure that is based on code that is

written in SQL.

SQL schema

A collection of database objects such as tables, views, indexes, functions,

distinct types, schemas, or triggers that defines a database. An SQL schema

provides a logical classification of database objects.

SQL statement coprocessor

An alternative to the DB2 precompiler that lets the user process SQL

statements at compile time. The user invokes an SQL statement coprocessor

by specifying a compiler option.

SQL string delimiter

A symbol that is used to enclose an SQL string constant. The SQL string

delimiter is the apostrophe (’), except in COBOL applications, where the

user assigns the symbol, which is either an apostrophe or a double

quotation mark (″).

SRB See service request block.

stand-alone

An attribute of a program that means that it is capable of executing

separately from DB2, without using DB2 services.

star join

A method of joining a dimension column of a fact table to the key column

of the corresponding dimension table. See also join, dimension, and star

schema.

star schema

The combination of a fact table (which contains most of the data) and a

number of dimension tables. See also star join, dimension, and dimension

table.

statement handle

In DB2 ODBC, the data object that contains information about an SQL


||||

||||

statement that is managed by DB2 ODBC. This includes information such

as dynamic arguments, bindings for dynamic arguments and columns,

cursor information, result values, and status information. Each statement

handle is associated with the connection handle.

statement string

For a dynamic SQL statement, the character string form of the statement.

statement trigger

A trigger that is defined with the trigger granularity FOR EACH

STATEMENT.

static cursor

A named control structure that does not change the size of the result table

or the order of its rows after an application opens the cursor. Contrast with

dynamic cursor.

static SQL

SQL statements, embedded within a program, that are prepared during the

program preparation process (before the program is executed). After being

prepared, the SQL statement does not change (although values of variables

that are specified by the statement might change).

storage group

A set of storage objects on which DB2 for z/OS data can be stored. A

storage object can have an SMS data class, a management class, a storage

class, and a list of volume serial numbers.

stored procedure

A user-written application program that can be invoked through the use of

the SQL CALL statement. Stored procedures are sometimes called

procedures.

string See binary string, character string, or graphic string.

strong typing

A process that guarantees that only user-defined functions and operations

that are defined on a distinct type can be applied to that type. For

example, you cannot directly compare two currency types, such as

Canadian dollars and U.S. dollars. But you can provide a user-defined

function to convert one currency to the other and then do the comparison.

structure

v A name that refers collectively to different types of DB2 objects, such as

tables, databases, views, indexes, and table spaces.

v A construct that uses z/OS to map and manage storage on a coupling

facility. See also cache structure, list structure, or lock structure.

Structured Query Language (SQL)

A standardized language for defining and manipulating data in a relational

database.

structure owner

In relation to group buffer pools, the DB2 member that is responsible for

the following activities:

v Coordinating rebuild, checkpoint, and damage assessment processing

v Monitoring the group buffer pool threshold and notifying castout

owners when the threshold has been reached

Glossary 1341

||||

|||

subcomponent

A group of closely related DB2 modules that work together to provide a

general function.

subject table

The table for which a trigger is created. When the defined triggering event

occurs on this table, the trigger is activated.

subquery

A SELECT statement within the WHERE or HAVING clause of another

SQL statement; a nested SQL statement.

subselect

That form of a query that includes only a SELECT clause, FROM clause,

and optionally a WHERE clause, GROUP BY clause, HAVING clause,

ORDER BY clause, or FETCH FIRST clause.

substitution character

A unique character that is substituted during character conversion for any

characters in the source program that do not have a match in the target

coding representation.

subsystem

A distinct instance of a relational database management system (RDBMS).

surrogate pair

A coded representation for a single character that consists of a sequence of

two 16-bit code units, in which the first value of the pair is a

high-surrogate code unit in the range U+D800 through U+DBFF, and the

second value is a low-surrogate code unit in the range U+DC00 through

U+DFFF. Surrogate pairs provide an extension mechanism for encoding

917 476 characters without requiring the use of 32-bit characters.

SVC dump

A dump that is issued when a z/OS or a DB2 functional recovery routine

detects an error.

sync point

See commit point.

syncpoint tree

The tree of recovery managers and resource managers that are involved in

a logical unit of work, starting with the recovery manager, that make the

final commit decision.

synonym

In SQL, an alternative name for a table or view. Synonyms can be used to

refer only to objects at the subsystem in which the synonym is defined. A

synonym cannot be qualified and can therefore not be used by other users.

Contrast with alias.

Sysplex

See Parallel Sysplex.

Sysplex query parallelism

Parallel execution of a single query that is accomplished by using multiple

tasks on more than one DB2 subsystem. See also query CP parallelism.

system administrator

The person at a computer installation who designs, controls, and manages

the use of the computer system.


|||

||||

system agent

A work request that DB2 creates such as prefetch processing, deferred

writes, and service tasks. See also allied agent.

system authorization ID

The primary DB2 authorization ID that is used to establish a trusted

connection. A system authorization ID is derived from the system user ID

that is provided by an external entity, such as a middleware server.

system conversation

The conversation that two DB2 subsystems must establish to process

system messages before any distributed processing can begin.

System Modification Program/Extended (SMP/E)

A z/OS tool for making software changes in programming systems (such

as DB2) and for controlling those changes.

Systems Network Architecture (SNA)

The description of the logical structure, formats, protocols, and operational

sequences for transmitting information through and controlling the

configuration and operation of networks.

table A named data object consisting of a specific number of columns and some

number of unordered rows. See also base table or temporary table.

Contrast with auxiliary table, clone table, materialized query table, result

table, and transition table.

table-controlled partitioning

A type of partitioning in which partition boundaries for a partitioned table

are controlled by values that are defined in the CREATE TABLE statement.

table function

A function that receives a set of arguments and returns a table to the SQL

statement that references the function. A table function can be referenced

only in the FROM clause of a subselect.

table locator

A mechanism that allows access to trigger tables in SQL or from within

user-defined functions. A table locator is a fullword integer value that

represents a transition table.

table space

A page set that is used to store the records in one or more tables. See also

partitioned table space, segmented table space, and universal table space.

table space set

A set of table spaces and partitions that should be recovered together for

one of the following reasons:

v Each of them contains a table that is a parent or descendent of a table in

one of the others.

v The set contains a base table and associated auxiliary tables.

A table space set can contain both types of relationships.

task control block (TCB)

A z/OS control block that is used to communicate information about tasks

within an address space that is connected to a subsystem. See also address

space connection.

TB Terabyte. A value of 1 099 511 627 776 bytes.

TCB See task control block.

Glossary 1343

||||

|||

TCP/IP

A network communication protocol that computer systems use to exchange

information across telecommunication links.

TCP/IP port

A 2-byte value that identifies an end user or a TCP/IP network application

within a TCP/IP host.

template

A DB2 utilities output data set descriptor that is used for dynamic

allocation. A template is defined by the TEMPLATE utility control

statement.

temporary table

A table that holds temporary data. Temporary tables are useful for holding

or sorting intermediate results from queries that contain a large number of

rows. The two types of temporary table, which are created by different

SQL statements, are the created temporary table and the declared

temporary table. Contrast with result table. See also created temporary

table and declared temporary table.

thread See DB2 thread.

threadsafe

A characteristic of code that allows multithreading both by providing

private storage areas for each thread, and by properly serializing shared

(global) storage areas.

three-part name

The full name of a table, view, or alias. It consists of a location name, a

schema name, and an object name, separated by a period.

time A three-part value that designates a time of day in hours, minutes, and

seconds.

timeout

Abnormal termination of either the DB2 subsystem or of an application

because of the unavailability of resources. Installation specifications are set

to determine both the amount of time DB2 is to wait for IRLM services

after starting, and the amount of time IRLM is to wait if a resource that an

application requests is unavailable. If either of these time specifications is

exceeded, a timeout is declared.

Time-Sharing Option (TSO)

An option in z/OS that provides interactive time sharing from remote

terminals.

timestamp

A seven-part value that consists of a date and time. The timestamp is

expressed in years, months, days, hours, minutes, seconds, and

microseconds.

trace A DB2 facility that provides the ability to monitor and collect DB2

monitoring, auditing, performance, accounting, statistics, and serviceability

(global) data.

transaction

An atomic series of SQL statements that make up a logical unit of work.

All of the data modifications made during a transaction are either

committed together as a unit or rolled back as a unit.


||||

transaction lock

A lock that is used to control concurrent execution of SQL statements.

transaction program name

In SNA LU 6.2 conversations, the name of the program at the remote

logical unit that is to be the other half of the conversation.

transition table

A temporary table that contains all the affected rows of the subject table in

their state before or after the triggering event occurs. Triggered SQL

statements in the trigger definition can reference the table of changed rows

in the old state or the new state. Contrast with auxiliary table, base table,

clone table, and materialized query table.

transition variable

A variable that contains a column value of the affected row of the subject

table in its state before or after the triggering event occurs. Triggered SQL

statements in the trigger definition can reference the set of old values or

the set of new values.

tree structure

A data structure that represents entities in nodes, with a most one parent

node for each node, and with only one root node.

trigger

A database object that is associated with a single base table or view and

that defines a rule. The rule consists of a set of SQL statements that run

when an insert, update, or delete database operation occurs on the

associated base table or view.

trigger activation

The process that occurs when the trigger event that is defined in a trigger

definition is executed. Trigger activation consists of the evaluation of the

triggered action condition and conditional execution of the triggered SQL

statements.

trigger activation time

An indication in the trigger definition of whether the trigger should be

activated before or after the triggered event.

trigger body

The set of SQL statements that is executed when a trigger is activated and

its triggered action condition evaluates to true. A trigger body is also called

triggered SQL statements.

trigger cascading

The process that occurs when the triggered action of a trigger causes the

activation of another trigger.

triggered action

The SQL logic that is performed when a trigger is activated. The triggered

action consists of an optional triggered action condition and a set of

triggered SQL statements that are executed only if the condition evaluates

to true.

triggered action condition

An optional part of the triggered action. This Boolean condition appears as

a WHEN clause and specifies a condition that DB2 evaluates to determine

if the triggered SQL statements should be executed.

Glossary 1345

||||

triggered SQL statements

The set of SQL statements that is executed when a trigger is activated and

its triggered action condition evaluates to true. Triggered SQL statements

are also called the trigger body.

trigger granularity

In SQL, a characteristic of a trigger, which determines whether the trigger

is activated:

v Only once for the triggering SQL statement

v Once for each row that the SQL statement modifies

triggering event

The specified operation in a trigger definition that causes the activation of

that trigger. The triggering event is comprised of a triggering operation

(insert, update, or delete) and a subject table or view on which the

operation is performed.

triggering SQL operation

The SQL operation that causes a trigger to be activated when performed on

the subject table or view.

trigger package

A package that is created when a CREATE TRIGGER statement is

executed. The package is executed when the trigger is activated.

trust attribute

An attribute on which to establish trust. A trusted relationship is

established based on one or more trust attributes.

trusted connection

A database connection whose attributes match the attributes of a unique

trusted context defined at the DB2 database server.

trusted connection reuse

The ability to switch the current user ID on a trusted connection to a

different user ID.

trusted context

A database security object that enables the establishment of a trusted

relationship between a DB2 database management system and an external

entity.

trusted context default role

A role associated with a trusted context. The privileges granted to the

trusted context default role can be acquired only when a trusted

connection based on the trusted context is established or reused.

trusted context user

A user ID to which switching the current user ID on a trusted connection

is permitted.

trusted context user-specific role

A role that is associated with a specific trusted context user. It overrides

the trusted context default role if the current user ID on the trusted

connection matches the ID of the specific trusted context user.

trusted relationship

A privileged relationship between two entities such as a middleware server

and a database server. This relationship allows for a unique set of

interactions between the two entities that would be impossible otherwise.

TSO See Time-Sharing Option.


||||

||

|||

|||

|||

||||

||||

|||

||||

||||

TSO attachment facility

A DB2 facility consisting of the DSN command processor and DB2I.

Applications that are not written for the CICS or IMS environments can

run under the TSO attachment facility.

typed parameter marker

A parameter marker that is specified along with its target data type. It has

the general form:

CAST(? AS data-type)

type 2 indexes

Indexes that are created on a release of DB2 after Version 7 or that are

specified as type 2 indexes in Version 4 or later.

UCS-2 Universal Character Set, coded in 2 octets, which means that characters are

represented in 16-bits per character.

UDF See user-defined function.

UDT User-defined data type. In DB2 for z/OS, the term distinct type is used

instead of user-defined data type. See distinct type.

uncommitted read (UR)

The isolation level that allows an application to read uncommitted data.

See also cursor stability, read stability, and repeatable read.

underlying view

The view on which another view is directly or indirectly defined.

undo A state of a unit of recovery that indicates that the changes that the unit of

recovery made to recoverable DB2 resources must be backed out.

Unicode

A standard that parallels the ISO-10646 standard. Several implementations

of the Unicode standard exist, all of which have the ability to represent a

large percentage of the characters that are contained in the many scripts

that are used throughout the world.

union An SQL operation that involves the UNION set operator, which combines

the results of two SELECT statements. Unions are often used to merge lists

of values that are obtained from two tables.

unique constraint

An SQL rule that no two values in a primary key, or in the key of a unique

index, can be the same.

unique index

An index that ensures that no identical key values are stored in a column

or a set of columns in a table.

unit of recovery (UOR)

A recoverable sequence of operations within a single resource manager,

such as an instance of DB2. Contrast with unit of work.

unit of work (UOW)

A recoverable sequence of operations within an application process. At any

time, an application process is a single unit of work, but the life of an

application process can involve many units of work as a result of commit

or rollback operations. In a multisite update operation, a single unit of

work can include several units of recovery. Contrast with unit of recovery.

universal table space

A table space that is both segmented and partitioned. Contrast with

Glossary 1347

|||

||

partitioned table space, segmented table space, partition-by-growth table

space, and range-partitioned table space.

unlock

The act of releasing an object or system resource that was previously

locked and returning it to general availability within DB2.

untyped parameter marker

A parameter marker that is specified without its target data type. It has the

form of a single question mark (?).

updatability

The ability of a cursor to perform positioned updates and deletes. The

updatability of a cursor can be influenced by the SELECT statement and

the cursor sensitivity option that is specified on the DECLARE CURSOR

statement.

update hole

The location on which a cursor is positioned when a row in a result table

is fetched again and the new values no longer satisfy the search condition.

See also delete hole.

update trigger

A trigger that is defined with the triggering SQL operation update.

UR See uncommitted read.

user-defined data type (UDT)

See distinct type.

user-defined function (UDF)

A function that is defined to DB2 by using the CREATE FUNCTION

statement and that can be referenced thereafter in SQL statements. A

user-defined function can be an external function, a sourced function, or an

SQL function. Contrast with built-in function.

user view

In logical data modeling, a model or representation of critical information

that the business requires.

UTF-8 Unicode Transformation Format, 8-bit encoding form, which is designed

for ease of use with existing ASCII-based systems. The CCSID value for

data in UTF-8 format is 1208. DB2 for z/OS supports UTF-8 in mixed data

fields.

UTF-16

Unicode Transformation Format, 16-bit encoding form, which is designed

to provide code values for over a million characters and a superset of

UCS-2. The CCSID value for data in UTF-16 format is 1200. DB2 for z/OS

supports UTF-16 in graphic data fields.

value The smallest unit of data that is manipulated in SQL.

variable

A data element that specifies a value that can be changed. A COBOL

elementary data item is an example of a host variable. Contrast with

constant.

variant function

See nondeterministic function.


||

varying-length string

A character, graphic, or binary string whose length varies within set limits.

Contrast with fixed-length string.

version

A member of a set of similar programs, DBRMs, packages, or LOBs.

v A version of a program is the source code that is produced by

precompiling the program. The program version is identified by the

program name and a timestamp (consistency token).

v A version of an SQL procedural language routine is produced by

issuing the CREATE or ALTER PROCEDURE statement for a native SQL

procedure.

v A version of a DBRM is the DBRM that is produced by precompiling a

program. The DBRM version is identified by the same program name

and timestamp as a corresponding program version.

v A version of an application package is the result of binding a DBRM

within a particular database system. The application package version is

identified by the same program name and consistency token as the

DBRM.

v A version of a LOB is a copy of a LOB value at a point in time. The

version number for a LOB is stored in the auxiliary index entry for the

LOB.

v A version of a record is a copy of the record at a point in time.

view A logical table that consists of data that is generated by a query. A view

can be based on one or more underlying base tables or views, and the data

in a view is determined by a SELECT statement that is run on the

underlying base tables or views.

Virtual Storage Access Method (VSAM)

An access method for direct or sequential processing of fixed- and

varying-length records on disk devices.

Virtual Telecommunications Access Method (VTAM)

An IBM licensed program that controls communication and the flow of

data in an SNA network (in z/OS).

volatile table

A table for which SQL operations choose index access whenever possible.

VSAM

See Virtual Storage Access Method.

VTAM

See Virtual Telecommunications Access Method.

warm start

The normal DB2 restart process, which involves reading and processing log

records so that data that is under the control of DB2 is consistent. Contrast

with cold start.

WLM application environment

A z/OS Workload Manager attribute that is associated with one or more

stored procedures. The WLM application environment determines the

address space in which a given DB2 stored procedure runs.

WLM enclave

A construct that can span multiple dispatchable units (service request

Glossary 1349

||

|

|||

|||

|||

||||

|||

|

||||

||

||

blocks and tasks) in multiple address spaces, allowing them to be reported

on and managed by WLM as part of a single work request.

write to operator (WTO)

An optional user-coded service that allows a message to be written to the

system console operator informing the operator of errors and unusual

system conditions that might need to be corrected (in z/OS).

WTO See write to operator.

WTOR

Write to operator (WTO) with reply.

XCF See cross-system coupling facility.

XES See cross-system extended services.

XML See Extensible Markup Language.

XML attribute

A name-value pair within a tagged XML element that modifies certain

features of the element.

XML column

A column of a table that stores XML values and is defined using the data

type XML. The XML values that are stored in XML columns are internal

representations of well-formed XML documents.

XML data type

A data type for XML values.

XML element

A logical structure in an XML document that is delimited by a start and an

end tag. Anything between the start tag and the end tag is the content of

the element.

XML index

An index on an XML column that provides efficient access to nodes within

an XML document by providing index keys that are based on XML

patterns.

XML lock

A column-level lock for XML data. The operation of XML locks is similar

to the operation of LOB locks.

XML node

The smallest unit of valid, complete structure in a document. For example,

a node can represent an element, an attribute, or a text string.

XML node ID index

An implicitly created index, on an XML table that provides efficient access

to XML documents and navigation among multiple XML data rows in the

same document.

XML pattern

A slash-separated list of element names, an optional attribute name (at the

end), or kind tests, that describe a path within an XML document in an

XML column. The pattern is a restrictive form of path expressions, and it

selects nodes that match the specifications. XML patterns are specified to

create indexes on XML columns in a database.

XML publishing function

A function that returns an XML value from SQL values. An XML

publishing function is also known as an XML constructor.


||

||||

||

||||

|||

||||

||||||

||

XML schema

In XML, a mechanism for describing and constraining the content of XML

files by indicating which elements are allowed and in which combinations.

XML schemas are an alternative to document type definitions (DTDs) and

can be used to extend functionality in the areas of data typing, inheritance,

and presentation.

XML schema repository (XSR)

A repository that allows the DB2 database system to store XML schemas.

When registered with the XSR, these objects have a unique identifier and

can be used to validate XML instance documents.

XML serialization function

A function that returns a serialized XML string from an XML value.

XML table

An auxiliary table that is implicitly created when an XML column is added

to a base table. This table stores the XML data, and the column in the base

table points to it.

XML table space

A table space that is implicitly created when an XML column is added to a

base table. The table space stores the XML table. If the base table is

partitioned, one partitioned table space exists for each XML column of

data.

X/Open

An independent, worldwide open systems organization that is supported

by most of the world’s largest information systems suppliers, user

organizations, and software companies. X/Open’s goal is to increase the

portability of applications by combining existing and emerging standards.

XRF See Extended Recovery Facility.

XSR See XML schema repository.

zIIP See IBM System z9 Integrated Processor.

z/OS An operating system for the System z product line that supports 64-bit real

and virtual storage.

z/OS Distributed Computing Environment (z/OS DCE)

A set of technologies that are provided by the Open Software Foundation

to implement distributed computing.

Glossary 1351

||||||

||||

||

||||

|

||

||


Information resources for DB2 for z/OS and related products

Many information resources are available to help you use DB2 for z/OS and many

related products. A large amount of technical information about IBM products is

now available online in information centers or on library Web sites.

Disclaimer: Any Web addresses that are included here are accurate at the time this

information is being published. However, Web addresses sometimes

change. If you visit a Web address that is listed here but that is no

longer valid, you can try to find the current Web address for the

product information that you are looking for at either of the following

sites:

v http://www.ibm.com/support/publications/us/library/index.shtml, which lists the IBM information centers that are

available for various IBM products

v http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi, which is the IBM Publications Center,

where you can download online PDF books or order printed books

for various IBM products

DB2 for z/OS product information

The primary place to find and use information about DB2 for z/OS is the

Information Management Software for z/OS Solutions Information Center

(http://publib.boulder.ibm.com/infocenter/imzic), which also contains information

about IMS, QMF, and many DB2 and IMS Tools products. The majority of the DB2

for z/OS information in this information center is also available in the books that

are identified in the following table. You can access these books at the DB2 for

z/OS library Web site (http://www.ibm.com/software/data/db2/zos/library.html)

or at the IBM Publications Center (http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi).

Table 257. DB2 Version 9.1 for z/OS book titles

Title

Publication

number

Available in

information

center

Available in

PDF

Available in

BookManager®

format

Available in

printed book

DB2 Version 9.1 for z/OS

Administration Guide

SC18-9840 X X X X

DB2 Version 9.1 for z/OS Application

Programming & SQL Guide

SC18-9841 X X X X

DB2 Version 9.1 for z/OS Application

Programming Guide and Reference for

Java

SC18-9842 X X X X

DB2 Version 9.1 for z/OS Codes GC18-9843 X X X X

DB2 Version 9.1 for z/OS Command

Reference

SC18-9844 X X X X

DB2 Version 9.1 for z/OS Data Sharing:

Planning and Administration

SC18-9845 X X X X

DB2 Version 9.1 for z/OS Diagnosis

Guide and Reference

1

LY37-3218 X X X


http://www.ibm.com/support/publications/us/library/index.shtml

http://www.ibm.com/support/publications/us/library/index.shtml

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi


http://publib.boulder.ibm.com/infocenter/imzic

http://www.ibm.com/software/data/db2/zos/library.html



Table 257. DB2 Version 9.1 for z/OS book titles (continued)

Title

Publication

number

Available in

information

center

Available in

PDF

Available in

BookManager®

format

Available in

printed book

DB2 Version 9.1 for z/OS Diagnostic

Quick Reference

LY37-3219 X

DB2 Version 9.1 for z/OS Installation

Guide

GC18-9846 X X X X

DB2 Version 9.1 for z/OS Introduction to

DB2

SC18-9847 X X X X

DB2 Version 9.1 for z/OS Licensed

Program Specifications

GC18-9848 X X

DB2 Version 9.1 for z/OS Messages GC18-9849 X X X X

DB2 Version 9.1 for z/OS ODBC Guide

and Reference

SC18-9850 X X X X

DB2 Version 9.1 for z/OS Performance

Monitoring and Tuning Guide

SC18-9851 X X X X

DB2 Version 9.1 for z/OS Optimization

Service Center

X

DB2 Version 9.1 for z/OS Program

Directory

GI10-8737 X X

DB2 Version 9.1 for z/OS RACF Access

Control Module Guide

SC18-9852 X X

DB2 Version 9.1 for z/OS Reference for

Remote DRDA Requesters and Servers

SC18-9853 X X X

DB2 Version 9.1 for z/OS Reference

Summary

2

SX26-3854

DB2 Version 9.1 for z/OS SQL Reference SC18-9854 X X X X

DB2 Version 9.1 for z/OS Utility Guide

and Reference

SC18-9855 X X X X

DB2 Version 9.1 for z/OS What’s New? GC18-9856 X X X X

DB2 Version 9.1 for z/OS XML Extender

Administration and Programming

SC18-9857 X X X X

DB2 Version 9.1 for z/OS XML Guide SC18-9858 X X X X

Notes:

1. DB2 Version 9.1 for z/OS Diagnosis Guide and Reference is available in PDF

and BookManager formats on the DB2 Version 9.1 for z/OS Licensed

Collection kit, LK3T-7195. You can order this License Collection kit on

the IBM Publications Center site (http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi). This book is also

available in online format in DB2 data set DSN910.SDSNIVPD(DSNDR).

2. DB2 Version 9.1 for z/OS Reference Summary will be available in 2007.

Information resources for related products

In the following table, related product names are listed in alphabetic order, and the

associated Web addresses of product information centers or library Web pages are

indicated.




Table 258. Related product information resource locations

Related product Information resources

C/C++ for z/OS Library Web site: http://www.ibm.com/software/awdtools/czos/library/

This product is now called z/OS XL C/C++.

CICS Transaction Server for

z/OS

Information center: http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp

COBOL Information center: http://publib.boulder.ibm.com/infocenter/pdthelp/v1r1/index.jsp

This product is now called Enterprise COBOL for z/OS.

DB2 Connect™ Information center: http://publib.boulder.ibm.com/infocenter/db2luw/v9//index.jsp

This resource is for DB2 Connect 9.

DB2 Database for Linux,

UNIX, and Windows

Information center: http://publib.boulder.ibm.com/infocenter/db2luw/v9//index.jsp

This resource is for DB2 9 for Linux, UNIX, and Windows.

DB2 Performance Expert

for z/OS

Information center: http://publib.boulder.ibm.com/infocenter/imzic

This product is now called DB2 Tivoli OMEGAMON® for XE Performance Expert on

z/OS.

DB2 Query Management

Facility

Information center: http://publib.boulder.ibm.com/infocenter/imzic

DB2 Server for VSE & VM

VSE

One of the following locations:

v For VSE: http://www.ibm.com/support/docview.wss?rs=66&uid=swg27003758

v For VM: http://www.ibm.com/support/docview.wss?rs=66&uid=swg27003759

DB2 Tools One of the following locations:

v Information center: http://publib.boulder.ibm.com/infocenter/imzic

v Library Web site: http://www.ibm.com/software/data/db2imstools/library.html

These resources include information about the following products and others:

v DB2 Administration Tool

v DB2 Automation Tool

v DB2 DataPropagator (also known as WebSphere Replication Server for z/OS)

v DB2 Log Analysis Tool

v DB2 Object Restore Tool

v DB2 Query Management Facility

v DB2 SQL Performance Analyzer

v DB2 Tivoli OMEGAMON for XE Performance Expert on z/OS (includes Buffer Pool

Analyzer and Performance Monitor)

DB2 Universal Database

for iSeries

Information center: http://www.ibm.com/systems/i/infocenter/

Debug Tool for z/OS Information center: http://publib.boulder.ibm.com/infocenter/pdthelp/v1r1/index.jsp

Enterprise COBOL for

z/OS

Information center: http://publib.boulder.ibm.com/infocenter/pdthelp/v1r1/index.jsp

Enterprise PL/I for z/OS Information center: http://publib.boulder.ibm.com/infocenter/pdthelp/v1r1/index.jsp

IMS Information center: http://publib.boulder.ibm.com/infocenter/imzic

Information resources for DB2 for z/OS and related products 1355

http://www.ibm.com/software/awdtools/czos/library/

http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp

http://publib.boulder.ibm.com/infocenter/pdthelp/v1r1/index.jsp

http://publib.boulder.ibm.com/infocenter/db2luw/v9//index.jsp

http://publib.boulder.ibm.com/infocenter/db2luw/v9//index.jsp



http://www.ibm.com/support/docview.wss?rs=66&uid=swg27003758

http://www.ibm.com/support/docview.wss?rs=66&uid=swg27003759


http://www.ibm.com/software/data/db2imstools/library.html

http://www.ibm.com/systems/i/infocenter/





Table 258. Related product information resource locations (continued)


IMS Tools One of the following locations:



These resources have information about the following products and others:

v IMS Batch Terminal Simulator for z/OS

v IMS Connect

v IMS HALDB Conversion and Maintenance Aid

v IMS High Performance Utility products

v IMS DataPropagator

v IMS Online Reorganization Facility

v IMS Performance Analyzer

PL/I Information center: http://publib.boulder.ibm.com/infocenter/pdthelp/v1r1/index.jsp

This product is now called Enterprise PL/I for z/OS.

System z http://publib.boulder.ibm.com/infocenter/eserver/v1r2/index.jsp

WebSphere Application

Server

Information center: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp

WebSphere Message Broker

with Rules and Formatter

Extension

Information center: http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/index.jsp

The product is also known as WebSphere MQ Integrator Broker.

WebSphere MQ Information center: http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp

The resource includes information about MQSeries.

WebSphere Replication

Server for z/OS

Either of the following locations:



This product is also known as DB2 DataPropagator.

z/Architecture Library Center site: http://www.ibm.com/servers/eserver/zseries/zos/bkserv/





http://publib.boulder.ibm.com/infocenter/eserver/v1r2/index.jsp

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/index.jsp

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/index.jsp

http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp



http://www.ibm.com/servers/eserver/zseries/zos/bkserv/

Table 258. Related product information resource locations (continued)


z/OS Library Center site: http://www.ibm.com/servers/eserver/zseries/zos/bkserv/

This resource includes information about the following z/OS elements and components:

v Character Data Representation Architecture

v Device Support Facilities

v DFSORT™

v Fortran

v High Level Assembler

v NetView®

v SMP/E for z/OS

v SNA

v TCP/IP

v TotalStorage® Enterprise Storage Server®

v VTAM

v z/OS C/C++

v z/OS Communications Server

v z/OS DCE

v z/OS DFSMS

v z/OS DFSMS Access Method Services

v z/OS DFSMSdss™

v z/OS DFSMShsm™

v z/OS DFSMSdfp

v z/OS ICSF

v z/OS ISPF

v z/OS JES3

v z/OS Language Environment

v z/OS Managed System Infrastructure

v z/OS MVS

v z/OS MVS JCL

v z/OS Parallel Sysplex

v z/OS RMF™

v z/OS Security Server

v z/OS UNIX System Services

z/OS XL C/C++ http://www.ibm.com/software/awdtools/czos/library/

The following information resources from IBM are not necessarily specific to a

single product:

v The DB2 for z/OS Information Roadmap; available at: http://www.ibm.com/software/data/db2/zos/roadmap.html

v DB2 Redbooks™ and Redbooks about related products; available at:

http://www.ibm.com/redbooks

v IBM Educational resources:

– Information about IBM educational offerings is available on the Web at:

http://www.ibm.com/software/sw-training/

Information resources for DB2 for z/OS and related products 1357

http://www.ibm.com/servers/eserver/zseries/zos/bkserv/

http://www.ibm.com/software/awdtools/czos/library/

http://www.ibm.com/software/data/db2/zos/roadmap.html

http://www.ibm.com/software/data/db2/zos/roadmap.html

http://www.ibm.com/redbooks

http://www.ibm.com/software/sw-training/

– A collection of glossaries of IBM terms in multiple languages is available on

the IBM Terminology Web site at: http://www.ibm.com/ibm/terminology/index.html

v National Language Support information; available at the IBM Publications

Center at: http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

v SQL Reference for Cross-Platform Development; available at the following

developerWorks® site: http://www.ibm.com/developerworks/db2/library/techarticle/0206sqlref/0206sqlref.html

The following information resources are not published by IBM but can be useful to

users of DB2 for z/OS and related products:

v Database design topics:

– DB2 for z/OS and OS/390 Development for Performance Volume I, by Gabrielle

Wiorkowski, Gabrielle & Associates, ISBN 0-96684-605-2

– DB2 for z/OS and OS/390 Development for Performance Volume II, by Gabrielle

Wiorkowski, Gabrielle & Associates, ISBN 0-96684-606-0

– Handbook of Relational Database Design, by C. Fleming and B. Von Halle,

Addison Wesley, ISBN 0-20111-434-8v Distributed Relational Database Architecture (DRDA) specifications;

http://www.opengroup.org

v Domain Name System: DNS and BIND, Third Edition, Paul Albitz and Cricket

Liu, O’Reilly, ISBN 0-59600-158-4

v Microsoft Open Database Connectivity (ODBC) information;

http://msdn.microsoft.com/library/

v Unicode information; http://www.unicode.org


http://www.ibm.com/ibm/terminology/index.html

http://www.ibm.com/ibm/terminology/index.html



http://www.ibm.com/developerworks/db2/library/techarticle/0206sqlref/0206sqlref.html

http://www.ibm.com/developerworks/db2/library/techarticle/0206sqlref/0206sqlref.html

http://www.opengroup.org

http://msdn.microsoft.com/library/

http://www.unicode.org

Index

Special characters_ (underscore)

assembler host variable 169

: (colon)assembler host variable 171

C host variable 188

COBOL 226

Fortran host variable 262

PL/I host variable 273

’ (apostrophe)string delimiter precompiler option 550

Numerics31-bit addressing 615

Aabend

before commit point 497

DB2 971, 1003

effect on cursor position 148

exit routines 986

for synchronization calls 646

IMSU0102 651

U0775 499

U0778 500, 501

multiple-mode program 496

program 494

reason codes 987

return code posted to CAF CONNECT 973

return code posted to RRSAF CONNECT 1006

single-mode program 496

systemX″04E″ 643

ABRT parameter of CAF (call attachment facility) 979, 988

access pathaffects lock attributes 482

direct row access 314, 901

index-only access 900

low cluster ratiosuggests table space scan 909

with list prefetch 935

multiple index accessdescription 913

PLAN_TABLE 897

selectioninfluencing with SQL 874

problems 827

queries containing host variables 859

Visual Explain 874, 889

table space scan 909

unique index with matching value 915

accessibility xxiii

keyboard xxiii

shortcut keys xxiii

ACQUIREoption of BIND PLAN subcommand

locking tables and table spaces 467

activity sample table 1083

address spaceexamples 1036

initializationCAF CONNECT command 975

CAF OPEN command 977

sample scenarios 984

separate tasks 964, 996

terminationCAF CLOSE command 980

CAF DISCONNECT command 981

ALIASESoption of DSNTP2DP tool 509

ALL quantified predicate 72

ALLOCATE CURSOR statement 800

ambiguous cursor 478

AMODE link-edit option 561, 615

ANY quantified predicate 72

APOST precompiler option 550

application planbinding 567

creating 561

dynamic plan selection for CICS applications 576

invalidated 447

listing packages 567

rebinding 446

using packages 442

application programbill of materials 1191

coding SQL statementsassembler 167

coding conventions 100

data declarations 155

data entry 42

description 99

dynamic SQL 661, 699

host variables 102

selecting rows using a cursor 125

design considerationsbind 439

CAF 964

checkpoint 645

IMS calls 645

planning for changes 444

precompile 439

programming for DL/I batch 644

RRSAF 996

SQL statements 645

stored procedures 701

structure 959

synchronization call abends 646

using ISPF (interactive system productivity

facility) 587

XRST call 645

duplicate CALL statements 812

external stored procedures 757

object extensions 341

preparationassembling 560

binding 442, 561

compiling 560

© Copyright IBM Corp. 1983, 2007 X-1

application program (continued)preparation (continued)

DB2 precompiler option defaults 558

defining to CICS 560

DRDA access 514

example 590

link-editing 560

precompiler option defaults 542

precompiler options 441

preparing for running 541

program preparation panel 587

using DB2 coprocessor 440

using DB2 precompiler 439

using DB2I (DB2 Interactive) 587

runningCAF (call attachment facility) 965

CICS 581

IMS 581

program synchronization in DL/I batch 645

TSO 578

TSO CLIST 580

suspensiondescription 452

test environment 627

testing 627

arithmetic expressions in UPDATE statement 44

AS clausenaming columns for view 9

naming columns in union 9

naming derived columns 10

naming result columns 9

ORDER BY name 8

with ORDER BY clause 13

ASCII data, retrieving 688

assembler application programassembling 560

binary host variable 173

character host variable 172

coding SQL statements 167

data type compatibility 181

data types 175

declaring tables 169

declaring views 169

fixed-length character string 173

graphic host variable 173

host variabledeclaring 171

naming convention 169

INCLUDE statement 169

including SQLCA 168

including SQLDA 168

indicator variable 182

LOB variable 174

numeric host variable 171

reentrant 170

result set locator 174

ROWID variable 175

SQLCODE 167

SQLSTATE 167

table locator 174

varbinary host variable 174

variable declaration 180

varying-length character string 173

assignment, compatibility rules 4

ASSOCIATE LOCATORS statement 799

ATTACH optionCAF 969

ATTACH option (continued)precompiler 969, 1002

RRSAF 1002

ATTACH precompiler option 551

attention processing 964, 985, 996

AUTH SIGNON, RRSAFsyntax 1016

usage 1016

authorityauthorization ID 580

creating test tables 629

SYSIBM.SYSTABAUTH table 28

AUTOCOMMIT field of SPUFI panel 81

automaticrebind

EXPLAIN processing 895

automatic query rewrite 311

automatic rebindconditions for 448

invalid plan or package 447

SQLCA not available 449

auxiliary tableLOCK TABLE statement 487, 491

Bbatch processing

access to DB2 and DL/I togetherbinding a plan 649

checkpoint calls 645

commits 645

precompiling 648

batch DB2 applicationrunning 579

starting with a CLIST 580

bill of materials applications 1191

binary host variableassembler 173

C 195

COBOL 232

PL/I 275

binary large object (BLOB) 343

BINARY variable arrayC 202

BINDcommand line processor command 564

BIND COPYfor native SQL procedures 728

BIND COPY REPLACEfor native SQL procedures 729

BIND PACKAGE subcommand of DSNoptions

CURRENTDATA 516

DBPROTOCOL 516

ENCODING 517

ISOLATION 471

KEEPDYNAMIC 668

location-name 516

OPTIONS 516

RELEASE 467

REOPT(ALWAYS) 859

REOPT(NONE) 859

REOPT(ONCE) 859

SQLERROR 516

options associated with DRDA access 516, 517

remote 563

X-2 Application Programming and SQL Guide

BIND PLAN subcommand of DSNoptions

ACQUIRE 467

CACHESIZE 574

CURRENTDATA 515

DBPROTOCOL 515

DISCONNECT 515

ENCODING 516

ISOLATION 471

KEEPDYNAMIC 668

RELEASE 467

REOPT(ALWAYS) 859

REOPT(NONE) 859

REOPT(ONCE) 859

SQLRULES 515, 575

options associated with DRDA access 515

remote 563

bindingadvantages of packages 443

application plans 561

changes that require 444

checking BIND PACKAGE options 517

DBRMs precompiled elsewhere 543

methodDBRMs and package list 443

DBRMs into single plan 443

package list only 442

options associated with DRDA access 516

options for 442

packagesdeciding how to use 442

in use 442

remote 562

planning for 442

plans 567

in use 442

remote package requirements 562

specify SQL rules 575

block fetchconditions for use by non-scrollable cursor 529

conditions for use by scrollable cursor 529

preventing 537

using 528

with cursor stability 537

BMP (batch message processing) programcheckpoints 498, 499

transaction-oriented 498

BTS (batch terminal simulator) 632

CC application program



LOB variable 197

LOB variable array 204


numeric host variable array 199


sample application 1103

C/C++ application programBINARY variable array 202


character host variable array 200


constants 215


C/C++ application program (continued)data types 208

DCLGEN support 160

declaring views 187

examples 1137

fixed-length string 217


graphic host variable array 202

host variable array, declaring 188

host variable, declaring 188


including SQLCA 185

including SQLDA 186


indicator variable array 217



ROWID variable 199

ROWID variable array 205

SQLCODE 185

SQLSTATE 185

table locator 196

VARBINARY variable array 202


varying-length string 217

with classes, preparing 586

cachedynamic SQL

effect of RELEASE(DEALLOCATE) 468

cache (dynamic SQL)statements 665

CACHESIZEoption of BIND PLAN subcommand 574

REBIND subcommand 574

CAF (call attachment facility)application program

examples 987

preparation 964

connecting to DB2 988

description 963

function descriptions 971

load module structure 966

parameters 971

programming language 964

register conventions 971

restrictions 963

return codeschecking 990

CLOSE 979

CONNECT 973

DISCONNECT 980

OPEN 977

TRANSLATE 982

run environment 965

running an application program 965

calculated valuesgroups with conditions 14

summarizing group values 14

call attachment facility (CAF) 963

CALL DSNALI statement 971, 983

CALL DSNRLI statement 1005

CALL statementcommand line processor 815

example 771

multiple 812

SQL procedure 731

Index X-3

cardinality of user-defined table functionimproving query performance 878

Cartesian join 920

CASE statement (SQL procedure) 732

catalog statisticsinfluencing access paths 884

catalog tableaccessing 28

SYSIBM.LOCATIONS 520

SYSIBM.SYSCOLUMNS 28

SYSIBM.SYSTABAUTH 28

CCSID (coded character set identifier)controlling in COBOL programs 251

effect of DECLARE VARIABLE 107

host variable 107

precompiler option 551

SQLDA 687

character host variableassembler 172

C 191

COBOL 228

Fortran 263

PL/I 274

character host variable arrayC 200

COBOL 236

PL/I 279

character large object (CLOB) 343

character stringliterals 100

mixed data 4

width of column in results 86, 93

check constraintcheck integrity 304

considerations 303

CURRENT RULES special register effect 304

defining 303

description 303

determining violations 1079

enforcement 304

programming considerations 1079

CHECK-pending status 304

checkpointcalls 496, 498

frequency 500

CHKP call, IMS 495, 497

CICSattachment facility

controlling from applications 1043


DSNTIAC subroutineassembler 184

C 220

COBOL 258

PL/I 293

environment planning 581

facilitiescommand language translator 559

control areas 627

EDF (execution diagnostic facility) 633

language interface module (DSNCLI)use in link-editing an application 561

logical unit of work 494

operatingindoubt data 495

running a program 627

system failure 495

CICS (continued)preparing with JCL procedures 585

programmingDFHEIENT macro 170

sample applications 1105, 1108

SYNCPOINT command 495

storage handlingassembler 184

C 220

COBOL 258

PL/I 293

sync point 495

thread reuse 1043

unit of work 494

claimeffect of cursor WITH HOLD 480

CLOSEstatement

description 130

recommendation 135

WHENEVER NOT FOUND clause 681, 694

CLOSE (connection function of CAF)description 968

language examples 980

program example 988

syntax 979

syntax usage 979

cluster ratioeffects


with list prefetch 935

COALESCE function 61

COBOL application programassignment rules 252



fixed-length string 228

varying-length string 229


fixed-length string array 236

varying-length string array 237


compiling 560

controlling CCSID 251


data types 247

DB2 precompiler option defaults 558

DCLGEN support 160


declaring views 223

defining the SQLDA 222

dynamic SQL 699

FILLER entry name 253



host variabledeclaring 226

use of hyphens 225

host variable arraydeclaring 226


including SQLCA 221



LOB variable 233




COBOL application program (continued)numeric host variable 227


object-oriented extensions 258

options 224, 225

preparation 560

record description from DCLGEN 159

resetting SQL-INIT-FLAG 226


ROWID variable 234

ROWID variable array 241

sample program 1125

SQLCODE 220

SQLSTATE 220

table locator 233


WHENEVER statement 224

with classes, preparing 586

coding SQL statementsassembler 167

C 185

C++ 185

COBOL 220

dynamic 661

Fortran 259

PL/I 269

REXX 293

collection, packageidentifying 568

SET CURRENT PACKAGESET statement 568

colonassembler host variable 171

C host variable 188

C host variable array 188

COBOL host variable 226

Fortran host variable 262

PL/I host variable 273

PL/I host variable array 273

preceding a host variable 102

preceding a host variable array 108

columndata types 4

default valuesystem-defined 31

user-defined 32

displaying, list of 28

heading created by SPUFI 94

labelsDCLGEN 158

labels, usage 690

nameas a host variable 158

name, with UPDATE statement 44

retrieving, with SELECT 6

specified in CREATE TABLE 31

width of results 86, 93

COMMA precompiler option 551

command line processorbinding 564

CALL statement 815


commit pointdescription 494

IMS unit of work 496

lock release 496

COMMIT statementdescription 81

COMMIT statement (continued)ending unit of work 494

in a stored procedure 769

when to issue 494

commit, using RRSAF 997

common table expressionsdescription 24

examples 1191

in a CREATE VIEW statement 25

in a SELECT statement 24

in an INSERT statement 25

infinite loops 26

recursion 1191

comparisoncompatibility rules 4

operator, subquery 71

compatibilitydata types 4

locks 465

rules 4

complex triggerWHEN clause 908

composite key 306

compound statementexample

dynamic SQL 756

nested IF and WHILE statements 755

EXIT handler 735

labels 734

SQL procedure 732

valid SQL statements 733

compound statementsnested 743

within the declaration of a condition handler 745

concurrencycontrol by locks 452

description 451

effect ofISOLATION options 475

lock size 463

uncommitted read 473

recommendations 455

condition handlersempty 738

conditionsignoring 738

CONNECTstatement

SPUFI 82

CONNECT (connection function of CAF)description 968


program example 988

syntax 973

CONNECT (Type 1) statement 523

CONNECT LOCATION field of SPUFI panel 82

CONNECT precompiler option 551

CONNECT statement, with DRDA access 519

connectionDB2

connecting from tasks 959

function of CAFCLOSE 979, 988

CONNECT 973, 976, 988

description 966

DISCONNECT 980, 988

OPEN 977, 988

Index X-5

connection (continued)function of CAF (continued)

sample scenarios 984, 985

summary of behavior 983

TRANSLATE 982, 990

function of RRSAFAUTH SIGNON 1016

CREATE THREAD 1040

description 998

examples 1036

FIND_DB2_SYSTEMS 1035

IDENTIFY 1006, 1040

SIGNON 1012, 1040

summary of behavior 1004

TERMINATE IDENTIFY 1032, 1040

TERMINATE THREAD 1031, 1040

TRANSLATE 1034

constants, syntaxC 215

Fortran 266

CONTINUE clause of WHENEVER statement 116

CONTINUE handler (SQL procedure)description 735

example 735

correlated referencecorrelation name 74

SQL rules 67

usage 67

using in subquery 74

correlation name 75

CREATE GLOBAL TEMPORARY TABLE statement 34

CREATE TABLE statementDEFAULT clause 31

NOT NULL clause 31

PRIMARY KEY clause 306

relationship names 309

UNIQUE clause 31, 306

usage 31

CREATE THREAD, RRSAFdescription 999

effect of call order 1004

implicit connection 999


program example 1040

syntax usage 1029

CREATE TRIGGERactivation order 331

description 321

example 321

timestamp 331

trigger naming 323

CREATE VIEW statement 38

created temporary tableinstances 34


use of NOT NULL 34

working with 33

CS (cursor stability)optimistic concurrency control 472

page and row locking 472

CURRENT PACKAGESET special registerdynamic plan switching 576

identify package collection 568

CURRENT RULES special registereffect on check constraints 304

usage 575

CURRENT SERVER special registerdescription 568

saving value in application program 538

CURRENT SQLID special registeruse in test 627

value in INSERT statement 32

CURRENTDATA option of BINDplan and package options differ 479

cursorambiguous 478

attributesusing GET DIAGNOSTICS 141

using SQLCA 141

closing 130

CLOSE statement 135

deleting a current row 134

description 125

duplicate 812

dynamic scrollable 140

effect of abend on position 148

exampleretrieving backward with scrollable cursor 150

updating specific row with rowset-positioned

cursor 152

updating with non-scrollable cursor 149

updating with rowset-positioned cursor 151

insensitive scrollable 139

maintaining position 147

non-scrollable 138

open state 147

OPEN statement 127

result table 125

row-positioneddeclaring 125

deleting a current row 129

description 125

end-of-data condition 128

retrieving a row of data 128

steps in using 125

updating a current row 129

rowset-positioneddeclaring 130

description 125


number of rows 131

number of rows in rowset 135

opening 131

retrieving a rowset of data 131

steps in using 130

updating a current rowset 133

scrollabledescription 138

dynamic 140

fetch orientation 141

INSENSITIVE 139

retrieving rows 141

SENSITIVE DYNAMIC 139

SENSITIVE STATIC 139

sensitivity 138

static 140

updatable 138

static scrollable 140

types 138

WITH HOLDclaims 480

description 147

locks 479


Ddata

adding to the end of a table 1078

associated with WHERE clause 10

currency 537

effect of locks on integrity 452

improving access 889

indoubt state 497

not in a table 26

retrieval using SELECT * 1077

retrieving a rowset 131

retrieving a set of rows 128

retrieving large volumes 1077

scrolling backward through 1073

security and integrity 493

understanding access 889

updating during retrieval 1076

updating previously retrieved data 1076

data encryption 310

data typebuilt-in 4

comparisons 107

compatibilityassembler and SQL 175

assembler application program 181

C and SQL 208

C application program 215

COBOL and SQL 247, 254

Fortran and SQL 264, 267

PL/I and SQL 284

PL/I application program 288

REXX and SQL 297


DATE precompiler option 552

datetime data type 4

DB2 abendCAF 971

DL/I batch 646

RRSAF 1003

DB2 coprocessor 546

processing SQL statements 542

DB2 private protocol accesscoding an application 517

compared to DRDA access 506

planning 506

DB2I (DB2 Interactive)background processing

run-time libraries 597

EDITJCL processingrun-time libraries 597

interrupting 91

menu 79

panelsBIND PACKAGE 600

BIND PLAN 603

Compile, Link, and Run 614

Current SPUFI Defaults 82

DB2I Primary Option Menu 79, 588

DCLGEN 156, 163

Defaults for BIND PLAN 607

Precompile 598

Program Preparation 590

System Connection Types 612

preparing programs 587

program preparation example 590

selectingDCLGEN (declarations generator) 159

DB2I (DB2 Interactive) (continued)selecting (continued)

SPUFI 79

SPUFI 79

DBCS (double-byte character set)table names 155

translation in CICS 559

DBINFOstored procedure 709

user-defined function 379

DBPROTOCOL(DRDA) 525

DBRM (database request module)binding to a package 562

binding to a plan 567

deciding how to bind 442

description 544

DBRMs in HFS filesbinding 564

DCLGEN subcommand of DSNbuilding data declarations 155

COBOL example 161

column labels 157

DBCS table names 155

forming host variable names 158

identifying tables 155


including declarations in a program 159

indicator variable array declaration 158

right margin 159

starting 155

using 155

using PDS (partitioned data set) 155

DDITV02 input data set 646

DDOTV02 output data set 648

deadlockdescription 453

example 453

indicationsin CICS 455

in IMS 455

in TSO 454

recommendation for avoiding 457

with RELEASE(DEALLOCATE) 459

X’00C90088’ reason code in SQLCA 454

debugging application programs 631

DEC15precompiler option 552

rules 27

DEC31avoiding overflow 27


rules 27

DECFLOAT data type 857

decimal15 digit precision 27

31 digit precision 27

arithmetic 26

DECIMALconstants 215

data type, in C 212

function, in C 213

declarationgenerator (DCLGEN) 155

in an application program 159

variables in CAF program examples 993

DECLARE (SQL procedure) 733

Index X-7

DECLARE CURSOR statementdescription, row-positioned 125

description, rowset-positioned 130

FOR UPDATE clause 126

multilevel security 126

prepared statement 680, 684

scrollable cursor 138

WITH HOLD clause 147

WITH RETURN option 763

WITH ROWSET POSITIONING clause 130

DECLARE GLOBAL TEMPORARY TABLE statement 35

DECLARE TABLE statementadvantages of using 101

assembler 169

C 187

COBOL 223

description 101

Fortran 261

PL/I 271

table description 155

DECLARE VARIABLE statementchanging CCSID 108

coding 108

description 107

declared temporary tableincluding column defaults 36

including identity columns 36

instances 35

ON COMMIT clause 37

qualifier for 35

remote access using a three-part name 519

requirements 35

working with 33

dedicated virtual memory pool 929

DEFCOLLIDoption of DSNTP2DP tool 509

DEFER(PREPARE) 525

DELETE statementcorrelated subquery 75

description 45, 46

positionedFOR ROW n OF ROWSET clause 134

restrictions 129

WHERE CURRENT clause 129, 134

deletingcurrent rows 129

data 46

every row from a table 46

with TRUNCATE 47

rows from a table 46

delimiter, SQL 100

DENSE_RANK specification 21

example 22

department sample tablecreating 32

description 1084

DEPLOYfor native SQL procedures 730

DESCRIBE CURSOR statement 800

DESCRIBE INPUT statement 679

DESCRIBE PROCEDURE statement 799

DESCRIBE statementcolumn labels 690

INTO clauses 684, 686

DFHEIENT macro 170

DFSLI000 (IMS language interface module) 561

diagnostics areaRESIGNAL affect on 742

SIGNAL affect on 742

direct row access 314, 901

disability xxiii

DISCONNECT (connection function of CAF)description 968


program example 988

syntax 980

syntax usage 980

displayingtable columns 28

table privileges 28

DISTINCTclause of SELECT statement 8

unique values 8

distinct typeassigning values 419

comparing types 418

description 417

exampleargument of user-defined function (UDF) 422

arguments of infix operator 422

casting constants 422

casting function arguments 422

casting host variables 422

LOB data type 422

function arguments 421

strong typing 418

UNION with INTERSECT 421

with EXCEPT 421

with UNION 421

distributed datachoosing an access method 506

coordinating updates 521

copying a remote table 537

DBPROTOCOL bind option 514, 519

encoding scheme of retrieved data 536

exampleaccessing remote temporary table 519

calling stored procedure at remote location 513

connecting to remote server 514, 520

limiting number of retrieved rows 534

specifying location in table name 514

using alias for multiple sites 520

using RELEASE statement 521

using three-part table names 518

executing long SQL statements 536

identifying server at run time 538

LOB performancesetting CURRENT RULES special register 524

using LOB locators 524

using stored procedure result sets 524

maintaining data currency 537

performancechoosing bind options 525

coding efficient queries 524

forcing block fetch 528

limiting number of retrieved rows 530, 534

optimizing access path 527

specifying package list 526

using block fetch 528

using DRDA 528

performance considerations 525

planningaccess by a program 505


distributed data (continued)planning (continued)

DB2 private protocol access 514

DRDA access 514

program preparation 517

programmingcoding with DB2 private protocol access 517

coding with DRDA access 517

resource limit facility 505

restricted systems 522

retrieving from ASCII or Unicode tables 536

savepoints 506

scrollable cursors 506

terminology 505

three-part table names 518

transmitting mixed data 537

two-phase commit 521

using alias for location 520

DL/I batchapplication programming 644

checkpoint call 495

checkpoint ID 652

commit and rollback coordination 500

DB2 requirements 644

DDITV02 input data set 646

DSNMTV01 module 649

features 643

SSM= parameter 649

submitting an application 649

TERM call 495

double-byte character large object (DBCLOB) 343

DPSIperformance considerations 871

DRDA accessaccessing remote temporary table 519

bind options 515, 516

coding an application 517

compared to DB2 private protocol access 506

connecting to remote server 519

mixed environment 1209

planning 506, 514

precompiler options 514

preparing programs 514

programming hints 535

releasing connections 521

sample program 1155

SQL limitations at different servers 535

DRDA access with CONNECT statementssample program 1155

DRDA with three-part namessample program 1163

DROP TABLE statement 37

DSN applications, running with CAF 965

DSN command of TSOreturn code processing 578

RUN subcommands 578

services lost under CAF 965

DSN_FUNCTION_TABLE table 409

DSN_STATEMENT_CACHE_TABLE 667

DSN_STATEMNT_TABLE tablecolumn descriptions 946

DSN8BC3 sample program 257

DSN8BD3 sample program 219

DSN8BE3 sample program 219

DSN8BF3 sample program 269

DSN8BP3 sample program 292

DSN8EXP stored proceduredescription 1240

example call 1242

option descriptions 1241

output 1243

syntax diagram 1241

DSNACICS stored procedure 1228

DSNALI (CAF language interface module)deleting 987

loading 987

DSNCLI (CICS language interface module) 561

DSNELI (TSO language interface module) 965

DSNH command of TSO 638

DSNHASM procedure 582

DSNHC procedure 582

DSNHCOB procedure 582

DSNHCOB2 procedure 582

DSNHCPP procedure 582

DSNHCPP2 procedure 582

DSNHDECPimplicit CAF connection 968

implicit RRSAF connection 999

DSNHFOR procedure 582

DSNHICB2 procedure 582

DSNHICOB procedure 582

DSNHLI entry point to DSNALIimplicit calls 968

program example 992

DSNHLI entry point to DSNRLIimplicit calls 999

program example 1039

DSNHLI2 entry point to DSNALI 990

DSNHPLI procedure 582

DSNMTV01 module 649

DSNRLI (RRSAF language interface module)deleting 1039

loading 1039

DSNTEDIT CLIST 1197

DSNTEP2 and DSNTEP4 sample programspecifying SQL terminator 1120

DSNTEP2 sample programhow to run 1111

parameters 1112


DSNTEP4 sample programhow to run 1111

parameters 1112



C 220

COBOL 258

PL/I 293

DSNTIAD sample programhow to run 1111

parameters 1112


specifying SQL terminator 1118

DSNTIAR subroutineassembler 183

C 218

COBOL 257

description 121

Fortran 268

PL/I 291

return codes 123

using 123

Index X-9

DSNTIAUL sample programhow to run 1111

parameters 1112


DSNTIR subroutine 268

DSNTP2DP tool 508

authorization 508


outalias output 510

outpkgs output 511

outplans output 511

sample output 509

syntax 508

DSNTPSMP stored procedure 718

DSNTRACE data set 986

DSNXDBRM 544

DSNXNBRM 544

duplicate CALL statements 812

duration of lockscontrolling 467

description 463

DXXMQGEN stored proceduredescription 1262

invocation example 1264

invocation syntax 1262

output 1265

parameter descriptions 1263

DXXMQGENCLOB stored proceduredescription 1269



output 1272


DXXMQINSERT stored proceduredescription 1243



output 1245


DXXMQINSERTALL stored proceduredescription 1252



output 1254


DXXMQINSERTALLCLOB stored proceduredescription 1259



output 1262


DXXMQINSERTCLOB stored proceduredescription 1248



output 1250


DXXMQRETRIEVE stored proceduredescription 1265



output 1269


DXXMQRETRIEVECLOB stored proceduredescription 1272



DXXMQRETRIEVECLOB stored procedure (continued)output 1276


DXXMQSHRED stored proceduredescription 1245



output 1247


DXXMQSHREDALL stored proceduredescription 1255



output 1257


DXXMQSHREDALLCLOB stored proceduredescription 1257



output 1259


DXXMQSHREDCLOB stored proceduredescription 1250



output 1252


DYNAM option of COBOL 224

dynamic buffer allocationFETCH WITH CONTINUE 136

dynamic plan selectionrestrictions with CURRENT PACKAGESET special

register 576

using packages with 576

dynamic prefetchdescription 932

dynamic SQLadvantages and disadvantages 661

assembler program 682

C program 682

cachingeffect of RELEASE bind option 468

caching prepared statements 665

COBOL application program 224

COBOL program 699

description 661

effect of bind option REOPT(ALWAYS) 696

effect of WITH HOLD cursor 675

EXECUTE IMMEDIATE statement 672

fixed-list SELECT statements 679, 681

Fortran program 261

host languages 671

non-SELECT statements 672, 676

PL/I 682

PREPARE and EXECUTE 674, 676

programming 661

requirements 662

restrictions 662

sample C program 1137

statement caching 665

statements allowed 1209

using DESCRIBE INPUT 679

varying-list SELECT statements 681, 696

DYNAMICRULES bind option 572


EECB (event control block)

address in CALL DSNALI parameter list 971

CONNECT connection function of CAF 973, 976

CONNECT, RRSAF 1006

program example 988, 990

programming with CAF (call attachment facility) 988

EDIT panel, SPUFISQL statements 89

embedded semicolonembedded 1118

embedded SQL applicationsXML data 427

employee photo and resume sample table 1089

employee sample table 1086

employee-to-project-activity sample table 1092

ENCRYPT_TDES function 310

END-EXEC delimiter 100

end-of-data condition 128, 131

errorarithmetic expression 116

division by zero 116

handling 115

messages generated by precompiler 637, 638

overflow 116

return codes 114

run 636

ESTAE routine in CAF (call attachment facility) 986

EXCEPTeliminating duplicate rows 17

keeping duplicate rows with ALL 18

EXCEPT clausecolumns of result table 16

exception condition handling 115

EXCLUSIVElock mode

effect on resources 464

LOB 486

page 464

row 464

table, partition, and table space 464

XML 489

EXEC SQL delimiter 100

EXECUTE IMMEDIATE statement 672

EXECUTE statementdynamic execution 675

parameter types 695

USING DESCRIPTOR clause 696

EXISTS predicate, subquery 72

EXIT handler (SQL procedure) 735

exit routineabend recovery with CAF 986

attention processing with CAF 985

EXPLAINautomatic rebind 449

report of outer join 918

statementdescription 889

index scans 900

interpreting output 896

investigating SQL processing 889

EXPLAIN PROCESSING field of panel DSNTIPOoverhead 895

EXPLAIN STATEMENT CACHE ALL 667

FFETCH CURRENT CONTINUE 135

FETCH FIRST n ROWS ONLY clauseeffect on OPTIMIZE clause 875

FETCH FIRST n ROWS ONLY clauseeffect on distributed performance 534

FETCH statementdescription, multiple rows 131

description, single row 128


host variables 681

multiple-rowassembler 169

description 131, 132

FOR n ROWS clause 135

number of rows in rowset 135

using with descriptor 132, 133

using with host variable arrays 131

row and rowset positioning 142

scrolling through data 1073


using row-positioned cursor 128

FETCH WITH CONTINUE 135

file reference variable 355

DB2-generated construct 356

filter factorpredicate 843

FIND_DB2_SYSTEMS function of RRSAFsyntax 1035

usage 1035

fixed buffer allocationFETCH WITH CONTINUE 136

fixed-length character stringassembler 173

COBOL 236

FLAG precompiler option 552

FLOAT precompiler option 552

FOLDvalue for C and CPP 553

value of precompiler option HOST 553

FOR FETCH ONLY clause 528

FOR READ ONLY clause 528

FOR UPDATE clause 126

FOREIGN KEY clausedescription 308

usage 309

formatSELECT statement results 93

SQL in input data set 88

Fortran application program@PROCESS statement 262

assignment rules 266

byte data type 262

character host variable 262, 263


constant syntax 266


data types 264


declaring views 261

defining the SQLDA 260

host variable, declaring 262


including SQLCA 259


LOB variable 263


Index X-11

Fortran application program (continued)numeric host variable 262

parallel option 262



ROWID variable 264

SQLCODE 259

SQLSTATE 259

statement labels 261



FROM clausejoining tables 57

SELECT statement 6

FRR (functional recovery routine) 986

FULL OUTER JOIN clause 60

functioncolumn

when evaluated 907

function resolution 405

functional recovery routine (FRR) 986

GGET DIAGNOSTICS

output host variable processing 111

GET DIAGNOSTICS statementcondition items 116

connection items 116

data types for items 117, 118

description 116

multiple-row INSERT 117

RETURN_STATUS item 739

ROW_COUNT item 131

SQL procedure 732

statement items 116

using in handler 735

global transactionRRSAF support 1014, 1022

GO TO clause of WHENEVER statement 116

GOTO statement (SQL procedure) 732

governor (resource limit facility) 670

GRANT statement 629

graphic host variableassembler 173

C 193

COBOL 230

PL/I 274

graphic host variable arrayC 202

COBOL 239

PL/I 279

GRAPHIC precompiler option 552

GROUP BY clauseeffect on OPTIMIZE clause 877

use with aggregate functions 14

Hhandler, using in SQL procedure 734

HAVING clauseselecting groups subject to conditions 14

subquery 71

HOSTFOLD value for C and CPP 553


host languagedeclarations in DB2I (DB2 Interactive) 156

dynamic SQL 671

host structureC 206

COBOL 242


PL/I 282

retrieving row of data 112

using SELECT INTO 112

host variableassembler 171

binaryassembler 173

C 195

COBOL 232

PL/I 275

C 188, 190

changing CCSID 107

characterassembler 172

C 191

COBOL 228

Fortran 263

PL/I 274

COBOL 226

description 101

example query 859

FETCH statement 681

floating-pointassembler 172

C/C++ 213

COBOL 227

PL/I 288

Fortran 262

graphicassembler 173

C 193

COBOL 230

PL/I 274

impact on access path selection 859

in equal predicate 863

inserting into tables 105

LOBassembler 347

C 348

COBOL 348

Fortran 350

PL/I 350

naming a structureC 206

COBOL 242

PL/I program 282

numericassembler 171

C 191

COBOL 227

Fortran 262

PL/I 274

PL/I 273

PREPARE statement 680

REXX 297

selecting single row 103

static SQL flexibility 662

tuning queries 859

updating values in tables 104

using 102


host variable (continued)using INSERT with VALUES clause 105


using SELECT INTO with aggregate function 104

using SELECT INTO with expressions 104

varbinaryassembler 174

XMLassembler 428

C 429

COBOL 429

PL/I 430

host variable arrayC 188, 199

characterC 200

COBOL 236

PL/I 279

COBOL 226, 234


graphicC 202

COBOL 239

PL/I 279


inserting multiple rows 109

numericC 199

COBOL 234

PL/I 278

PL/I 273, 278

retrieving multiple rows 109

hybrid joindescription 923

II/O processing

parallelqueries 951

IDENTIFY, RRSAFprogram example 1040

syntax 1006

usage 1006

identity columndefining 43, 315

IDENTITY_VAL_LOCAL function 317

inserting in table 1073

inserting values into 43

trigger 325

using as parent key 316

IF statement (SQL procedure) 732

IKJEFT01 terminal monitor program in TSO 579

IMScheckpoint calls 496

CHKP call 495

commit point 496

environment planning 581

language interface module (DFSLI000) 561

link-editing 561

recovery 495, 497

restrictions on commit 497

ROLB call 495, 500

ROLL call 495, 500

SYNC call 495

unit of work 495, 496

XRST call 497

IN predicate, subquery 72

INCLUDE statement, DCLGEN output 159

indexaccess methods

access path selection 910

by nonmatching index 912

IN-list index scan 913

matching index columns 900

matching index description 910

multiple 913

one-fetch index scan 914

locking 467

typesforeign key 309

primary 307

unique 307

unique on primary key 305

indicator structure 113

indicator variablearray declaration in DCLGEN 158

assembler application program 182

C 217

COBOL 255

description 105

Fortran 267

incorrect test for null column value 106

inserting null value 106

null value 106

PL/I 290

REXX 301

specifying 106

testing 105

indicator variable arrayC 217

COBOL 255

description 110

inserting null values 111

PL/I 290

specifying 110

testing for null value 110

infinite loop 26

informational referential constraintautomatic query rewrite 311

description 311

INLISTP 886

INNER JOIN clause 57

input data set DDITV02 646

INSERT processing, effect of MEMBER CLUSTER option of

CREATE TABLESPACE 456

INSERT statementdescription 39

multiple rows 41

single row 40

VALUES clause 39

with identity column 43

with ROWID column 42

insertingvalues from host variable arrays 109

values from host variables 105

INTENT EXCLUSIVE lock mode 464, 486, 489

INTENT SHARE lock mode 464, 486, 489

Interactive System Productivity Facility (ISPF) 79

internal resource lock manager (IRLM) 650

INTERSECTeliminating duplicate rows 17


Index X-13

INTERSECT clausecolumns of result table 16

invalid SQL terminator characters 1118

IS DISTINCT FROM predicate 107

ISOLATIONoption of BIND PLAN subcommand

effects on locks 471

isolation levelcontrol by SQL statement

example 480

recommendations 459

REXX 302

ISPF (Interactive System Productivity Facility)browse 82, 93

DB2 uses dialog management 79

DB2I Primary Option Menu 588

Program Preparation panel 590

programming 959, 962

scroll command 94

ISPLINK SELECT services 962

ITERATE statement (SQL procedure) 732

JJCL (job control language)

batch backout example 651

DDNAME list format 584

page number format 584

precompilation procedures 582

precompiler option list format 584

preparing a CICS program 585

preparing a object-oriented program 586

starting a TSO batch application 579

join operationCartesian 920

description 916

FULL OUTER JOIN 60

hybriddescription 923

INNER JOIN 57

join sequence 924

joining a table to itself 58

joining tables 57

LEFT OUTER JOIN 61

merge scan 921

more than one join 64

more than one join type 64

nested loop 918

operandnested table expression 65

user-defined table function 65

RIGHT OUTER JOIN 62

SQL rules 63

star join 924

star schema 924

join sequencedefinition 834

KKEEPDYNAMIC option

BIND PACKAGE subcommand 668

BIND PLAN subcommand 668

keycomposite 306

foreign 308

key (continued)parent 305

primarychoosing 305

defining 307

recommendations for defining 308

using timestamp 305

unique 1073

keywords, reserved 1203

Llabel, column 690

language interface modulesDSNCLI 561

DSNRLI 764


large object (LOB)character conversion 355

declaring host variables 346

for precompiler 347

declaring LOB file reference variables 346

declaring LOB locators 346

defining and moving data into DB2 343

description 343

expression 352

file reference variable 355


locator 352

materialization 351

sample applications 346

LEAVE statement (SQL procedure) 732

LEFT OUTER JOIN clause 61

level of a lock 461

LEVEL precompiler option 553

limited partition scan 905

LINECOUNT precompiler option 553

link-editing 560

AMODE option 615

RMODE option 615

list prefetchdescription 934

thresholds 935

LOAD macro used by RRSAF 997

load module structure of CAF (call attachment facility) 966

load module structure of RRSAF 1000

LOAD z/OS macro used by CAF 965

LOBlock

concurrency with UR readers 476

description 485

LOB (large object)lock duration 487

LOCK TABLE statement 487

locking 485

modes of LOB locks 486

modes of table space locks 486

LOB column, definition 343

LOB valuesfetching 135

LOB variableassembler 174

C 197

COBOL 233

Fortran 263

PL/I 276


LOB variable arrayC 204

COBOL 240

PL/I 280

lockavoidance 477

benefits 452

classtransaction 451

compatibility 465

description 451

durationcontrolling 467

description 463

LOBs 487

XML data 490

effect of cursor WITH HOLD 479

effectsdeadlock 453

suspension 452

timeout 453

escalationwhen retrieving large numbers of rows 1077

hierarchydescription 461

LOB locks 485

mode 464

objectdescription 466

indexes 467

options affectingaccess path 482

bind 467

cursor stability 472

program 467

read stability 475

repeatable read 475

uncommitted read 473

page locksCS, RS, and RR compared 475

description 461

recommendations for concurrency 455

sizepage 461

partition 461

table 461

table space 461

unit of work 493, 494

XML locks 488

LOCK TABLE statementeffect on auxiliary tables 487, 491

effect on locks 481

LOCKPART clause of CREATE and ALTER TABLESPACEeffect on locking 462

LOCKSIZE clauserecommendations 456

LOOP statement (SQL procedure) 732

Mmapping macro

assembler applications 184

DSNXDBRM 544

DSNXNBRM 544

MARGINS precompiler option 553

mass deletecontends with UR process 476

materializationLOBs 351

outer join 918

views and nested table expressions 939

MEMBER CLUSTER option of CREATE TABLESPACE 456

merge processingviews or nested table expressions 938

MERGE statement 908

mergingdata 45

messageanalyzing 637

CAF errors 983

obtaining textassembler 183

C 218

COBOL 257

Fortran 268

PL/I 291

RRSAF errors 1004

mixed dataconverting 537

description 4

transmitting to remote location 537

MLS (multilevel security)referential constraints 310

triggers 334

mode of a lock 464

modified source statements 544

MQSeriesApplication Messaging Interface (AMI) 1045

DB2 functionscommit environment 1050

connecting applications 1054

description 1045

MQPUBLISH 1047

MQPUBLISHXML 1049

MQREAD 1047

MQREADALL 1048

MQREADALLCLOB 1048

MQREADALLXML 1048

MQREADCLOB 1047

MQREADXML 1048

MQRECEIVE 1047

MQRECEIVEALL 1048

MQRECEIVEALLCLOB 1048

MQRECEIVEALLXML 1049

MQRECEIVECLOB 1047

MQRECEIVEXML 1048

MQSEND 1047

MQSENDXML 1049

MQSENDXMLFILE 1049

MQSENDXMLFILECLOB 1049

MQSUBSCRIBE 1047

MQUNSUBSCRIBE 1047


retrieving messages 1053

sending messages 1052

DB2 scalar functions 1046

DB2 stored proceduresDXXMQINSERT 1049, 1050

DXXMQINSERTALL 1049, 1050

DXXMQINSERTALLCLOB 1049

DXXMQINSERTCLOB 1049

DXXMQRETRIEVE 1050

DXXMQRETRIEVECLOB 1050

DXXMQSHRED 1049

Index X-15

MQSeries (continued)DB2 stored procedures (continued)

DXXMQSHREDALL 1049

DXXMQSHREDALLCLOB 1049

DXXMQSHREDCLOB 1049

DB2 table functions 1047

DB2 XML-specific functions 1048

description 1045

message 1045

policy 1046

service 1046

multilevel security (MLS) checkreferential constraints 310

triggers 334

multiple-mode IMS programs 498

multiple-row FETCH statementchecking DB2_LAST_ROW 119

specifying indicator arrays 110

SQLCODE +100 114

testing for null 110

multiple-row INSERT statementdynamic execution 676

NOT ATOMIC CONTINUE ON SQLEXCEPTION 117

using GET DIAGNOSTICS 117

Nnaming convention

assembler 169

C 187

COBOL 224

Fortran 261

PL/I 271

REXX 296

tables you create 32

native SQL proceduresBIND COPY 728

BIND COPY REPLACE 729

deploying 730

packages for 728

replacing packages for 729

nested compound statementscursor declarations 747

definition 743

for controlling scope of conditions 748

scope of variables 745


nested table expressioncorrelated reference 66

correlation name 66

join operation 65

processing 938

NEWFUNprecompiler option 554

NODYNAM option of COBOL 225

NOFOR precompiler option 554

NOGRAPHIC precompiler option 554

nonsegmented table spacescan 909

nontabular data storage 1079

NOOPTIONS precompiler option 554

NOPADNTSTR precompiler option 554

NOSOURCE precompiler option 554

NOT FOUND clause of WHENEVER statement 116

NOT LOGGED table spacerecovering 503

notices, legal 1287

NOXREF precompiler option 554

NUL character in C 187

NUL-terminated string in C 214

NULLpointer in C 187

null valuecolumn value of UPDATE statement 44

host structure 113



inserting into columns 106

IS DISTINCT FROM predicate 106

IS NULL predicate 106

Null, in REXX 296

numericdata

width of column in results 93

numeric datadescription 4

width of column in results 86

numeric host variableassembler 171

C 191

COBOL 227

Fortran 262

PL/I 274

numeric host variable arrayC 199

COBOL 234

PL/I 278

Oobject of a lock 466

object-oriented program, preparation 586

ON clause, joining tables 57

ONEPASS precompiler option 555

OPENstatement

opening a cursor 127

opening a rowset cursor 131

performance 938

prepared SELECT 681


without parameter markers 694

OPEN (connection function of CAF)description 968


program example 988

syntax 977

syntax usage 977

optimistic concurrency control 460, 472

Optimization Service Center 889

OPTIMIZE FOR n ROWS clause 876

interaction with FETCH FIRST clause 875

OPTIMIZE FOR n ROWS clauseeffect on distributed performance 530

OPTIONS precompiler option 555

ORDER BY clausederived columns 13

effect on OPTIMIZE clause 877

SELECT statement 12

with AS clause 13

with ORDER OF clause 13

ORDER OF clause 13

organization applicationexamples 1103


originating task 952

OSC 889

outer joinEXPLAIN report 918

FULL OUTER JOIN 60

LEFT OUTER JOIN 61

materialization 918

RIGHT OUTER JOIN 62

output host variable processing 111

errors 111

Ppackage

advantages 443

bindingDBRM to a package 561

EXPLAIN option for remote 895

PLAN_TABLE 891

remote 562

to plans 567

deciding how to use 442

identifying at run time 568

invalidated 447

dropping objects 445

listing 567

location 568

rebinding examples 446

rebinding with pattern-matching characters 445

selecting 568

trigger 447

version, identifying 571

packagesfor native SQL procedures 728

PACKAGESoption of DSNTP2DP tool 509

packages bound on DB2 Version 3 and before xxviii

PADNTSTR precompiler option 555

pagelocks

description 461

PAGE_RANGE column of PLAN_TABLE 905

panelCurrent SPUFI Defaults 82, 87

DB2I Primary Option Menu 79

DCLGEN 156, 162

DSNEDP01 156, 162

DSNEPRI 79

DSNESP01 79

DSNESP02 82

DSNESP07 87

EDIT (for SPUFI input data set) 88

SPUFI 79

parallel processingdescription 949

enabling 952

related PLAN_TABLE columns 906

tuning 956

parameter markercasting in function invocation 412

dynamic SQL 674

more than one 676

values provided by OPEN 681

with arbitrary statements 695, 696

parent key 305

PARMS option 579

partition scan, limited 905

partitioned table spacelocking 462

performanceaffected by

application structure 962

DEFER(PREPARE) 525

lock size 463

NODEFER(PREPARE) 525

remote queries 523, 525, 534

REOPT(ALWAYS) 527

REOPT(AUTO) 527

REOPT(NONE) 527

REOPT(ONCE) 527

monitoringwith EXPLAIN 889

performance considerationsDPSI 871


PERIOD precompiler option 555

phone application, description 1103

PL/I application programbinary host variable 275



coding considerations 272



data types 284

DBCS constants 271

DCLGEN support 160


declaring views 271



host variable 273

host variable array 273


including SQLCA 269

including SQLDA 270


indicator variables 290

LOB variable 276






ROWID variable 277

ROWID variable array 280, 282

SQLCODE 269

SQLSTATE 269


table locator 276



PLAN_TABLE tablecolumn descriptions 891

report of outer join 918

planningaccessing distributed data 505

binding 442

precompiling 441

recovery 493

PLANSoption of DSNTP2DP tool 509

plans bound on DB2 Version 3 and before xxviii

Index X-17

precompilerbinding on another system 543

description 542

diagnostics 544

functions 543

input 544

maximum size of input 544

modified source statements 544


optionsCONNECT 514

defaults 557

DRDA access 514

SQL 514

output 544

planning for 441

precompiling programs 542

running 543

startingdynamically 583

JCL for procedures 582

submitting jobsDB2I panels 598

ISPF panels 590

submitting jobs with ISPF panels 587

predicatedescription 831

evaluation rules 835

filter factor 843

general rules 10

generation 855

impact on access paths 832

indexable 833

join 832

local 832

modification 855

properties 832

stage 1 (sargable) 834

stage 2evaluated 834

influencing creation 881

subquery 832

predictive governingin a distributed environment 671

with DEFER(PREPARE) 671

writing an application for 671

PRELINK utility 593

PREPARE statementdynamic execution 675

host variable 680

INTO clause 684

prepared SQL statementcaching 668


PRIMARY KEY clauseALTER TABLE statement 307

CREATE TABLE statement 306

PRIMARY_ACCESSTYPE column of PLAN_TABLE 901

problem determination, guidelines 636


program problems checklistdocumenting error situations 631

error messages 631, 632

project activity sample table 1091

project application, description 1103

project sample table 1090

Qquery parallelism 949

QUOTE precompiler option 555

QUOTESQL precompiler option 555

RRANK specification 21

example 22

reason codeCAF

translation 987, 990

X″00C10824″ 980, 981

X″00F30050″ 986

X″00F30083″ 986

X’00C90088’ 454

X’00C9008E’ 453

X″00D44057″ 643

REBIND PACKAGE subcommand of DSNgenerating list of 1197

optionsISOLATION 471

RELEASE 467

rebinding with wildcard characters 445

remote 563

REBIND PLAN subcommand of DSNgenerating list of 1197

optionsACQUIRE 467

ISOLATION 471

NOPKLIST 446

PKLIST 446

RELEASE 467

remote 563

REBIND TRIGGER PACKAGE subcommand of DSN 447

rebindingautomatically

conditions for 447

EXPLAIN processing 895

changes that require 444

list of plans and packages 447

lists of plans or packages 1197

options for 442

packages with pattern-matching characters 445

planning for 449

plans 446

plans or packages in use 442

Recoverable Resource Manager Services attachment facility

(RRSAF)See RRSAF

recoveryidentifying application requirements 499

IMS application program 495

IMS batch 501

planning for 493

recursive SQLcontrolling depth 1194

description 25

examples 1191

infinite loops 26

rules 25

single level explosion 1191

summarized explosion 1193

referential constraintdefining 305

description 305


referential constraint (continued)determining violations 1079

informational 311

name 308

on tables with data encryption 310

on tables with multilevel security 310

referential integrityeffect on subqueries 76


register conventionsCAF (call attachment facility) 971

RRSAF 1005

RELEASEoption of BIND PLAN subcommand

combining with other options 467

release information block (RIB) 971

RELEASE LOCKS field of panel DSNTIP4effect on page and row locks 479

RELEASE SAVEPOINT statement 502

RELEASE statement, with DRDA access 521

REOPT 886

REOPTEXT 886

reoptimizing access path 859

REPEAT statement (SQL procedure) 732

REPLACE statement (COBOL) 223

reserved keywords 1203

resetting control blocksCAF 980

RRSAF 1032

RESIGNAL statementraising a condition 739

setting SQLSTATE value 742

RESIGNAL statement (SQL procedure) 732

resource limit facility (governor)description 670

writing an application for predictive governing 671

resource unavailable conditionCAF 982

RRSAF 1034

restart, DL/I batch programs using JCL 651

result columnjoin operation 60

naming with AS clause 9

result set locatorassembler 174

C 196

COBOL 232

example 800

Fortran 263

how to use 800

PL/I 276

result tabledescription 3

example 3

of SELECT statement 3

read-only 127

retrievingdata in ASCII from DB2 for z/OS 688

data in Unicode from DB2 for z/OS 688

data using SELECT * 1077

data, changing the CCSID 688

large volumes of data 1077

multiple rows into host variable arrays 109

return codeDSN command 578

SQL 980

RETURN statementreturning SQL procedure status 739

RETURN statement (SQL procedure) 732

REXX procedureapplication programming interface

CONNECT 294

DISCONNECT 294

EXECSQL 294


data type conversion 297

DSNREXX 295

error handling 296


input data type 298, 299

isolation level 302


naming cursors 297

naming prepared statements 297

running 581

SQLCA 293

SQLDA 293

statement label 296

RIB (release information block)address in CALL DSNALI parameter list 971

CONNECT connection function of CAF 973

CONNECT, RRSAF 1006

program example 988

RIDfor direct row access 314

RID (record identifier) pooluse in list prefetch 934

RID function 314

RIGHT OUTER JOIN clause 62

RMODE link-edit option 615

ROLB call, IMSadvantages over ROLL 501

DL/I batch programs 500

ends unit of work 495

ROLL call, IMSDL/I batch programs 500

ends unit of work 495

ROLLBACK optionCICS SYNCPOINT command 495

ROLLBACK statementdescription 81

error in IMS 643

in a stored procedure 769

TO SAVEPOINT clause 502

unit of work in TSO 494

with RRSAF 997

rowselecting with WHERE clause 10

updating 44

updating current 129

updating large volumes 1076

ROW CHANGE TIMESTAMP 20, 460

row change token 460

row-level security 310

ROWIDcoding example 903

data type 4

index-only access 901

inserting in table 1073

ROWID columndefining 42, 313

defining LOBs 343

inserting values into 42

Index X-19

ROWID column (continued)using for direct row access 314

ROWID variableassembler 175

C 199

COBOL 234

Fortran 264

PL/I 277

ROWID variable arrayC 205

COBOL 241

PL/I 280, 282

rowsetdeleting current 134

updating current 133

rowset cursorclosing 135

DB2 for z/OS down-level requester 537

declaring 130


example 151

multiple-row FETCH 131

opening 131

using 130

rowset parameter, DB2 for z/OS support for 535

RR (repeatable read)how locks are held (figure) 475


RRS global transactionRRSAF support 1014, 1022

RRSAFapplication program

examples 1039

preparation 996

connecting to DB2 1040

description 995

function descriptions 1005

load module structure 1000

programming language 996

register conventions 1005

restrictions 995

return codesAUTH SIGNON 1016

CONNECT 1006

FIND_DB2_SYSTEMS 1035

SIGNON 1012

TERMINATE IDENTIFY 1032

TERMINATE THREAD 1031

TRANSLATE 1034

run environment 997

RRSAF (Recoverable Resource Manager Services attachment

facility)transactions

using global transactions 460

RS (read stability)page and row locking (figure) 475

RUN subcommand of DSNreturn code processing 578

running a program in TSO foreground 578

run-time libraries, DB2Ibackground processing 597

EDITJCL processing 597

running application programCICS 581

errors 636

IMS 581

Ssample application

call attachment facility 964

databases, for 1100

DRDA access 1155

DRDA access with CONNECT statements 1155

DRDA with three-part names 1163

dynamic SQL 1137

environments 1105

languages 1105

LOB 1104

organization 1103

phone 1103

programs 1106

project 1103

RRSAF 996

static SQL 1137

stored procedure 1103

structure of 1099

use 1105

user-defined function 1104

sample programDSN8BC3 257

DSN8BD3 219

DSN8BE3 219

DSN8BF3 269

DSN8BP3 292

sample tableDSN8910.ACT (activity) 1083

DSN8910.DEMO_UNICODE (Unicode sample ) 1093

DSN8910.DEPT (department) 1084

DSN8910.EMP (employee) 1086

DSN8910.EMP_PHOTO_RESUME (employee photo and

resume) 1089

DSN8910.EMPPROJACT (employee-to-project

activity) 1092

DSN8910.PROJ (project) 1090

PROJACT (project activity) 1091

views on 1094

savepointdescription 501

distributed environment 506

RELEASE SAVEPOINT statement 502

restrictions on use 502

ROLLBACK TO SAVEPOINT 502

SAVEPOINT statement 502

setting multiple times 502

use with DRDA access 502

SAVEPOINT statement 502

scope of a lock 461

scrollable cursorcomparison of types 143

DB2 for z/OS down-level requester 537

distributed environment 506

dynamicdynamic model 140

fetching current row 144


optimistic concurrency control 472

performance considerations 870

retrieving rows 141

sensitive dynamic 140

sensitive static 139

sensitivity 143

staticcreating delete hole 144

creating update hole 145


scrollable cursor (continued)static (continued)

holes in result table 144

number of rows 142

removing holes 146

static model 140

updatable 138

scrollingbackward through data 1073

backward using identity columns 1074

backward using ROWIDs 1074

in any direction 1075

ISPF (Interactive System Productivity Facility) 94

search conditioncomparison operators 10

NOT keyword 11

SELECT statement 69

WHERE clause 10

segmented table spacelocking 462

scan 909

SEGSIZE clause of CREATE TABLESPACErecommendations 910

SELECT FROM DELETE statementdescription 55

retrievingmultiple rows 55

with INCLUDE clause 55

SELECT from INSERT statementBEFORE trigger values 48

default values 48

description 47

inserting into view 49

multiple rowscursor sensitivity 50

effect of changes 51

effect of SAVEPOINT and ROLLBACK 51

effect of WITH HOLD 51

processing errors 52

result table of cursor 50

using cursor 49

using FETCH FIRST 50

using INPUT SEQUENCE 50

result table 48

retrievingBEFORE trigger values 47

default values 47

generated values 47

multiple rows 47

special registers 47


SELECT FROM MERGE statementdescription 53

with INCLUDE clause 53

SELECT FROM UPDATE statementdescription 53

retrievingmultiple rows 53

with INCLUDE clause 50, 53

SELECT statementchanging result format 93

clausesDISTINCT 8

EXCEPT 15

FROM 6

GROUP BY 14

HAVING 14

SELECT statement (continued)clauses (continued)

INTERSECT 15

ORDER BY 12

UNION 15

WHERE 10

derived column with AS clause 8

filtering by time changed 20

fixed-list 679, 681

named columns 7

parameter markers 695

search condition 69

selecting a set of rows 125

subqueries 69

unnamed columns 7

using with* (to select all columns) 6

column-name list 7

DECLARE CURSOR statement 125, 130

varying-list 681, 696

selectingall columns 6

more than one row 103

named columns 7

rows 10

some columns 7

unnamed columns 7

semicolondefault SPUFI statement terminator 82

embedded 1118

sequence numbersCOBOL application program 224

Fortran 261

PL/I 271

sequence objectcreating 318

referencing 318

using across multiple tables 318

sequencesimproving concurrency 459

sequential detection 932, 934

sequential prefetchbind time 934

description 934

SET clause of UPDATE statement 44

SET CURRENT DEGREE statement 952

SET CURRENT PACKAGESET statement 568

SET ENCRYPTION PASSWORD statement 310

setting SQL terminatorDSNTIAD 1118

SPUFI 89

SHAREINTENT EXCLUSIVE lock mode 464, 486, 489

lock modeLOB 486

page 464

row 464


XML 489

shortcut keyskeyboard xxiii

SIGNAL statementraising a condition 739

setting condition message text 741

SIGNAL statement (SQL procedure) 733

SIGNON, RRSAFprogram example 1040

Index X-21

SIGNON, RRSAF (continued)syntax 1012

usage 1012

simple table spacelocking 462

single-mode IMS programs 498

SKIP LOCKED DATA 483

examples 485

isolation levels 484

lock mode compatibility 484

lock sizes 484

Skipping locked pages 483

Skipping locked rows 483

SOME quantified predicate 72

sortprogram

RIDs (record identifiers) 937

when performed 938

removing duplicates 937

shown in PLAN_TABLE 936

sort keyORDER BY clause 12

ordering 12

SOURCE precompiler option 555

special registerbehavior in stored procedures 770

CURRENT PACKAGE PATH 569

CURRENT PACKAGESET 569

CURRENT RULES 575

user-defined functions 391

SPUFIbrowsing output 93

changed column widths 93

CONNECT LOCATION field 82

created column heading 94

DB2 governor 91

default values 82

entering comments 89

panelsallocates RESULT data set 81

filling in 79

format and display output 93

previous values displayed on panel 79

selecting on DB2I menu 79

processing SQL statements 79, 91

retrieving Unicode data 89

setting SQL terminator 89

specifying SQL statement terminator 82

SQLCODE returned 93

SQL (Structured Query Language)checking execution 113

codingassembler 167

basics 99

C 185

C++ 185

COBOL 220

dynamic 699

Fortran 259

Fortran program 260

object extensions 341

PL/I 269

REXX 293

cursors 125

dynamiccoding 661


SQL (Structured Query Language) (continued)dynamic (continued)


host variable arrays 101

host variables 101

keywords, reserved 1203

return codeschecking 114

handling 121

statement terminator 1118

string delimiter 596

structures 101

syntax checking 535

varying-list 681, 696

SQL communication area (SQLCA)description 114

using DSNTIAR to format 121

SQL precompiler option 556

SQL procedureconditions, handling 734

forcing SQL error 742

preparation using DSNTPSMP procedure 716


referencing SQLCODE and SQLSTATE 736

SQL variable 733


SQL procedure statementCALL statement 731

CASE statement 732

compound statement 732

CONTINUE handler 735

EXIT handler 735

FOR statement 732

GET DIAGNOSTICS statement 732

GOTO statement 732

handler 734

handling errors 734

IF statement 732

ITERATE statement 732

LEAVE statement 732

LOOP statement 732

REPEAT statement 732

RESIGNAL statement 732

RETURN statement 732

SIGNAL statement 733

SQL statement 733

WHILE statement 733

SQL proceduresdebugging 823

nested compound statements 743

SQL statement (SQL procedure) 733

SQL statement nestingrestrictions 413


user-defined functions 413

SQL statement terminatormodifying in DSNTEP2 and DSNTEP4 1120

modifying in DSNTIAD 1118

modifying in SPUFI 82

specifying in SPUFI 82

SQL statementsALLOCATE CURSOR 800

ALTER FUNCTION 362

ASSOCIATE LOCATORS 799

CLOSE 130, 135, 681

COBOL program sections 222

coding REXX 295


SQL statements (continued)comments

assembler 169

C 187

COBOL 223

Fortran 260

PL/I 270

REXX 296

CONNECT, with DRDA access 519

continuationassembler 169

C 187

COBOL 223

Fortran 261

PL/I 271

REXX 296

CREATE FUNCTION 362

DECLARE CURSORdescription 125, 130

example 680, 684

DECLARE TABLE 101, 155

DELETEdescription 129

example 46

DESCRIBE 684

DESCRIBE CURSOR 800

DESCRIBE PROCEDURE 799

embedded 544

error return codes 121

EXECUTE 675

EXECUTE IMMEDIATE 672

EXPLAINmonitor access paths 889

FETCHdescription 128, 131

example 681

INSERT 39

labelsassembler 170

C 188

COBOL 224

Fortran 261

PL/I 271

REXX 296

marginsassembler 169

C 187

COBOL 224

Fortran 261

PL/I 271

REXX 296

MERGEexample 45

OPENdescription 127, 131

example 681

PREPARE 675

RELEASE, with DRDA access 521

SELECTdescription 10


joining tables 57

SELECT FROM DELETE 55

SELECT from INSERT 47

SELECT FROM MERGE 53

SELECT FROM UPDATE 53

SET CURRENT DEGREE 952

SQL statements (continued)set symbols 170

UPDATEdescription 129, 133, 134

example 44

WHENEVER 115

SQL terminator, specifying in DSNTEP2 and DSNTEP4 1120

SQL terminator, specifying in DSNTIAD 1118

SQL variable 733

SQL-INIT-FLAG, resetting 226

SQLCA (SQL communication area)assembler 167

C 185

checking SQLCODE 114

checking SQLERRD(3) 114

checking SQLSTATE 114

checking SQLWARN0 114

COBOL 220

description 114


C 220

COBOL 258

PL/I 293

DSNTIAR subroutineassembler 183

C 218

COBOL 257

Fortran 268

PL/I 291

Fortran 259

PL/I 269

reason code for deadlock 454

reason code for timeout 453

REXX 293


SQLCODE-510 478

-923 647

-925 500, 643

-926 500, 643

+004 980, 981

+100 116

+256 986

+802 116

values 114

SQLCODE variablein SQL procedures 736

SQLDAsetting an XML host variable 692

XML column 692

SQLDA (SQL descriptor area)allocating storage 132, 685

assembler 168

assembler program 682

C 186, 682

COBOL 221

declaring 132

dynamic SELECT example 687

for LOBs and distinct types 690

Fortran 260

multiple-row FETCH statement 132

no occurrences of SQLVAR 684

OPEN statement 681

parameter in CAF TRANSLATE 982

parameter in RRSAF TRANSLATE 1034

parameter markers 695

Index X-23

SQLDA (SQL descriptor area) (continued)PL/I 270, 682

requires storage addresses 688

REXX 293

setting output fields 132

varying-list SELECT statement 682

SQLERROR clause of WHENEVER statement 115

SQLN field of SQLDA 684

SQLRULES, option of BIND PLAN subcommand 575

SQLSTATE″01519″ 116

″2D521″ 500, 643

″57015″ 647

values 114

SQLSTATE variablein SQL procedures 736

SQLVAR field of SQLDA 686

SQLWARNING clause of WHENEVER statement 115

SSIDoption of DSNTP2DP tool 509

SSID (subsystem identifier), specifying 595

SSN (subsystem name)CALL DSNALI parameter list 971

parameter in CAF CONNECT function 973

parameter in CAF OPEN function 977

parameter in RRSAF CONNECT function 1006

SQL calls to CAF (call attachment facility) 968

SQL calls to RRSAF (recoverable resources services

attachment facility) 999

star join 924

dedicated virtual memory pool 929

star schemadefining indexes for 881

stateof a lock 464

statement cache table 667

statement tablecolumn descriptions 946

static SQLdescription 661

host variables 662


STDDEV functionwhen evaluation occurs 907

STDSQL precompiler option 556

STOP DATABASE commandtimeout 453

storageacquiring

retrieved row 686

SQLDA 685

addresses in SQLDA 688

storage group, for sample application data 1100

stored procedureaccessing transition tables 395, 804

binding 765

CALL statement 771

calling from a REXX procedure 804

defining parameter lists 776, 777, 778, 779

defining to DB2 709

DSN8EXP 1240

DSNACICS 1228

DXXMQGEN 1262

DXXMQGENCLOB 1269

DXXMQINSERT 1243

DXXMQINSERTALL 1252

DXXMQINSERTALLCLOB 1259

stored procedure (continued)DXXMQINSERTCLOB 1248

DXXMQRETRIEVE 1265

DXXMQRETRIEVECLOB 1272

DXXMQSHRED 1245

DXXMQSHREDALL 1255

DXXMQSHREDALLCLOB 1257

DXXMQSHREDCLOB 1250

example 703

invoking from a trigger 329

languages supported 757

linkage conventions 773

returning non-relational data 764

returning result set 762

running as authorized program 764

running multiple instances 812


testing 820

usage 701

use of special registers 770

using COMMIT in 769

using host variables with 706

using ROLLBACK in 769

using temporary tables in 764

versioning 816

WLM_REFRESH 1226

writing 757

writing in REXX 766

stored proceduresfrom command line processor 814

storm drain effect 1044

stringdata type 4

fixed-lengthassembler 173

COBOL 228

PL/I 290

host variables in C 214

varying-lengthassembler 173

COBOL 229

PL/I 290

subquerybasic predicate 71

conceptual overview 69

correlatedDELETE statement 75

description 73

example 73

UPDATE statement 75

DELETE statement 75

description 69

EXISTS predicate 72

IN predicate 72

join transformation 866

quantified predicate 71

referential constraints 76

restrictions with DELETE 76

tuning 865

tuning examples 869

UPDATE statement 75

subsystemidentifier (SSID), specifying 595

subsystem name (SSN) 968, 999

summarizing group values 14

SYNC call, IMS 495, 496

SYNC parameter of CAF (call attachment facility) 979, 988


synchronization call abends 646

SYNCPOINT command of CICS 495

syntax diagramhow to read xxii

SYSLIB data sets 583

Sysplex query parallelismsplitting large queries across DB2 members 949

SYSPRINT precompiler outputoptions section 638

source statements section, example 638

summary section, example 638

symbol cross-reference section 638

used to analyze errors 638

SYSTERM output to analyze errors 638

Ttable

alteringchanging definitions 33

using CREATE and ALTER 1079

copying from remote locations 537

declaring 101, 155

deleting rows 46

dependent, cycle restrictions 309

displaying, list of 28

DROP statement 37

expression, nestedprocessing 938

filling with test data 630

incomplete definition of 307

inserting multiple rows 41

inserting single row 40

loading, in referential structure 305

locks 461

merging rows 45

populating 630

referential structure 305

retrieving 125

selecting values as you delete rows 55

selecting values as you insert rows 47

selecting values as you merge rows 53

selecting values as you update rows 53

temporary 33

updating rows 44

using three-part table names 518

table expressions, nestedmaterialization 939

table locatorassembler 174

C 196

COBOL 233

PL/I 276

table spacefor sample application 1100

locksdescription 461

scansaccess path 909

determined by EXPLAIN 890

task control block (TCB)See TCB (task control block)

TCB (task control block)capabilities with CAF 964

capabilities with RRSAF 996

issuing CAF CLOSE 980

issuing CAF OPEN 978

temporary tableadvantages of 34

working with 33

TERM call in DL/I 495

terminal monitor program (TMP)See TMP (terminal monitor program)

TERMINATE IDENTIFY, RRSAFprogram example 1040

syntax 1032

usage 1032

TERMINATE THREAD, RRSAFprogram example 1040

syntax 1031

usage 1031

terminating, CAF CLOSE function 979

TEST command of TSO 631

test environment, designing 627

test tables 627

test views of existing tables 627

threadCLOSE function 968

OPEN function 968

TIME precompiler option 556

time that row was changeddetermining 20

timeoutdescription 453

indications in IMS 453

X’00C9008E’ reason code in SQLCA 453

TMP (terminal monitor program)DSN command processor 578

running under TSO 579

transactionIMS

using global transactions 460

transaction lockdescription 451

transaction-oriented BMP, checkpoints in 498

transition table, trigger 326

transition variable, trigger 325

TRANSLATE (connection function of CAF)description 968

language example 983

program example 990

syntax usage 982

TRANSLATE function of RRSAFsyntax 1034

usage 1034

translating requests into SQL 1078

triggeractivation order 331

activation time 323

cascading 330

coding 323

data integrity 335

delete 324

description 321

FOR EACH ROW 324

FOR EACH STATEMENT 324

granularity 324

insert 324

interaction with constraints 333

interaction with security label columns 334

naming 323

parts example 321

parts of 323

subject table 323

Index X-25

trigger (continued)transition table 326

transition variable 325

triggering event 323

update 324

using identity columns 325

with row-level security 334

TRUNCATE 47

example 47

TSOCLISTs

calling application programs 580

running in foreground 580

DSNALI language interface module 965

TEST command 631

tuningDB2

queries containing host variables 859

two-phase commit, definition 521

TWOPASS precompiler option 556

UUnicode

data, retrieving from DB2 for z/OS 688

sample table 1093

Unified Debugger 823

setting up 823

UNIONeliminating duplicate rows 17


UNION clausecolumns of result table 16

combining SELECT statements 15

effect on OPTIMIZE clause 877

removing duplicates with sort 937

UNIQUE clause 306

unit of recoveryindoubt

recovering CICS 495

restarting IMS 497

unit of workCICS description 494

completioncommit 494

open cursors 147

releasing locks 493

roll back 494

TSO 494

description 493

DL/I batch 500

duration 493

IMSbatch 500

commit point 496

ending 495

starting point 495

prevention of data access by other users 493

TSOCOMMIT statement 494

completion 494

ROLLBACK statement 494

updatable cursor 126

UPDATElock mode

page 464

row 464

UPDATE (continued)lock mode (continued)


UPDATE statementcorrelated subqueries 75

description 44

positionedFOR ROW n OF ROWSET 134

restrictions 129

WHERE CURRENT clause 129, 133

SET clause 44

updatingduring retrieval 1076

large volumes 1076

values from host variables 104

UR (uncommitted read)concurrent access restrictions 476

effect on reading LOBs 485

effect on reading XML data 489


recommendation 459

USE AND KEEP EXCLUSIVE LOCKS option of WITH

clause 480

USE AND KEEP SHARE LOCKS option of WITH clause 480

USE AND KEEP UPDATE LOCKS option of WITH

clause 480

USER special registervalue in INSERT statement 32

value in UPDATE statement 44

user-defined functionstatements allowed 1212

user-defined function (UDF)abnormal termination 413

accessing transition tables 395

ALTER FUNCTION statement 362

authorization ID 401

call type 378

casting arguments 411

characteristics 362

coding guidelines 367

concurrent 401

CREATE FUNCTION statement 362

data type promotion 407

DBINFO structure 379

definer 360

defining 362

description 359

diagnostic message 377

DSN_FUNCTION_TABLE 409

exampleexternal scalar 360, 364

external table 366


overloading operator 365

sourced 366

SQL 366


host data typesassembler 372

C 372

COBOL 372

PL/I 372

implementer 360

implementing 367

indicatorsinput 376

result 377


user-defined function (UDF) (continued)invoker 360

invoking 405

invoking from a trigger 329

invoking from predicate 414

main program 368

multiple programs 401

naming 377

nesting SQL statements 413

parallelism considerations 368

parameter conventions 370

assembler 382

C 383

COBOL 387

PL/I 390

preparing 400

reentrant 400

restrictions 367

samples 361

scratchpad 377, 394


setting result values 376

simplifying function resolution 408

special registers 391

specific name 377

steps in creating and using 360

subprogram 368

table locatorsassembler 396

C 398

COBOL 398

PL/I 399

testing 402

types 359

user-defined table functionimproving query performance 878

USING DESCRIPTOR clauseEXECUTE statement 696

FETCH statement 694

OPEN statement 696

VVALUES clause, INSERT statement 39

varbinary host variableassembler 174

VARBINARY variable arrayC 202

variabledeclaration

assembler 180

C 212

COBOL 251

Fortran 265

PL/I 287

declaring in SQL procedure 733

hostassembler 171

COBOL 226

Fortran 262

PL/I 273

variable arrayhost

C 199

COBOL 234

PL/I 278

VARIANCE functionwhen evaluation occurs 907

varying-length character stringassembler 173

COBOL 237

version of a package 571

VERSION precompiler option 557, 571

viewcontents 39

declaring 101

description 37

dropping 39

EXPLAIN 941, 942

identity columns 38

join of two or more tables 38

processingview materialization description 939

view materialization in PLAN_TABLE 905

view merge 938

referencing special registers 38

retrieving 125

summary data 39

union of two or more tables 38

usingdeleting rows 46

inserting rows 39

updating rows 44

Visual Explain 874

volatile table 878

WWHENEVER statement

assembler 170

C 188

COBOL 224

CONTINUE clause 116

Fortran 261

GO TO clause 116

NOT FOUND clause 116, 128

PL/I 271

specifying 115

SQL error codes 115

SQLERROR clause 115

SQLWARNING clause 115

WHERE clauseSELECT statement

description 10


joining tables 57

subquery 71

WHILE statement (SQL procedure) 733

WITH clausecommon table expressions 24

isolation level 480

specifies isolation level 480

WITH HOLD clauseand CICS 148

and IMS 148

DECLARE CURSOR statement 147

restrictions 148

WITH HOLD cursoreffect on dynamic SQL 675

effect on locks and claims 479

WLM_REFRESH stored proceduredescription 1226


Index X-27

WLM_REFRESH stored procedure (continued)sample JCL 1228

syntax diagram 1226

write-down privilege 335

XXDBDECOMPXML

authorization 1281




XDBDECOMPXML stored procedure 1281

XMLlock

description 488

XML (extensible markup language)lock duration 490

LOCK TABLE statement 491

locking 488

modes of table space locks 489

modes of XML locks 489

XML dataembedded SQL applications 427

retrieving from tables in embedded SQL applications 434

selecting 8

updating tables in embedded SQL applications 431

XML decompositionstored procedure 1281

XML host variableSQLDA 692

XML schemastored procedure for registering 1276, 1279

stored procedure for removing 1280

XML schema documentstored procedure to add 1277

XML valuesfetching 135

XML_COMPLETEauthorization 1279





XMLEXISTS 11

description 11

example 11

XMLQUERY 8

description 8

example 8

XPath 8

XPath contexts 8

XPath contextsXMLEXISTS 11

XPath expressions 8

XREF precompiler option 557

XRST call, IMS 497

XSR_ADDSCHEMADOCauthorization 1277





XSR_ADDSCHEMADOC stored procedure 1277

XSR_COMPLETE stored procedure 1279

XSR_REGISTERauthorization 1276

XSR_REGISTER (continued)invocation example 1277




XSR_REGISTER stored procedure 1276

XSR_REMOVEauthorization 1280





XSR_REMOVE stored procedure 1280


��

Program Number: 5635-DB2

Printed in USA

SC18-9841-00

Spine information:

��

�

DB

2 Ve

rsio

n 9.1

fo

r z/

OS

Appl

icat

ion

Prog

ram

min

g an

d SQ

L G

uide

Documents

MQND display queue(’In Q’) curdepth 5. - Student · PDF file5. Look at the Backout queue and find the original message by using the WebSphere MQ sample program CSQ4BCJ1. Note: