MQND display queue(’In Q’) curdepth 5. - Student · PDF file5. Look at the Backout...
Transcript of MQND display queue(’In Q’) curdepth 5. - Student · PDF file5. Look at the Backout...
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.
1070 Application Programming and SQL Guide
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.
1072 Application Programming and SQL 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;
© Copyright IBM Corp. 1983, 2007 1073
/**********************************************************/
/* 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:
/**************************/
/* Declare host variables */
/**************************/
EXEC SQL BEGIN DECLARE SECTION;
SQL TYPE IS ROWID hv_dept_rowid;
char[37] hv_deptname;
EXEC SQL END DECLARE SECTION;
/***************************/
/* 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. */
/**********************************************************/
1074 Application Programming and SQL Guide
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 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 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?
1076 Application Programming and SQL Guide
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
Chapter 36. Programming techniques: Questions and answers 1077
|||||||
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.)
1078 Application Programming and SQL Guide
||
||||
||||
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.
Chapter 36. Programming techniques: Questions and answers 1079
||||||
||
1080 Application Programming and SQL Guide
Part 7. Appendixes
© Copyright IBM Corp. 1983, 2007 1081
1082 Application Programming and SQL Guide
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:
© Copyright IBM Corp. 1983, 2007 1083
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 shows the content of the columns.
Table 216. Columns of the department table
Column Column Name Description
1 DEPTNO Department ID, the primary key
1084 Application Programming and SQL Guide
Table 216. Columns of the department table (continued)
Column Column Name Description
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
Name On Column Type of Index
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.
Relationship to other tables:
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
Column Column Name Description
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
1086 Application Programming and SQL Guide
Table 219. Columns of the employee table (continued)
Column Column Name Description
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
Name On Column Type of Index
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
Appendix A. DB2 sample tables 1087
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
1088 Application Programming and SQL Guide
Relationship to other tables:
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
(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;
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
STORES DSN8910.EMP_PHOTO_RESUME
COLUMN PSEG_PHOTO;
CREATE AUX TABLE DSN8910.AUX_EMP_RESUME
IN DSN8D91L.DSN8S91N
STORES DSN8910.EMP_PHOTO_RESUME
COLUMN RESUME;
Content of the employee photo and resume table:
Table 223 shows the content of the columns.
Table 223. Columns of the employee photo and resume table
Column Column Name Description
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
Appendix A. DB2 sample tables 1089
Table 224 shows the indexes for the employee photo and resume table:
Table 224. Indexes of the employee photo and resume table
Name On Column Type of Index
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
Relationship to other tables:
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))
IN DSN8D91A.DSN8S91P
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:
1090 Application Programming and SQL Guide
Table 226 shows the content of the columns.
Table 226. Columns of the project table
Column Column Name Description
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
Name On Column Type of Index
DSN8910.XPROJ1 PROJNO Primary, ascending
DSN8910.XPROJ2 RESPEMP Ascending
Relationship to other tables:
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)
IN DSN8D91A.DSN8S91P
CCSID EBCDIC;
Content of the project activity table:
Appendix A. DB2 sample tables 1091
Table 228 shows the content of the columns.
Table 228. Columns of the project activity table
Column Column Name Description
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
Relationship to other tables:
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
(EMPNO CHAR(6) NOT NULL,
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)
IN DSN8D91A.DSN8S91P
CCSID EBCDIC;
Content of the employee to project activity table:
1092 Application Programming and SQL Guide
Table 230 shows the content of the columns.
Table 230. Columns of the employee to project activity table
Column Column Name Description
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
Relationship to other tables:
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
Column Column Name Description
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’
Appendix A. DB2 sample tables 1093
Table 232. Columns of the Unicode sample table (continued)
Column Column Name Description
4 X00_TO_XFF Array of characters, x’00’ to x’FF’
This table has no indexes
Relationship to other tables:
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
1094 Application Programming and SQL Guide
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
Appendix A. DB2 sample tables 1095
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
1096 Application Programming and SQL Guide
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.DEPTNO,D2.DEPTNAME,D2.MGRNO,D2.FIRSTNME,D2.MIDINIT,
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.DEPTNO,D1.DEPTNAME,D1.MGRNO,D1.FIRSTNME,D1.MIDINIT,
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.PROJNO,P2.PROJNAME,P2.RESPEMP,P2.FIRSTNME,P2.MIDINIT,
P2.LASTNAME
FROM DSN8910.VPROJRE1 P1,
DSN8910.VPROJRE1 P2
WHERE P1.PROJNO = P2.MAJPROJ ;
Figure 281. VPSTRDE1
Appendix A. DB2 sample tables 1097
CREATE VIEW DSN8910.VPSTRDE2
(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,
P1.PROJNO,P1.PROJNAME,P1.RESPEMP,P1.FIRSTNME,P1.MIDINIT,
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
1098 Application Programming and SQL Guide
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
Appendix A. DB2 sample tables 1099
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
USING STOGROUP DSN8G910
PRIQTY 20
SECQTY 20
ERASE NO
NUMPARTS 4
(PART 1 USING STOGROUP DSN8G910
PRIQTY 12
1100 Application Programming and SQL Guide
SECQTY 12,
PART 3 USING STOGROUP DSN8G910
PRIQTY 12
SECQTY 12)
LOCKSIZE PAGE LOCKMAX SYSTEM
BUFFERPOOL BP0
CLOSE NO
COMPRESS YES
CCSID EBCDIC;
CREATE TABLESPACE DSN8S91B
IN DSN8D91L
USING STOGROUP DSN8G910
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
USING STOGROUP DSN8G910
PRIQTY 160
SECQTY 80
SEGSIZE 4
LOCKSIZE TABLE
BUFFERPOOL BP0
CLOSE NO
CCSID EBCDIC;
CREATE TABLESPACE DSN8S91P
IN DSN8D91A
USING STOGROUP DSN8G910
PRIQTY 160
SECQTY 80
SEGSIZE 4
LOCKSIZE ROW
BUFFERPOOL BP0
CLOSE NO
CCSID EBCDIC;
CREATE TABLESPACE DSN8S91R
IN DSN8D91A
USING STOGROUP DSN8G910
PRIQTY 20
SECQTY 20
ERASE NO
LOCKSIZE PAGE LOCKMAX SYSTEM
BUFFERPOOL BP0
CLOSE NO
CCSID EBCDIC;
CREATE TABLESPACE DSN8S91S
IN DSN8D91A
USING STOGROUP DSN8G910
Appendix A. DB2 sample tables 1101
PRIQTY 20
SECQTY 20
ERASE NO
LOCKSIZE PAGE LOCKMAX SYSTEM
BUFFERPOOL BP0
CLOSE NO
CCSID EBCDIC;
CREATE TABLESPACE DSN8S81Q
IN DSN8D81P
USING STOGROUP DSN8G810
PRIQTY 160
SECQTY 80
SEGSIZE 4
LOCKSIZE PAGE
BUFFERPOOL BP0
CLOSE NO
CCSID EBCDIC;
CREATE TABLESPACE DSN8S81U
IN DSN8D81E
USING STOGROUP DSN8G810
PRIQTY 5
SECQTY 5
ERASE NO
LOCKSIZE PAGE LOCKMAX SYSTEM
BUFFERPOOL BP0
CLOSE NO
CCSID UNICODE;
1102 Application Programming and SQL Guide
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:
© Copyright IBM Corp. 1983, 2007 1103
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:
1104 Application Programming and SQL Guide
||
|||||
||||
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
telephone numbers and updates them if
requested.
Phone DSN8BP3 DSNTEJ2P DSNELI This PL/I batch program lists employee
telephone numbers and updates them if
requested.
Phone DSN8BF3 DSNTEJ2F DSNELI This FORTRAN program lists employee
telephone numbers and updates them if
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
telephone numbers and updates them if
requested.
Phone DSN8SP3 DSNTEJ3P DSNALI This PL/I ISPF program lists employee
telephone numbers and updates them if
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.
1106 Application Programming and SQL Guide
|
Table 236. Sample DB2 applications for TSO (continued)
Application Program name
Preparation
JCL member
name
Attachment
facility Description
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
demonstrates how to prepare and run a client
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
demonstrates how to prepare and run a client
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
Appendix B. Sample applications 1107
|
|
|
|
|||||||||||||
|||||
|
|
|
|
|
|
Table 236. Sample DB2 applications for TSO (continued)
Application Program name
Preparation
JCL member
name
Attachment
facility Description
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
Application Program name JCL member name Description
Organization DSN8CC0
DSN8CC1
DSN8CC2
DSNTEJ5C CICS COBOL
Organization
Application
1108 Application Programming and SQL Guide
|
|
|
|
Table 238. Sample DB2 applications for CICS (continued)
Application Program name JCL member name Description
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 B. Sample applications 1109
1110 Application Programming and SQL Guide
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.
© Copyright IBM Corp. 1983, 2007 1111
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.
1112 Application Programming and SQL Guide
|
|
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.
1114 Application Programming and SQL Guide
|||
|||
|||
||
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,
// UNIT=SYSDA,SPACE=(800,(15,15)),DISP=(,CATLG),
// VOL=SER=SCR03,RECFM=FB,LRECL=120,BLKSIZE=1200
//SYSIN DD *
DSN8910.PROJ WHERE DEPTNO='D01'
Figure 289. DSNTIAUL invocation without the SQL parameter
Appendix C. Running the productivity-aid sample programs 1115
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;
//UNLOAD EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(DSN)
RUN PROGRAM(DSNTIAUL) PLAN(DSNTIB91) PARMS('SQL,250') -
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
//SYSREC01 DD DSN=DSN8UNLD.SYSREC01,
// UNIT=SYSDA,SPACE=(32760,(1000,500)),DISP=(,CATLG),
// VOL=SER=SCR03
//SYSPUNCH DD DSN=DSN8UNLD.SYSPUNCH,
// UNIT=SYSDA,SPACE=(800,(15,15)),DISP=(,CATLG),
// VOL=SER=SCR03,RECFM=FB,LRECL=120,BLKSIZE=1200
//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
//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 DUMMY
//SYSPUNCH DD DSN=DSN8UNLD.SYSPUNCH,
// UNIT=SYSDA,SPACE=(800,(15,15)),DISP=(,CATLG),
// VOL=SER=SCR03,RECFM=FB,LRECL=120,BLKSIZE=1200
//SYSIN DD *
DSN8910.DEPT
Figure 291. DSNTIAUL invocation to obtain LOAD control statements
1116 Application Programming and SQL Guide
||
|||||||||
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
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(DSN)
RUN PROGRAM(DSNTIAUL) PLAN(DSNTIB91) -
PARMS(’SQL,2,LOBFILE(DSN8UNLD)’) -
LIB(’DSN910.RUNLIB.LOAD’)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSREC00 DD DSN=DSN8UNLD.SYSREC00,
// UNIT=SYSDA,SPACE=(800,(15,15)),DISP=(,CATLG),
// VOL=SER=SCR03,RECFM=FB
//SYSPUNCH DD DSN=DSN8UNLD.SYSPUNCH,
// UNIT=SYSDA,SPACE=(800,(15,15)),DISP=(,CATLG),
// 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).
Appendix C. Running the productivity-aid sample programs 1117
||
|
|
||
|||||||||||||||||
||
|||
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|||
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.
1118 Application Programming and SQL Guide
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
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(DSN)
RUN PROGRAM(DSNTIAD) PLAN(DSNTIA91) PARMS('RC0') -
LIB(’DSN910.RUNLIB.LOAD’)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//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
Appendix C. Running the productivity-aid sample programs 1119
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:
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.
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
1120 Application Programming and SQL Guide
||||
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 #
CREATE TRIGGER NEW_HIRE
AFTER INSERT ON EMP
FOR EACH ROW MODE DB2SQL
BEGIN ATOMIC
UPDATE COMPANY_STATS SET NBEMP = NBEMP + 1;
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
Appendix C. Running the productivity-aid sample programs 1121
||
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
0 Successful completion.
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.
1122 Application Programming and SQL Guide
|||
|||||
|||||
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
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(DSN)
RUN PROGRAM(DSNTEP2) PLAN(DSNTEP91) PARMS('/ALIGN(LHS) MIXED TOLWARN(YES)') -
LIB(’DSN910.RUNLIB.LOAD’)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSIN DD *
SELECT * FROM DSN8910.PROJ;
Figure 293. DSNTEP2 invocation with the ALIGN(LHS) and MIXED parameters
//RUNTEP2 EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(DSN)
RUN PROGRAM(DSNTEP4) PLAN(DSNTEP481) PARMS('/ALIGN(MID) MIXED') -
LIB(’DSN910.RUNLIB.LOAD’)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//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 C. Running the productivity-aid sample programs 1123
1124 Application Programming and SQL Guide
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.
© Copyright IBM Corp. 1983, 2007 1125
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)
1126 Application Programming and SQL Guide
* 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. *
* *
* MODULE TYPE = COBOL PROGRAM *
* PROCESSOR = DB2 PRECOMPILER *
* *
* *
* MODULE SIZE = SEE LINK EDIT *
* 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)
1128 Application Programming and SQL Guide
* 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. *
* *
* EXTERNAL REFERENCES = *
* ROUTINES/SERVICES = *
* DSNTIAR - TRANSLATE SQLCA INTO MESSAGES *
* DATA-AREAS = NONE *
* CONTROL-BLOCKS = *
* SQLCA - SQL COMMUNICATION AREA *
* *
* TABLES = NONE *
* CHANGE-ACTIVITY = NONE *
* *
Figure 296. Called program that does pointer manipulation (Part 2 of 10)
Appendix D. Programming examples 1129
* *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. *
*---------------------------------------------------------------*
/
IDENTIFICATION DIVISION.
*-----------------------
PROGRAM-ID. DSN8BCU2
*
ENVIRONMENT DIVISION.
*--------------------
CONFIGURATION SECTION.
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
RECORD CONTAINS 120 CHARACTERS
LABEL RECORDS ARE OMITTED
DATA RECORD IS MSGREC
RECORDING MODE IS F.
01 MSGREC PIC X(120).
Figure 296. Called program that does pointer manipulation (Part 3 of 10)
1130 Application Programming and SQL Guide
*
FD SYSREC01
RECORD CONTAINS 5 TO 32704 CHARACTERS
LABEL RECORDS ARE OMITTED
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.
/
WORKING-STORAGE SECTION.
*
*****************************************************
* 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).
02 FILLER PIC X(71) VALUE ’ ’.
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).
02 FILLER PIC X(62) VALUE ’ ’.
Figure 296. Called program that does pointer manipulation (Part 4 of 10)
Appendix D. Programming examples 1131
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.
*
Figure 296. Called program that does pointer manipulation (Part 5 of 10)
1132 Application Programming and SQL Guide
*****************************************************
* 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).
/
Figure 296. Called program that does pointer manipulation (Part 6 of 10)
Appendix D. Programming examples 1133
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.
Figure 296. Called program that does pointer manipulation (Part 7 of 10)
1134 Application Programming and SQL Guide
****************************************************************
* *
* 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
AFTER ADVANCING 2 LINES.
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.
Figure 296. Called program that does pointer manipulation (Part 8 of 10)
Appendix D. Programming examples 1135
*****************************************************
* 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.
Figure 296. Called program that does pointer manipulation (Part 9 of 10)
1136 Application Programming and SQL Guide
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
AFTER ADVANCING 2 LINES.
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
AFTER ADVANCING 2 LINES.
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
AFTER ADVANCING 2 LINES.
GO TO PROG-END.
*
*****************************************************
* PRINT MESSAGE TEXT *
*****************************************************
ERROR-PRINT.
WRITE MSGREC FROM ERROR-TEXT (ERROR-INDEX)
AFTER ADVANCING 1 LINE.
Figure 296. Called program that does pointer manipulation (Part 10 of 10)
Appendix D. Programming examples 1137
/**********************************************************************/
/* 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)
1138 Application Programming and SQL Guide
/* 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;
EXEC SQL BEGIN DECLARE SECTION;
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 END DECLARE SECTION;
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) ) ;
Figure 297. Sample SQL in a C program (Part 2 of 4)
Appendix D. Programming examples 1139
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;
Figure 297. Sample SQL in a C program (Part 3 of 4)
1140 Application Programming and SQL Guide
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);
printf("??/n SQLWARN1 = %c",SQLWARN1);
printf("??/n SQLWARN2 = %c",SQLWARN2);
printf("??/n SQLWARN3 = %c",SQLWARN3);
printf("??/n SQLWARN4 = %c",SQLWARN4);
printf("??/n SQLWARN5 = %c",SQLWARN5);
printf("??/n SQLWARN6 = %c",SQLWARN6);
printf("??/n SQLWARN7 = %c",SQLWARN7);
progend: ;
}
Figure 297. Sample SQL in a C program (Part 4 of 4)
Appendix D. Programming examples 1141
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
0 Successful completion.
12 An error occurred when DRAW edited the input file.
20 One of the following errors occurred:
1142 Application Programming and SQL Guide
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.
The DRAW invocation is:
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.
The DRAW invocation is:
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
Appendix D. Programming examples 1143
, "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:
1144 Application Programming and SQL Guide
/* 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:
SELECT "EMPNO" , "FIRSTNME" , "MIDINIT" , "LASTNAME" , "WORKDEPT" ,
"PHONENO" , "HIREDATE" , "JOB" , "EDLEVEL" , "SEX" , "BIRTHDATE" ,
"SALARY" , "BONUS" , "COMM"
FROM DSN8910.EMP
If you include a location qualifier, the query looks like this:
SELECT "EMPNO" , "FIRSTNME" , "MIDINIT" , "LASTNAME" , "WORKDEPT" ,
"PHONENO" , "HIREDATE" , "JOB" , "EDLEVEL" , "SEX" , "BIRTHDATE" ,
"SALARY" , "BONUS" , "COMM"
FROM STLEC1.DSN8910.EMP
Figure 298. REXX sample program DRAW (Part 1 of 10)
Appendix D. Programming examples 1145
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:
Figure 298. REXX sample program DRAW (Part 2 of 10)
1146 Application Programming and SQL Guide
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)=’?’
)
Figure 298. REXX sample program DRAW (Part 3 of 10)
Appendix D. Programming examples 1147
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
Figure 298. REXX sample program DRAW (Part 4 of 10)
1148 Application Programming and SQL Guide
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"
If SQLCODE ^= 0 Then Call SQLCA
Address DSNREXX "EXECSQL COMMIT"
Address DSNREXX "DISCONNECT"
If SQLCODE ^= 0 Then Call SQLCA
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
Figure 298. REXX sample program DRAW (Part 5 of 10)
Appendix D. Programming examples 1149
/**********************************************************************/
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 "("
Do I = 1 To SQLDA.SQLD
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
Figure 298. REXX sample program DRAW (Part 6 of 10)
1150 Application Programming and SQL Guide
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"
Do I = 1 To SQLDA.SQLD
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
Figure 298. REXX sample program DRAW (Part 7 of 10)
Appendix D. Programming examples 1151
/**********************************************************************/
/* 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"
Do I = 1 To SQLDA.SQLD
If I = 1 Then
Line = " "
Else
Line = " ,"
Line = Line Left(’"’SQLDA.I.SQLNAME’"=’,21)
Line = Line Left(" ",20)
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
L = Line.0 + 1; Line.0 = L
Line.L = "WHERE"
Return
Figure 298. REXX sample program DRAW (Part 8 of 10)
1152 Application Programming and SQL Guide
/**********************************************************************/
/* Draw LOAD */
/**********************************************************************/
DrawLoad:
Line.0 = 1
Line.1 = "LOAD DATA INDDN SYSREC INTO TABLE" TABLE
Position = 1
Do I = 1 To SQLDA.SQLD
If I = 1 Then
Line = " ("
Else
Line = " ,"
Line = Line Left(’"’SQLDA.I.SQLNAME’"’,20)
Line = Line "POSITION("RIGHT(POSITION,5)")"
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 = GRTYP ) THEN
Type = SQLTYPES.Type"("STRIP(LEN)")"
When (Type = FLOTYPE ) THEN
Type = SQLTYPES.Type"("STRIP((LEN*4)-11) ")"
When (Type = DCTYPE ) 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
Type = SQLTYPES.Type
End
If (Type = GRTYP ,
|Type = VGRTYP ,
|Type = LVGRTYP ) THEN
Len = Len * 2
If (Type = VCHTYPE ,
|Type = LVCHTYPE ,
|Type = VGRTYP ,
|Type = LVGRTYP ) THEN
Len = Len + 2
Line = Line Type
L = Line.0 + 1; Line.0 = L
Figure 298. REXX sample program DRAW (Part 9 of 10)
Appendix D. Programming examples 1153
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
Figure 298. REXX sample program DRAW (Part 10 of 10)
1154 Application Programming and SQL Guide
Sample COBOL program using DRDA access with CONNECT
statements
The following sample program demonstrates distributed data access using DRDA
access.
IDENTIFICATION DIVISION.
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. *
* *
* MODULE TYPE = COBOL PROGRAM *
* PROCESSOR = DB2 PRECOMPILER, ENTERPRISE COBOL FOR Z/OS *
* MODULE SIZE = SEE LINK EDIT *
* 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 *
* *
* EXTERNAL REFERENCES = *
* ROUTINE SERVICES = NONE *
* DATA-AREAS = NONE *
* CONTROL-BLOCKS = *
* SQLCA - SQL COMMUNICATION AREA *
* *
* TABLES = NONE *
* *
* CHANGE-ACTIVITY = NONE *
* *
* *
* *
Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 1 of 8)
Appendix D. Programming examples 1155
|
|
* 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. *
* Provide a text description of the following step. *
* Open a cursor that will be used to retrieve information *
* about the transferring employee from this site. *
* Print the SQLCA out. *
* 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. *
* *
Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 2 of 8)
1156 Application Programming and SQL Guide
* FETCH-DELETE-SITE-1. *
* Provide a text description of the following step. *
* Fetch information about the transferring employee. *
* Print the SQLCA out. *
* 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. *
* Provide a text description of the following step. *
* Delete the information about the transferring employee *
* from this site. *
* Print the SQLCA out. *
* *
* CLOSE-CURSOR-SITE-1. *
* Provide a text description of the following step. *
* Close the cursor used to retrieve information about *
* the transferring employee. *
* Print the SQLCA out. *
* *
* UPDATE-ADDRESS. *
* Update the address of the employee. *
* Update the city of the employee. *
* Update the location of the employee. *
* *
* CONNECT-TO-SITE-2. *
* Provide a text description of the following step. *
* Establish a connection to the location where the *
* employee is transferring to. *
* Print the SQLCA out. *
* *
* PROCESS-SITE-2. *
* Provide a text description of the following step. *
* Insert the employee information at the location where *
* the employee is being transferred to. *
* Print the SQLCA out. *
* *
* COMMIT-WORK. *
* COMMIT all the changes made to STLEC1 and STLEC2. *
* *
*****************************************************************
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT PRINTER, ASSIGN TO S-OUT1.
DATA DIVISION.
FILE SECTION.
FD PRINTER
RECORD CONTAINS 120 CHARACTERS
DATA RECORD IS PRT-TC-RESULTS
LABEL RECORD IS OMITTED.
01 PRT-TC-RESULTS.
03 PRT-BLANK PIC X(120).
Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 3 of 8)
Appendix D. Programming examples 1157
WORKING-STORAGE SECTION.
*****************************************************************
* 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.
EXEC SQL INCLUDE SQLCA END-EXEC.
*****************************************************************
* Declaration for the table that contains employee information *
*****************************************************************
EXEC SQL DECLARE SYSADM.EMP TABLE
(EMPNO CHAR(6) NOT NULL,
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,
Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 4 of 8)
1158 Application Programming and SQL Guide
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 *
*****************************************************************
EXEC SQL DECLARE C1 CURSOR FOR
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
IF SQLCODE IS EQUAL TO 0
PERFORM UPDATE-ADDRESS
PERFORM CONNECT-TO-SITE-2
IF SQLCODE IS EQUAL TO 0
PERFORM PROCESS-SITE-2.
PERFORM COMMIT-WORK.
Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 5 of 8)
Appendix D. Programming examples 1159
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
WRITE PRT-TC-RESULTS FROM 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
WRITE PRT-TC-RESULTS FROM STNAME
EXEC SQL
FETCH C1 INTO :H-EMPTBL:H-EMPTBL-IND
END-EXEC.
PERFORM PTSQLCA.
IF SQLCODE IS EQUAL TO ZERO
PERFORM DELETE-SITE-1.
Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 6 of 8)
1160 Application Programming and SQL Guide
*****************************************************************
* Delete the employee from STLEC1. *
*****************************************************************
DELETE-SITE-1.
MOVE ’DELETE EMPLOYEE ’ TO STNAME
WRITE PRT-TC-RESULTS FROM STNAME
MOVE ’DELETE EMPLOYEE ’ TO STNAME
EXEC SQL
DELETE FROM SYSADM.EMP
WHERE EMPNO = :TEMP-EMPNO
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
WRITE PRT-TC-RESULTS FROM 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
WRITE PRT-TC-RESULTS FROM STNAME
EXEC SQL
CONNECT TO :SITE-2
END-EXEC.
PERFORM PTSQLCA.
Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 7 of 8)
Appendix D. Programming examples 1161
*****************************************************************
* 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
WRITE PRT-TC-RESULTS FROM 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
WRITE PRT-TC-RESULTS FROM STNAME
EXEC SQL
COMMIT
END-EXEC.
PERFORM PTSQLCA.
*****************************************************************
* Include COBOL standard language procedures *
*****************************************************************
INCLUDE-SUBS.
EXEC SQL INCLUDE COBSSUB END-EXEC.
Figure 299. Sample COBOL two-phase commit application for DRDA access (Part 8 of 8)
1162 Application Programming and SQL Guide
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.
IDENTIFICATION DIVISION.
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. *
* *
* MODULE TYPE = COBOL PROGRAM *
* PROCESSOR = DB2 PRECOMPILER, ENTERPRISE COBOL FOR Z/OS *
* MODULE SIZE = SEE LINK EDIT *
* 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 *
* *
* EXTERNAL REFERENCES = *
* ROUTINE SERVICES = NONE *
* DATA-AREAS = NONE *
* CONTROL-BLOCKS = *
* SQLCA - SQL COMMUNICATION AREA *
* *
* TABLES = NONE *
* *
* CHANGE-ACTIVITY = NONE *
* *
* *
Figure 300. Sample COBOL two-phase commit application for DB2 private protocol access
(Part 1 of 7)
Appendix D. Programming examples 1163
|
* *
* 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. *
* Provide a text description of the following step. *
* Open a cursor that will be used to retrieve information *
* about the transferring employee from this site. *
* Print the SQLCA out. *
* 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. *
* Provide a text description of the following step. *
* Fetch information about the transferring employee. *
* Print the SQLCA out. *
* 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. *
* Provide a text description of the following step. *
* Delete the information about the transferring employee *
* from this site. *
* Print the SQLCA out. *
* *
* CLOSE-CURSOR-SITE-1. *
* Provide a text description of the following step. *
* Close the cursor used to retrieve information about *
* the transferring employee. *
* Print the SQLCA out. *
* *
Figure 300. Sample COBOL two-phase commit application for DB2 private protocol access
(Part 2 of 7)
1164 Application Programming and SQL Guide
* UPDATE-ADDRESS. *
* Update the address of the employee. *
* Update the city of the employee. *
* Update the location of the employee. *
* *
* PROCESS-SITE-2. *
* Provide a text description of the following step. *
* Insert the employee information at the location where *
* the employee is being transferred to. *
* Print the SQLCA out. *
* *
* COMMIT-WORK. *
* COMMIT all the changes made to STLEC1 and STLEC2. *
* *
*****************************************************************
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT PRINTER, ASSIGN TO S-OUT1.
DATA DIVISION.
FILE SECTION.
FD PRINTER
RECORD CONTAINS 120 CHARACTERS
DATA RECORD IS PRT-TC-RESULTS
LABEL RECORD IS OMITTED.
01 PRT-TC-RESULTS.
03 PRT-BLANK PIC X(120).
WORKING-STORAGE SECTION.
*****************************************************************
* 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.
Figure 300. Sample COBOL two-phase commit application for DB2 private protocol access
(Part 3 of 7)
Appendix D. Programming examples 1165
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.
EXEC SQL INCLUDE SQLCA END-EXEC.
*****************************************************************
* Declaration for the table that contains employee information *
*****************************************************************
EXEC SQL DECLARE SYSADM.EMP TABLE
(EMPNO CHAR(6) NOT NULL,
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 *
*****************************************************************
EXEC SQL DECLARE C1 CURSOR FOR
SELECT EMPNO, NAME, ADDRESS, CITY, EMPLOC,
SSNO, BORN, SEX, HIRED, DEPTNO, JOBCODE,
SRATE, EDUC, SAL, VALCHK
FROM STLEC1.SYSADM.EMP
WHERE EMPNO = :TEMP-EMPNO
END-EXEC.
Figure 300. Sample COBOL two-phase commit application for DB2 private protocol access
(Part 4 of 7)
1166 Application Programming and SQL Guide
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
IF SQLCODE IS EQUAL TO 0
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
WRITE PRT-TC-RESULTS FROM 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
WRITE PRT-TC-RESULTS FROM STNAME
EXEC SQL
FETCH C1 INTO :H-EMPTBL:H-EMPTBL-IND
END-EXEC.
Figure 300. Sample COBOL two-phase commit application for DB2 private protocol access
(Part 5 of 7)
Appendix D. Programming examples 1167
PERFORM PTSQLCA.
IF SQLCODE IS EQUAL TO ZERO
PERFORM DELETE-SITE-1.
*****************************************************************
* Delete the employee from STLEC1. *
*****************************************************************
DELETE-SITE-1.
MOVE ’DELETE EMPLOYEE ’ TO STNAME
WRITE PRT-TC-RESULTS FROM STNAME
MOVE ’DELETE EMPLOYEE ’ TO STNAME
EXEC SQL
DELETE FROM STLEC1.SYSADM.EMP
WHERE EMPNO = :TEMP-EMPNO
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
WRITE PRT-TC-RESULTS FROM 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.
Figure 300. Sample COBOL two-phase commit application for DB2 private protocol access
(Part 6 of 7)
1168 Application Programming and SQL Guide
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
WRITE PRT-TC-RESULTS FROM 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
WRITE PRT-TC-RESULTS FROM STNAME
EXEC SQL
COMMIT
END-EXEC.
PERFORM PTSQLCA.
*****************************************************************
* Include COBOL standard language procedures *
*****************************************************************
INCLUDE-SUBS.
EXEC SQL INCLUDE COBSSUB END-EXEC.
Figure 300. Sample COBOL two-phase commit application for DB2 private protocol access
(Part 7 of 7)
Appendix D. Programming examples 1169
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
main()
{
/************************************************************/
/* Include the SQLCA and SQLDA */
/************************************************************/
EXEC SQL INCLUDE SQLCA;
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 */
/************************************************************/
EXEC SQL BEGIN DECLARE SECTION;
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 */
EXEC SQL END DECLARE SECTION;
Figure 301. Calling a stored procedure from a C program (Part 1 of 4)
1170 Application Programming and SQL Guide
/*************************************************************/
/* 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");
}
Figure 301. Calling a stored procedure from a C program (Part 2 of 4)
Appendix D. Programming examples 1171
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;
Figure 301. Calling a stored procedure from a C program (Part 3 of 4)
1172 Application Programming and SQL Guide
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;
}
Figure 301. Calling a stored procedure from a C program (Part 4 of 4)
Appendix D. Programming examples 1173
IDENTIFICATION DIVISION.
PROGRAM-ID. CALPRML.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT REPOUT
ASSIGN TO UT-S-SYSPRINT.
DATA DIVISION.
FILE SECTION.
FD REPOUT
RECORD CONTAINS 127 CHARACTERS
LABEL RECORDS ARE OMITTED
DATA RECORD IS REPREC.
01 REPREC PIC X(127).
WORKING-STORAGE SECTION.
*****************************************************
* 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).
02 FILLER PIC X(38) VALUE SPACES.
01 CALLREC.
02 CALLMSG PIC X(28) VALUE
’ GETPRML FAILED DUE TO RC = ’.
02 CALLCODE PIC +9(5) USAGE DISPLAY.
02 FILLER PIC X(42) VALUE SPACES.
01 RSLTREC.
02 RSLTMSG PIC X(15) VALUE
’ TABLE NAME IS ’.
02 TBLNAME PIC X(18) VALUE SPACES.
02 FILLER PIC X(87) VALUE SPACES.
Figure 302. Calling a stored procedure from a COBOL program (Part 1 of 3)
1174 Application Programming and SQL Guide
*****************************************************
* 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 *
*****************************************************
EXEC SQL INCLUDE SQLCA END-EXEC.
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.
Figure 302. Calling a stored procedure from a COBOL program (Part 2 of 3)
Appendix D. Programming examples 1175
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)
AFTER ADVANCING 1 LINE.
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
AFTER ADVANCING 1 LINE.
Figure 302. Calling a stored procedure from a COBOL program (Part 3 of 3)
1176 Application Programming and SQL Guide
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 */
/************************************************************/
EXEC SQL INCLUDE 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)
Appendix D. Programming examples 1177
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;
1178 Application Programming and SQL Guide
C stored procedure: GENERAL WITH NULLS
This example stored procedure does the following:
#pragma runopts(plist(os))
#include <stdlib.h>
EXEC SQL INCLUDE SQLCA;
/***************************************************************/
/* 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. */
/***************************************************************/
EXEC SQL BEGIN DECLARE SECTION;
char PROCNM[19];
char SCHEMA[9];
char PARMLST[255];
EXEC SQL END DECLARE SECTION;
/***************************************************************/
/* 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)
Appendix D. Programming examples 1179
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.
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 for this stored procedure is GENERAL WITH NULLS.
The output parameters from this stored procedure contain the SQLCODE from the
SELECT operation, and the value of the RUNOPTS column retrieved from the
SYSROUTINES table.
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 WITH NULLS
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;
1180 Application Programming and SQL Guide
#pragma runopts(plist(os))
#include <stdlib.h>
EXEC SQL INCLUDE SQLCA;
/***************************************************************/
/* 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. */
/***************************************************************/
EXEC SQL BEGIN DECLARE SECTION;
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;
EXEC SQL END DECLARE SECTION;
/***************************************************************/
/* 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 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)
Appendix D. Programming examples 1181
COBOL stored procedure: GENERAL
This example stored procedure does the following:
v Searches the catalog table SYSROUTINES for a row matching the input
parameters from the client program. The two input parameters contain values
for NAME and SCHEMA.
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.
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
SELECT RUNOPTS INTO :PARMLST
FROM SYSIBM.SYSROUTINES
WHERE NAME=:PROCNM AND
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)
1182 Application Programming and SQL Guide
The output parameters from this stored procedure contain the SQLCODE from the
SELECT operation, and the value of the RUNOPTS column retrieved from the
SYSROUTINES table.
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 COBOL
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;
Appendix D. Programming examples 1183
CBL RENT
IDENTIFICATION DIVISION.
PROGRAM-ID. GETPRML.
AUTHOR. EXAMPLE.
DATE-WRITTEN. 03/25/98.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
DATA DIVISION.
FILE SECTION.
WORKING-STORAGE SECTION.
EXEC SQL INCLUDE SQLCA END-EXEC.
***************************************************
* DECLARE A HOST VARIABLE TO HOLD INPUT SCHEMA
***************************************************
01 INSCHEMA PIC X(8).
***************************************************
* DECLARE CURSOR FOR RETURNING RESULT SETS
***************************************************
*
EXEC SQL DECLARE C1 CURSOR WITH RETURN FOR
SELECT NAME FROM SYSIBM.SYSTABLES WHERE CREATOR=:INSCHEMA
END-EXEC.
*
LINKAGE SECTION.
***************************************************
* DECLARE THE INPUT PARAMETERS FOR THE PROCEDURE
***************************************************
01 PROCNM PIC X(18).
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
SELECT RUNOPTS INTO :PARMLST
FROM SYSIBM.ROUTINES
WHERE NAME=:PROCNM AND
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)
1184 Application Programming and SQL Guide
COBOL stored procedure: GENERAL WITH NULLS
This example stored procedure does the following:
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.
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 for this stored procedure is GENERAL WITH NULLS.
The output parameters from this stored procedure contain the SQLCODE from the
SELECT operation, and the value of the RUNOPTS column retrieved from the
SYSIBM.SYSROUTINES table.
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 COBOL
DETERMINISTIC
READS SQL DATA
EXTERNAL NAME "GETPRML"
COLLID GETPRML
ASUTIME NO LIMIT
PARAMETER STYLE GENERAL WITH NULLS
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;
Appendix D. Programming examples 1185
CBL RENT
IDENTIFICATION DIVISION.
PROGRAM-ID. GETPRML.
AUTHOR. EXAMPLE.
DATE-WRITTEN. 03/25/98.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
DATA DIVISION.
FILE SECTION.
*
WORKING-STORAGE SECTION.
*
EXEC SQL INCLUDE SQLCA END-EXEC.
*
***************************************************
* DECLARE A HOST VARIABLE TO HOLD INPUT SCHEMA
***************************************************
01 INSCHEMA PIC X(8).
***************************************************
* DECLARE CURSOR FOR RETURNING RESULT SETS
***************************************************
*
EXEC SQL DECLARE C1 CURSOR WITH RETURN FOR
SELECT NAME FROM SYSIBM.SYSTABLES WHERE CREATOR=:INSCHEMA
END-EXEC.
*
LINKAGE SECTION.
***************************************************
* DECLARE THE INPUT PARAMETERS FOR THE PROCEDURE
***************************************************
01 PROCNM PIC X(18).
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)
1186 Application Programming and SQL Guide
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.
The output parameters from this stored procedure contain the SQLCODE from the
SELECT operation, and the value of the RUNOPTS column retrieved from the
SYSIBM.SYSROUTINES table.
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 PLI
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)"
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
SELECT RUNOPTS INTO :PARMLST
FROM SYSIBM.SYSROUTINES
WHERE NAME=:PROCNM AND
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)
Appendix D. Programming examples 1187
WLM ENVIRONMENT SAMPPROG
PROGRAM TYPE MAIN
SECURITY DB2
RESULT SETS 0
COMMIT ON RETURN NO;
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.
The linkage convention for this stored procedure is GENERAL WITH NULLS.
The output parameters from this stored procedure contain the SQLCODE from the
SELECT operation, and the value of the RUNOPTS column retrieved from the
SYSIBM.SYSROUTINES table.
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 PLI
DETERMINISTIC
READS SQL DATA
EXTERNAL NAME "GETPRML"
COLLID GETPRML
ASUTIME NO LIMIT
PARAMETER STYLE GENERAL WITH NULLS
STAY RESIDENT NO
RUN OPTIONS "MSGFILE(OUTFILE),RPTSTG(ON),RPTOPTS(ON)"
WLM ENVIRONMENT SAMPPROG
*PROCESS SYSTEM(MVS);
GETPRML:
PROC(PROCNM, SCHEMA, OUT_CODE, PARMLST)
OPTIONS(MAIN NOEXECOPS REENTRANT);
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 */
/* SYSIBM.SYSROUTINES */
EXEC SQL INCLUDE SQLCA;
/************************************************************/
/* Execute SELECT from SYSIBM.SYSROUTINES in the catalog. */
/************************************************************/
EXEC SQL
SELECT RUNOPTS INTO :PARMLST
FROM SYSIBM.SYSROUTINES
WHERE NAME=:PROCNM AND
SCHEMA=:SCHEMA;
OUT_CODE = SQLCODE; /* return SQLCODE to caller */
RETURN;
END GETPRML;
Figure 308. A PL/I stored procedure with linkage convention GENERAL
1188 Application Programming and SQL Guide
PROGRAM TYPE MAIN
SECURITY DB2
RESULT SETS 0
COMMIT ON RETURN NO;
*PROCESS SYSTEM(MVS);
GETPRML:
PROC(PROCNM, SCHEMA, OUT_CODE, PARMLST, INDICATORS)
OPTIONS(MAIN NOEXECOPS REENTRANT);
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 -- 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);
EXEC SQL INCLUDE SQLCA;
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
SELECT RUNOPTS INTO :PARMLST
FROM SYSIBM.SYSROUTINES
WHERE NAME=:PROCNM AND
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 D. Programming examples 1189
1190 Application Programming and SQL Guide
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
© Copyright IBM Corp. 1983, 2007 1191
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).
1192 Application Programming and SQL Guide
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
WHERE ROOT.PART = ’01’
UNION ALL
SELECT PARENT.PART, CHILD.SUBPART,
PARENT.QUANTITY*CHILD.QUANTITY
FROM RPL PARENT, PARTLIST CHILD
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.
The result of the query is shown in Table 247:
Table 247. Result table for example 2
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
WHERE ROOT.PART = ’01’
UNION ALL
SELECT PARENT.LEVEL+1, CHILD.PART, CHILD.SUBPART, CHILD.QUANTITY
FROM RPL PARENT, PARTLIST CHILD
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.
The result of the query is shown in Table 248:
Table 248. Result table for example 3
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
1194 Application Programming and SQL Guide
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
1196 Application Programming and SQL Guide
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
© Copyright IBM Corp. 1983, 2007 1197
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.
SELECT SUBSTR(’REBIND PLAN(’CONCAT NAME
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.
SELECT SUBSTR(’REBIND PACKAGE(’CONCAT COLLID CONCAT’.’
CONCAT NAME CONCAT’.(*)) ’,1,55)
FROM SYSIBM.SYSPACKAGE
WHERE BINDTIME <= ’timestamp’;
where timestamp is an ISO timestamp string.
1198 Application Programming and SQL Guide
Example 5:
REBIND all plans bound since a given date and time.
SELECT SUBSTR(’REBIND PLAN(’CONCAT NAME
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 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)
FROM SYSIBM.SYSPACKAGE
WHERE BINDTIME >= ’timestamp’;
where timestamp is an ISO timestamp string.
Example 7:
REBIND all plans bound within a given date and time range.
SELECT SUBSTR(’REBIND PLAN(’CONCAT NAME
CONCAT’) ’,1,45)
FROM SYSIBM.SYSPLAN
WHERE
(BINDDATE >= ’yyyymmdd’ AND
BINDTIME >= ’hhmmssth’) AND
BINDDATE <= ’yyyymmdd’ AND
BINDTIME <= ’hhmmssth’);
where yyyymmdd represents the date portion and hhmmssth represents the
time portion of the timestamp string.
Example 8:
REBIND all versions of all packages bound within a given date and time
range.
SELECT SUBSTR(’REBIND PACKAGE(’CONCAT COLLID CONCAT’.’
CONCAT NAME CONCAT’.(*)) ’,1,55)
FROM SYSIBM.SYSPACKAGE
WHERE BINDTIME >= ’timestamp1’ AND
BINDTIME <= ’timestamp2’;
where timestamp1 and timestamp2 are ISO timestamp strings.
Example 9:
REBIND all invalid plans.
SELECT SUBSTR(’REBIND PLAN(’CONCAT NAME
CONCAT’) ’,1,45)
FROM SYSIBM.SYSPLAN
WHERE VALID = ’N’;
Example 10:
REBIND all invalid versions of all packages.
SELECT SUBSTR(’REBIND PACKAGE(’CONCAT COLLID CONCAT’.’
CONCAT NAME CONCAT’.(*)) ’,1,55)
FROM SYSIBM.SYSPACKAGE
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
SELECT SUBSTR(’REBIND PLAN(’CONCAT NAME
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.
SELECT SUBSTR(’REBIND PACKAGE(’CONCAT COLLID CONCAT’.’
CONCAT NAME CONCAT’.(*)) ’,1,55)
FROM SYSIBM.SYSPACKAGE
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
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(DSN)
RUN PROGRAM(DSNTIAUL) PLAN(DSNTIB91) PARMS(’SQL’) -
LIB(’DSN910.RUNLIB.LOAD’)
END
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//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)
1200 Application Programming and SQL Guide
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 *
SELECT SUBSTR(’REBIND PACKAGE(’CONCAT COLLID CONCAT’.’
CONCAT NAME CONCAT’.(*)) ’,1,55)
FROM SYSIBM.SYSPACKAGE
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
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSTSIN DD *
DSNTEDIT SYSADM.SYSTSIN.DATA
//SYSIN DD DUMMY
/*
//*********************************************************************/
//*
//* PUT IN THE DSN COMMAND STATEMENTS
//*
//*********************************************************************/
//EDIT EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//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
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSTSIN 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 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
//SYSPRINT DD SYSOUT=*
//SYSPUNCH DD SYSOUT=*
//SYSREC00 DD DSN=SYSADM.SYSTSIN.DATA,
// UNIT=SYSDA,DISP=SHR
//*********************************************************************/
//*
//* 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 *
SELECT SUBSTR(’REBIND PLAN(’CONCAT NAME
CONCAT’) DEGREE(ANY) ’,1,45)
FROM SYSIBM.SYSPLAN
WHERE DEGREE = ’ ’;
/*
//*********************************************************************/
//*
//* PUT IN THE DSN COMMAND STATEMENTS
//*
//*********************************************************************/
//EDIT EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//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
//SYSTSPRT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//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
1202 Application Programming and SQL Guide
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.
© Copyright IBM Corp. 1983, 2007 1203
|||
|
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
Note: 1. New reserved word for Version 9.1.
D
DATA
DATABASE
DAY
DAYS
DBINFO
DECLARE
DEFAULT
DELETE
DESCRIPTOR
DETERMINISTIC
DISABLE
DISALLOW
DISTINCT
DO
DOCUMENT1
DOUBLE
DROP
DSSIZE
DYNAMIC
Note: 1. New reserved word for Version 9.1.
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
1204 Application Programming and SQL Guide
||
|
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
Note: 1. New reserved word for Version 9.1.
J
JAR
JOIN
K
KEEP1
KEY
Note: 1. New reserved word for Version 9.1.
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
Note: 1. New reserved word for Version 9.1.
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
Note: 1. New reserved word for Version 9.1.
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
Note: 1. New reserved word for Version 9.1.
1206 Application Programming and SQL Guide
|
|
|
|
|||||||
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
Note: 1. New reserved word for Version 9.1.
T
TABLE
TABLESPACE
THEN
TO
TRIGGER
TRUNCATE1
TYPE1
Note: 1. New reserved word for Version 9.1.
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
Note: 1. New reserved word for Version 9.1.
Appendix G. Reserved schema names and reserved words 1207
|
|
|
||
||
Y
YEAR
YEARS
1208 Application Programming and SQL Guide
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
© Copyright IBM Corp. 1983, 2007 1209
Table 249. Actions allowed on SQL statements in DB2 for z/OS (continued)
SQL statement Executable
Interactively
or
dynamically
prepared
Processed by
Requesting
system Server Precompiler
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
1210 Application Programming and SQL Guide
||||||
||||||
|||||||
|||||||
Table 249. Actions allowed on SQL statements in DB2 for z/OS (continued)
SQL statement Executable
Interactively
or
dynamically
prepared
Processed by
Requesting
system Server Precompiler
SET host-variable = CURRENT
APPLICATION ENCODING
SCHEME
Y Y Y
SET host-variable = CURRENT
DATE
Y Y
SET host-variable = CURRENT
DEGREE
Y Y
SET host-variable = CURRENT
MEMBER
Y Y
SET host-variable = CURRENT
PACKAGESET
Y Y
SET host-variable = CURRENT
PATH
Y Y
SET host-variable = CURRENT
QUERY OPTIMIZATION LEVEL
Y Y
SET host-variable = CURRENT
SERVER
Y Y
SET host-variable = CURRENT
SQLID
Y Y
SET host-variable = CURRENT
TIME
Y Y
SET host-variable = CURRENT
TIMESTAMP
Y Y
SET host-variable = CURRENT
TIMEZONE
Y Y
SET PATH Y Y Y
SET SCHEMA Y Y Y
SET transition-variable =
CURRENT DATE
Y Y
SET transition-variable =
CURRENT DEGREE
Y Y
SET transition-variable =
CURRENT PATH
Y Y
SET transition-variable =
CURRENT QUERY
OPTIMIZATION LEVEL
Y Y
SET transition-variable =
CURRENT SQLID
Y Y
SET transition-variable =
CURRENT TIME
Y Y
SET transition-variable =
CURRENT TIMESTAMP
Y Y
SET transition-variable =
CURRENT TIMEZONE
Y Y
SIGNAL6 Y Y
Appendix H. Characteristics of SQL statements in DB2 for z/OS 1211
Table 249. Actions allowed on SQL statements in DB2 for z/OS (continued)
SQL statement Executable
Interactively
or
dynamically
prepared
Processed by
Requesting
system Server Precompiler
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
1212 Application Programming and SQL Guide
||||||
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
Appendix H. Characteristics of SQL statements in DB2 for z/OS 1213
|||||
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
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
1214 Application Programming and SQL Guide
||||||
||||||
|||||
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
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
Appendix H. Characteristics of SQL statements in DB2 for z/OS 1215
|||||
||
||
|
|
||||
|||
|||
|||
|||
|||
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
1216 Application Programming and SQL Guide
|
|
|
||||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
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 H. Characteristics of SQL statements in DB2 for z/OS 1217
|
|
|
||||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
|||
||||
|||
|||
|||
|||
|||
|||
|||
|
|||
|||
|||
1218 Application Programming and SQL Guide
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
© Copyright IBM Corp. 1983, 2007 1219
Table 252. Program preparation options for packages (continued)
Generic option description Equivalent for Requesting DB2
Bind or
Precompile
Option DB2 Server Support
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
1220 Application Programming and SQL Guide
||||||
|||
Table 252. Program preparation options for packages (continued)
Generic option description Equivalent for Requesting DB2
Bind or
Precompile
Option DB2 Server Support
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
1222 Application Programming and SQL Guide
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:
© Copyright IBM Corp. 1983, 2007 1223
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
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.
“Store an XML document from
an MQ message queue in DB2
tables (DXXMQSHRED)” on
page 1245
DXXMQINSERTCLOB 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.
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
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. DXXMQSHREDCLOB 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
(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
an MQ message queue in DB2
tables (DXXMQINSERTALL)”
on page 1252
DXXMQSHREDALL 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. DXXMQSHREDALL is intended for XML
documents with a length of up to 3 KB.
“Store XML documents from
an MQ message queue in DB2
tables (DXXMQSHREDALL)”
on page 1255
DXXMQSHREDALLCLOB 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. DXXMQSHREDALLCLOB is
intended for XML documents with a length of up to
1MB.
“Store large XML documents
from an MQ message queue in
DB2 tables
(DXXMQSHREDALLCLOB)”
on page 1257
DXXMQINSERTALLCLOB 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. DXXMQINSERTALLCLOB
is intended for XML documents with a length of up to
1 MB.
“Store large XML documents
from an MQ message queue in
DB2 tables
(DXXMQINSERTALLCLOB)”
on page 1259
1224 Application Programming and SQL Guide
Table 253. MQ XML stored procedures (continued)
Stored procedure name Function For information, see:
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.
“Send XML documents to an
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.
“Send XML documents to an
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
Stored procedure name Function For information, see:
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 ) ��
1226 Application Programming and SQL Guide
|
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.
Appendix J. DB2-supplied stored procedures 1227
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.
1228 Application Programming and SQL Guide
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.
This is an input parameter of type CHAR(8).
CICS-level
Specifies the level of the target CICS subsystem:
Appendix J. DB2-supplied stored procedures 1229
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.
This is an input parameter of type CHAR(8).
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.
This is an input parameter of type CHAR(8).
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.
This is an input parameter of type CHAR(4).
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.
1230 Application Programming and SQL Guide
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);
Appendix J. DB2-supplied stored procedures 1231
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. */
/*****************************************/
1232 Application Programming and SQL Guide
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.
Appendix J. DB2-supplied stored procedures 1233
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).
1234 Application Programming and SQL Guide
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
Appendix J. DB2-supplied stored procedures 1235
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:
1236 Application Programming and SQL Guide
||
�� 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.
Appendix J. DB2-supplied stored procedures 1237
|||
|
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.
1238 Application Programming and SQL Guide
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)
Appendix J. DB2-supplied stored procedures 1239
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
1240 Application Programming and SQL Guide
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 ) ��
Appendix J. DB2-supplied stored procedures 1241
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.
EXEC SQL BEGIN DECLARE SECTION;
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 */
EXEC SQL END DECLARE SECTION;
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
1242 Application Programming and SQL Guide
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
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 DXXMQINSERT
v Ownership of the stored procedure
v SYSADM authority
DXXMQINSERT syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
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.
Appendix J. DB2-supplied stored procedures 1243
�� 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
an input parameter of type VARCHAR(80).
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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
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 */
1244 Application Programming and SQL Guide
/* 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 */
EXEC SQL END DECLARE SECTION;
/* 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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
Environment for DXXMQSHRED
DXXMQSHRED runs in a WLM-established stored procedure address space and
uses the Resource Recovery Services attachment facility to connect to DB2.
Appendix J. DB2-supplied stored procedures 1245
DXXMQSHRED requires that WebSphere MQ and XML Extender are installed.
Authorization required for DXXMQSHRED
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 DXXMQSHRED
v Ownership of the stored procedure
v SYSADM authority
DXXMQSHRED syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQSHRED. Because the linkage convention for DXXMQSHRED 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 .DXXMQSHRED
DMQXML2C ( service-name ,
NULL policy-name ,
NULL DAD-file-name, �
� status ) ��
DXXMQSHRED 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.
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
an input parameter of type VARCHAR(80).
status
Contains information that indicates whether DXXMQSHRED 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.
1246 Application Programming and SQL Guide
v sqlcode is 0 if DXXMQSHRED ran successfully, or the SQLCODE from the
most recent unsuccessful SQL statement if DXXMQSHRED 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 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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
char serviceName[48]; /* WebSphere MQ service name */
char policyName[48]; /* WebSphere MQ policy name */
char dadFileName[30]; /* DAD file name */
char status[20]; /* Status of DXXMQSHRED call */
/* DXXMQSHRED is GENERAL WITH NULLS, so parameters need indicators */
short serviceName_ind; /* Indicator var for serviceName */
short policyName_ind; /* Indicator var for policyName */
short dadFileName_ind; /* Indicator var for dadFileName */
short status_ind; /* Indicator var for status */
EXEC SQL END DECLARE SECTION;
/* 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 DAD file name */
strcpy(dadFileName,"/tmp/neworder2.dad");
/* 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.DXXMQSHRED(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:dadFileName:dadFileName_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);
DXXMQSHRED output
If DXXMQSHRED 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 DXXMQSHRED does not execute
successfully, the contents of the status parameter indicate the problem.
Appendix J. DB2-supplied stored procedures 1247
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
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
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 DXXMQINSERTCLOB
v Ownership of the stored procedure
v SYSADM authority
DXXMQINSERTCLOB syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
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
DMQXML2C ( service-name ,
NULL policy-name ,
NULL �
� XML-collection-name, status ) ��
DXXMQINSERTCLOB 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.
1248 Application Programming and SQL Guide
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
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:
v dxx-rc is the return code from accessing XML Extender. dxx-rc values are
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.
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 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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
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 DXXMQINSERTCLOB call */
/* DXXMQINSERTCLOB 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 */
EXEC SQL END DECLARE SECTION;
/* 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 */
Appendix J. DB2-supplied stored procedures 1249
/* 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.DXXMQINSERTCLOB(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:collectionName:collectionName_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);
DXXMQINSERTCLOB output
If DXXMQINSERTCLOB 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 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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
Environment for DXXMQSHREDCLOB
DXXMQSHREDCLOB runs in a WLM-established stored procedure address space
and uses the Resource Recovery Services attachment facility to connect to DB2.
DXXMQSHREDCLOB requires that WebSphere MQ and XML Extender are
installed.
Authorization required for DXXMQSHREDCLOB
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 DXXMQSHREDCLOB
v Ownership of the stored procedure
v SYSADM authority
DXXMQSHREDCLOB syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQSHREDCLOB. Because the linkage convention for DXXMQSHREDCLOB is
GENERAL WITH NULLS, if you pass parameters in host variables, you need to
1250 Application Programming and SQL Guide
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 .DXXMQSHREDCLOB
DMQXML2C ( service-name ,
NULL policy-name ,
NULL DAD-file-name, �
� status ) ��
DXXMQSHREDCLOB 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.
DAD-file-name
Specifies the name of the (DAD) file that maps the XML document to DB2
tables. DAD-file-name is an input parameter of type VARCHAR(80).
status
Contains information that indicates whether DXXMQSHREDCLOB 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 DXXMQSHREDCLOB ran successfully, or the SQLCODE from
the most recent unsuccessful SQL statement if DXXMQSHREDCLOB 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 DXXMQSHREDCLOB invocation
The following example calls the single-phase commit version of
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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
Appendix J. DB2-supplied stored procedures 1251
char serviceName[48]; /* WebSphere MQ service name */
char policyName[48]; /* WebSphere MQ policy name */
char dadFileName[30]; /* DAD file name */
char status[20]; /* Status of DXXMQSHREDCLOB call */
/* DXXMQSHREDCLOB is GENERAL WITH NULLS, so parameters need indicators */
short serviceName_ind; /* Indicator var for serviceName */
short policyName_ind; /* Indicator var for policyName */
short dadFileName_ind; /* Indicator var for dadFileName */
short status_ind; /* Indicator var for status */
EXEC SQL END DECLARE SECTION;
/* 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 DAD file name */
strcpy(dadFileName,"/tmp/neworder2.dad");
/* 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.DXXMQSHREDCLOB(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:dadFileName:dadFileName_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);
DXXMQSHREDCLOB output
If DXXMQSHREDCLOB 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 DXXMQSHREDCLOB does not
execute successfully, the contents of the status parameter indicate the problem.
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
Environment for DXXMQINSERTALL
DXXMQINSERTALL runs in a WLM-established stored procedure address space
and uses the Resource Recovery Services attachment facility to connect to DB2.
1252 Application Programming and SQL Guide
DXXMQINSERTALL requires that WebSphere MQ and XML Extender are installed.
Authorization required for DXXMQINSERTALL
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 DXXMQINSERTALL
v Ownership of the stored procedure
v SYSADM authority
DXXMQINSERTALL syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQINSERTALL. Because the linkage convention for DXXMQINSERTALL 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 .DXXMQINSERTALL
DMQXML2C ( service-name ,
NULL policy-name ,
NULL �
� XML-collection-name, status ) ��
DXXMQINSERTALL option descriptions
service-name
Specifies the service point that is the logical WebSphere MQ destination from
which the messages are 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
messages. 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 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
input parameter of type VARCHAR(80).
status
Contains information that indicates whether DXXMQINSERTALL 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.
Appendix J. DB2-supplied stored procedures 1253
v sqlcode is 0 if DXXMQINSERTALL ran successfully, or the SQLCODE from
the most recent unsuccessful SQL statement if DXXMQINSERTALL 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 DXXMQINSERTALL invocation
The following example calls the single-phase commit version of
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
DSN8QXSI in DSN910.SDSNSAMP.
#include "dxx.h"
#include "dxxrc.h"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
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 DXXMQINSERTALL call */
/* DXXMQINSERTALL 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 */
EXEC SQL END DECLARE SECTION;
/* 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 indicators for the output parameter */
status_ind = -1;
/* Call the store procedure */
EXEC SQL CALL DMQXML1C.DXXMQINSERTALL(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:collectionName:collectionName_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);
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
successfully, the contents of the status parameter indicate the problem.
1254 Application Programming and SQL Guide
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
Environment for DXXMQSHREDALL
DXXMQSHREDALL runs in a WLM-established stored procedure address space
and uses the Resource Recovery Services attachment facility to connect to DB2.
DXXMQSHREDALL requires that WebSphere MQ and XML Extender are installed.
Authorization required for DXXMQSHREDALL
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 DXXMQSHREDALL
v Ownership of the stored procedure
v SYSADM authority
DXXMQSHREDALL syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQSHREDALL. Because the linkage convention for DXXMQSHREDALL 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 .DXXMQSHREDALL
DMQXML2C ( service-name ,
NULL policy-name ,
NULL DAD-file-name, �
� status ) ��
DXXMQSHREDALL option descriptions
service-name
Specifies the service point that is the logical WebSphere MQ destination from
which messages are 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.
Appendix J. DB2-supplied stored procedures 1255
policy-name
Specifies the WebSphere MQ AMI service policy that is used to handle the
messages. 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.
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 DXXMQSHREDALL runs.DAD-file-name
is an input parameter of type VARCHAR(80).
status
Contains information that indicates whether DXXMQSHREDALL 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 DXXMQSHREDALL ran successfully, or the SQLCODE from
the most recent unsuccessful SQL statement if DXXMQSHREDALL 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 DXXMQSHREDALL invocation
The following example calls the single-phase commit version of
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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
char serviceName[48]; /* WebSphere MQ service name */
char policyName[48]; /* WebSphere MQ policy name */
char dadFileName[30]; /* DAD file name */
char status[20]; /* Status of DXXMQSHREDALL call */
/* DXXMQSHREDALL is GENERAL WITH NULLS, so parameters need indicators */
short serviceName_ind; /* Indicator var for serviceName */
short policyName_ind; /* Indicator var for policyName */
short dadFileName_ind; /* Indicator var for dadFileName */
short status_ind; /* Indicator var for status */
EXEC SQL END DECLARE SECTION;
/* 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 DAD file name */
strcpy(dadFileName,"/tmp/neworder2.dad");
/* Initialize the output variable */
status[0] = ’\0’;
/* Set the indicators to 0 for the parameters that have non-null */
/* values */
1256 Application Programming and SQL Guide
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.DXXMQSHREDALL(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:dadFileName:dadFileName_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);
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
execute successfully, the contents of the status parameter indicate the problem.
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
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
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 DXXMQSHREDALLCLOB
v Ownership of the stored procedure
v SYSADM authority
DXXMQSHREDALLCLOB syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
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
Appendix J. DB2-supplied stored procedures 1257
indicators for input host variables must be initialized before you execute the CALL
statement.
�� CALL DMQXML1C .DXXMQSHREDALLCLOB
DMQXML2C ( service-name ,
NULL policy-name ,
NULL �
� DAD-file-name, status ) ��
DXXMQSHREDALLCLOB option descriptions
service-name
Specifies the service point that is the logical WebSphere MQ destination from
which messages are 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
messages. 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.
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 DXXMQSHREDALLCLOB runs.
DAD-file-name is an input parameter of type VARCHAR(80).
status
Contains information that indicates whether DXXMQSHREDALLCLOB 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 DXXMQSHREDALLCLOB ran successfully, or the SQLCODE
from the most recent unsuccessful SQL statement if
DXXMQSHREDALLCLOB 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 DXXMQSHREDALLCLOB invocation
The following example calls the single-phase commit version of
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.
1258 Application Programming and SQL Guide
#include "dxx.h"
#include "dxxrc.h"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
char serviceName[48]; /* WebSphere MQ service name */
char policyName[48]; /* WebSphere MQ policy name */
char dadFileName[30]; /* DAD file name */
char status[20]; /* Status of DXXMQSHREDALLCLOB call */
/* DXXMQSHREDALLCLOB is GENERAL WITH NULLS, so parameters need indicators */
short serviceName_ind; /* Indicator var for serviceName */
short policyName_ind; /* Indicator var for policyName */
short dadFileName_ind; /* Indicator var for dadFileName */
short status_ind; /* Indicator var for status */
EXEC SQL END DECLARE SECTION;
/* 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 DAD file name */
strcpy(dadFileName,"/tmp/neworder2.dad");
/* 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.DXXMQSHREDALLCLOB(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:dadFileName:dadFileName_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);
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
execute successfully, the contents of the status parameter indicate the problem.
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
Appendix J. DB2-supplied stored procedures 1259
Environment for DXXMQINSERTALLCLOB
DXXMQINSERTALLCLOB runs in a WLM-established stored procedure address
space and uses the Resource Recovery Services attachment facility to connect to
DB2.
DXXMQINSERTALLCLOB requires that WebSphere MQ and XML Extender are
installed.
Authorization required for DXXMQINSERTALLCLOB
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 DXXMQINSERTALLCLOB
v Ownership of the stored procedure
v SYSADM authority
DXXMQINSERTALLCLOB syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQINSERTALLCLOB. Because the linkage convention for
DXXMQINSERTALLCLOB 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 .DXXMQINSERTALLCLOB
DMQXML2C ( service-name ,
NULL policy-name ,
NULL �
� XML-collection-name, status ) ��
DXXMQINSERTALLCLOB option descriptions
service-name
Specifies the service point that is the logical WebSphere MQ destination from
which the messages are 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
messages. 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 documents are to be inserted. XML-collection-name
must be specified, and must be the name of a valid XML collection that exists
1260 Application Programming and SQL Guide
on the system on which DXXMQINSERTALLCLOB runs. XML-collection-name is
an input parameter of type VARCHAR(80).
status
Contains information that indicates whether DXXMQINSERTALLCLOB 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 DXXMQINSERTALLCLOB ran successfully, or the SQLCODE
from the most recent unsuccessful SQL statement if
DXXMQINSERTALLCLOB 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 DXXMQINSERTALLCLOB invocation
The following example calls the single-phase commit version of
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
DSN8QXSI in DSN910.SDSNSAMP.
#include "dxx.h"
#include "dxxrc.h"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
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 DXXMQINSERTALLCLOB call */
/* DXXMQINSERTALLCLOB 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 */
EXEC SQL END DECLARE SECTION;
/* 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 indicators for the output parameter */
status_ind = -1;
/* Call the store procedure */
EXEC SQL CALL DMQXML1C.DXXMQINSERTALLCLOB(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:collectionName:collectionName_ind,
:status:status_ind);
printf("SQLCODE from CALL: %d\n",sqlca.sqlcode);
Appendix J. DB2-supplied stored procedures 1261
/* 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);
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
successfully, the contents of the status parameter indicate the problem.
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
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
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 DXXMQGEN
v Ownership of the stored procedure
v SYSADM authority
DXXMQGEN syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQGEN. Because the linkage convention for DXXMQGEN 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 .DXXMQGEN
DMQXML2C ( service-name ,
NULL policy-name ,
NULL DAD-file-name, �
� override-type ,
NULL override ,
NULL max-rows ,
NULL num-msgs, status ) ��
1262 Application Programming and SQL Guide
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.
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.
DAD-file-name
Specifies the name of the (DAD) file that maps the XML documents 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 DXXMQGEN runs. DAD-file-name is an
input parameter of type VARCHAR(80).
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).
Appendix J. DB2-supplied stored procedures 1263
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:
v dxx-rc is the return code from accessing XML Extender. dxx-rc values are
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.
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 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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
char serviceName[48]; /* WebSphere MQ service name */
char policyName[48]; /* WebSphere MQ policy name */
char dadFileName[80]; /* DAD file name */
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 serviceName_ind; /* Indicator var for serviceName */
short policyName_ind; /* Indicator var for policyName */
short dadFileName_ind; /* Indicator var for dadFileName */
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 */
short status_ind; /* Indicator var for status */
EXEC SQL END DECLARE SECTION;
/* 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 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’;
1264 Application Programming and SQL Guide
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’;
/* Set the indicators to 0 for the parameters that have non-null */
/* values */
dadFileName_ind = 0;
serviceName_ind = 0;
policyName_ind = 0;
maxrow_ind = 0;
/* Initialize the indicators for the output parameters */
numrow_ind = -1;
status_ind = -1;
/* Call the store procedure */
EXEC SQL CALL DMQXML1C.DXXMQGEN(: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);
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
successfully, the contents of the status parameter indicate the problem.
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
Environment for DXXMQRETRIEVE
DXXMQRETRIEVE runs in a WLM-established stored procedure address space and
uses the Resource Recovery Services attachment facility to connect to DB2.
DXXMQRETRIEVE requires that WebSphere MQ and XML Extender are installed.
Authorization required for DXXMQRETRIEVE
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 DXXMQRETRIEVE
v Ownership of the stored procedure
Appendix J. DB2-supplied stored procedures 1265
v SYSADM authority
DXXMQRETRIEVE syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQRETRIEVE. Because the linkage convention for DXXMQRETRIEVE 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 .DXXMQRETRIEVE
DMQXML2C ( service-name ,
NULL policy-name ,
NULL �
� XML-collection-name, override-type ,
NULL override ,
NULL max-rows ,
NULL num-msgs, status ) ��
DXXMQRETRIEVE 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.
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 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
Specifies what the override parameter does. Possible values are:
NO_OVERRIDE
The override parameter does not override the XML collection. 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 XML
collection.
1266 Application Programming and SQL Guide
XML_OVERRIDE
The DAD file uses RDB_node mapping, and the override parameter
contains conditions that override the conditions in the XML collection.
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-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 DXXMQRETRIEVE
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 DXXMQRETRIEVE sends to the
MQ message queue.
num-rows is an output parameter of type INTEGER.
status
Contains information that indicates whether DXXMQRETRIEVE 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 DXXMQRETRIEVE ran successfully, or the SQLCODE from the
most recent unsuccessful SQL statement if DXXMQRETRIEVE ran
unsuccessfully.
Appendix J. DB2-supplied stored procedures 1267
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 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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
char serviceName[48]; /* WebSphere MQ service name */
char policyName[48]; /* WebSphere MQ policy name */
char collectionName[80]; /* XML collection name */
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 DXXMQRETRIEVE call */
/* DXXMQRETRIEVE 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 dadFileName */
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 */
short status_ind; /* Indicator var for status */
EXEC SQL END DECLARE SECTION;
/* 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");
/* 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’;
/* Set the indicators to 0 for the parameters that have non-null */
/* values */
collectionName_ind = 0;
serviceName_ind = 0;
policyName_ind = 0;
maxrow_ind = 0;
/* Initialize the indicators for the output parameters */
numrow_ind = -1;
status_ind = -1;
/* Call the store procedure */
EXEC SQL CALL DMQXML1C.DXXMQRETRIEVE(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:collectionName:collectionName_ind,
:overrideType:ovtype_ind,
1268 Application Programming and SQL Guide
: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);
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
successfully, the contents of the status parameter indicate the problem.
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
Environment for DXXMQGENCLOB
DXXMQGENCLOB runs in a WLM-established stored procedure address space
and uses the Resource Recovery Services attachment facility to connect to DB2.
DXXMQGENCLOB requires that WebSphere MQ and XML Extender are installed.
Authorization required for DXXMQGENCLOB
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 DXXMQGENCLOB
v Ownership of the stored procedure
v SYSADM authority
DXXMQGENCLOB syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQGENCLOB. Because the linkage convention for DXXMQGENCLOB 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.
Appendix J. DB2-supplied stored procedures 1269
�� CALL DMQXML1C .DXXMQGENCLOB
DMQXML2C ( service-name ,
NULL policy-name ,
NULL DAD-file-name, �
� override-type ,
NULL override ,
NULL max-rows ,
NULL num-msgs, status ) ��
DXXMQGENCLOB 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.
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.
DAD-file-name
Specifies the name of the (DAD) file that maps the XML documents 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 DXXMQGENCLOB runs. DAD-file-name
is an input parameter of type VARCHAR(80).
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.
1270 Application Programming and SQL Guide
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 DXXMQGENCLOB
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 DXXMQGENCLOB sends to the
MQ message queue.
num-rows is an output parameter of type INTEGER.
status
Contains information that indicates whether DXXMQGENCLOB 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 DXXMQGENCLOB ran successfully, or the SQLCODE from the
most recent unsuccessful SQL statement if DXXMQGENCLOB 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 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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
char serviceName[48]; /* WebSphere MQ service name */
char policyName[48]; /* WebSphere MQ policy name */
char dadFileName[80]; /* DAD file name */
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 DXXMQGENCLOB call */
/* DXXMQGENCLOB is GENERAL WITH NULLS, so parameters need indicators */
short serviceName_ind; /* Indicator var for serviceName */
short policyName_ind; /* Indicator var for policyName */
short dadFileName_ind; /* Indicator var for dadFileName */
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 */
short status_ind; /* Indicator var for status */
EXEC SQL END DECLARE SECTION;
/* Status fields */
int dxx_rc=0;
Appendix J. DB2-supplied stored procedures 1271
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 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’;
/* Set the indicators to 0 for the parameters that have non-null */
/* values */
dadFileName_ind = 0;
serviceName_ind = 0;
policyName_ind = 0;
maxrow_ind = 0;
/* Initialize the indicators for the output parameters */
numrow_ind = -1;
status_ind = -1;
/* Call the store procedure */
EXEC SQL CALL DMQXML2C.DXXMQGENCLOB(: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);
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
successfully, the contents of the status parameter indicate the problem.
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:
v A single-phase commit version, with schema name DMQXML1C.
v A two-phase commit version, with schema name DMQXML2C.
1272 Application Programming and SQL Guide
Environment for DXXMQRETRIEVECLOB
DXXMQRETRIEVECLOB runs in a WLM-established stored procedure address
space and uses the Resource Recovery Services attachment facility to connect to
DB2.
DXXMQRETRIEVECLOB requires that WebSphere MQ and XML Extender are
installed.
Authorization required for DXXMQRETRIEVECLOB
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 DXXMQRETRIEVECLOB
v Ownership of the stored procedure
v SYSADM authority
DXXMQRETRIEVECLOB syntax diagram
The following syntax diagram shows the SQL CALL statement for invoking
DXXMQRETRIEVECLOB. Because the linkage convention for
DXXMQRETRIEVECLOB 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 .DXXMQRETRIEVECLOB
DMQXML2C ( service-name ,
NULL policy-name ,
NULL �
� XML-collection-name, override-type ,
NULL override ,
NULL max-rows ,
NULL num-msgs, status ) ��
DXXMQRETRIEVECLOB 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.
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 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
Appendix J. DB2-supplied stored procedures 1273
system on which DXXMQRETRIEVECLOB runs. XML-collection-name is an
input parameter of type VARCHAR(80).
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
DXXMQRETRIEVECLOB 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 DXXMQRETRIEVECLOB sends to
the MQ message queue.
num-rows is an output parameter of type INTEGER.
status
Contains information that indicates whether DXXMQRETRIEVECLOB 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 DXXMQRETRIEVECLOB ran successfully, or the SQLCODE
from the most recent unsuccessful SQL statement if
DXXMQRETRIEVECLOB 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).
1274 Application Programming and SQL Guide
Example of DXXMQRETRIEVECLOB invocation
The following example calls the single-phase commit version of
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"
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
char serviceName[48]; /* WebSphere MQ service name */
char policyName[48]; /* WebSphere MQ policy name */
char collectionName[80]; /* XML collection name */
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 DXXMQRETRIEVECLOB call */
/* DXXMQRETRIEVECLOB 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 dadFileName */
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 */
short status_ind; /* Indicator var for status */
EXEC SQL END DECLARE SECTION;
/* 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");
/* 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’;
/* Set the indicators to 0 for the parameters that have non-null */
/* values */
collectionName_ind = 0;
serviceName_ind = 0;
policyName_ind = 0;
maxrow_ind = 0;
/* Initialize the indicators for the output parameters */
numrow_ind = -1;
status_ind = -1;
/* Call the store procedure */
EXEC SQL CALL DMQXML1C.DXXMQRETRIEVECLOB(:serviceName:serviceName_ind,
:policyName:policyName_ind,
:collectionName:collectionName_ind,
:overrideType:ovtype_ind,
:override:ov_ind,
:max_row:maxrow_ind,
:num_row:numrow_ind,
:status:status_ind);
Appendix J. DB2-supplied stored procedures 1275
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);
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 ��
1276 Application Programming and SQL Guide
||||||||||||||||||||||||||||||||||||||||||||||
||||||||||||||||||||
|||
|
|||||
|
|
|
||
|
|||
|
|||
||||||||
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:
The following syntax diagram shows the CALL statement for invoking
XSR_ADDSCHEMADOC.
Appendix J. DB2-supplied stored procedures 1277
||||||
||||
||||
|
|
||||||
||
|
||||
|
||
|
||
|
|||
XSR_ADDSCHEMADOC 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 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 ��
1278 Application Programming and SQL Guide
||||||||||||||||||||||||||||||||||||||||
||||||||||||||||||||
||||
|||
||||||||
||||||||
||||
||||
|
|
|||||
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:
The following syntax diagram shows the CALL statement for invoking
XSR_COMPLETE.
�� SYSPROC
CALL
.
XSR_COMPLETE
(
rschema
,
name
,
schemaproperties
,
�
� issuedfordecomposition ) ��
XSR_COMPLETE 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 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.
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.
Appendix J. DB2-supplied stored procedures 1279
||
|
||||
|
|
|
|
||
|
|||
|||||||||||||||||||||||||||||
||||||||||
||||
|||
||||||||
|||||
||||
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:
The following syntax diagram shows the CALL statement for invoking
XSR_REMOVE.
XSR_REMOVE 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 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
)
��
1280 Application Programming and SQL Guide
|||||||||||||||||||||||||||||||
|||
|
|
|||||
||
|||
|
|
|
|||
|
|||
|
|||
||||||||
|
|
|||
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:
The following syntax diagram shows the CALL statement for invoking
XDBDECOMPXML.
XDBDECOMPXML 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 argument of type VARCHAR(128) that specifies the name of the XML
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 J. DB2-supplied stored procedures 1281
|||||||||||||||||||||||||||||||||||||||||||||
|||
||
||||||||
|
|
|
|||
|
|||
|
|||
||||||||
|||
|||
1282 Application Programming and SQL Guide
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
© Copyright IBM Corp. 1983, 2007 1283
||||
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.
1284 Application Programming and SQL Guide
||
||
||
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
1286 Application Programming and SQL Guide
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.
© Copyright IBM Corp. 1983, 2007 1287
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
1288 Application Programming and SQL Guide
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
1290 Application Programming and SQL Guide
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.
© Copyright IBM Corp. 1983, 2007 1291
||
|||
||||
||||
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.
1292 Application Programming and SQL Guide
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.
1294 Application Programming and SQL Guide
||||
|||||
||
|||||
|||
||
||
||||
||
|||
|
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.
1296 Application Programming and SQL Guide
|||||
|||
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.
1298 Application Programming and SQL Guide
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.
1300 Application Programming and SQL Guide
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.
1302 Application Programming and SQL Guide
|
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.
1304 Application Programming and SQL Guide
||||
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.
1306 Application Programming and SQL Guide
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.
1308 Application Programming and SQL Guide
|||
||||||||||
||||||||||
|
|
||||
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.
1310 Application Programming and SQL Guide
|||
|||||||
|||||||
||||||
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.
1312 Application Programming and SQL Guide
|||||
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.
1314 Application Programming and SQL Guide
|||||
|
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.
1316 Application Programming and SQL Guide
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.
1318 Application Programming and SQL Guide
|||
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
The result of a join operation that includes the matched rows of both tables
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.
1320 Application Programming and SQL Guide
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.
1322 Application Programming and SQL Guide
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,
1324 Application Programming and SQL Guide
||||
||
|||||
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
The result of a join operation that includes the matched rows of both tables
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.
1326 Application Programming and SQL Guide
|||
|||||
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
1328 Application Programming and SQL Guide
||
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.
1330 Application Programming and SQL Guide
||||
||
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
1332 Application Programming and SQL Guide
|||
||
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
The result of a join operation that includes the matched rows of both tables
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.
1334 Application Programming and SQL Guide
|||||
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
The specification of the desired placement of the cursor as part of a FETCH
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
The specification of the desired placement of the cursor as part of a FETCH
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.
1336 Application Programming and SQL Guide
|||
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.
1338 Application Programming and SQL Guide
|||||
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
1340 Application Programming and SQL Guide
||||
||||
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.
1342 Application Programming and SQL Guide
|||
||||
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.
1344 Application Programming and SQL Guide
||||
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.
1346 Application Programming and SQL Guide
||||
||
|||
|||
|||
||||
||||
|||
||||
||||
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.
1348 Application Programming and SQL Guide
||
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.
1350 Application Programming and SQL Guide
||
||||
||
||||
|||
||||
||||||
||
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
||||||
||||
||
||||
|
||
||
1352 Application Programming and SQL Guide
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
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
© Copyright IBM Corp. 1983, 2007 1353
Table 257. DB2 Version 9.1 for z/OS book titles (continued)
Title
Publication
number
Available in
information
center
Available in
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.
1354 Application Programming and SQL Guide
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
Table 258. Related product information resource locations (continued)
Related product Information resources
IMS 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 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:
v Information center: http://publib.boulder.ibm.com/infocenter/imzic
v Library Web site: http://www.ibm.com/software/data/db2imstools/library.html
This product is also known as DB2 DataPropagator.
z/Architecture Library Center site: http://www.ibm.com/servers/eserver/zseries/zos/bkserv/
1356 Application Programming and SQL Guide
Table 258. Related product information resource locations (continued)
Related product Information resources
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
– 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
1358 Application Programming and SQL Guide
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
binary host variable 195
declaring tables 187
LOB variable 197
LOB variable array 204
numeric host variable 191
numeric host variable array 199
result set locator 196
sample application 1103
C/C++ application programBINARY variable array 202
character host variable 191
character host variable array 200
coding SQL statements 185
constants 215
data type compatibility 215
C/C++ application program (continued)data types 208
DCLGEN support 160
declaring views 187
examples 1137
fixed-length string 217
graphic host variable 193
graphic host variable array 202
host variable array, declaring 188
host variable, declaring 188
INCLUDE statement 187
including SQLCA 185
including SQLDA 186
indicator variable 217
indicator variable array 217
naming convention 187
precompiler option defaults 558
ROWID variable 199
ROWID variable array 205
SQLCODE 185
SQLSTATE 185
table locator 196
VARBINARY variable array 202
variable declaration 212
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
programming considerations 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
table space scan 909
with list prefetch 935
COALESCE function 61
COBOL application programassignment rules 252
binary host variable 232
character host variable 228
fixed-length string 228
varying-length string 229
character host variable array 236
fixed-length string array 236
varying-length string array 237
coding SQL statements 220
compiling 560
controlling CCSID 251
data type compatibility 254
data types 247
DB2 precompiler option defaults 558
DCLGEN support 160
declaring tables 223
declaring views 223
defining the SQLDA 222
dynamic SQL 699
FILLER entry name 253
graphic host variable 230
graphic host variable array 239
host variabledeclaring 226
use of hyphens 225
host variable arraydeclaring 226
INCLUDE statement 224
including SQLCA 221
indicator variable 255
indicator variable array 255
LOB variable 233
LOB variable array 240
naming convention 224
X-4 Application Programming and SQL Guide
COBOL application program (continued)numeric host variable 227
numeric host variable array 234
object-oriented extensions 258
options 224, 225
preparation 560
record description from DCLGEN 159
resetting SQL-INIT-FLAG 226
result set locator 232
ROWID variable 234
ROWID variable array 241
sample program 1125
SQLCODE 220
SQLSTATE 220
table locator 233
variable declaration 251
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
stored procedures 814
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
language examples 976
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
language examples 1031
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
table space scan 909
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
end-of-data condition 131
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
X-6 Application Programming and SQL Guide
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
result set locator 800
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
INCLUDE statement 159
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
precompiler option 552
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
language examples 981
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
X-8 Application Programming and SQL Guide
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
program preparation 1111
DSNTEP4 sample programhow to run 1111
parameters 1112
program preparation 1111
DSNTIAC subroutineassembler 184
C 220
COBOL 258
PL/I 293
DSNTIAD sample programhow to run 1111
parameters 1112
program preparation 1111
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
program preparation 1111
DSNTIR subroutine 268
DSNTP2DP tool 508
authorization 508
option descriptions 509
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
invocation example 1271
invocation syntax 1269
output 1272
parameter descriptions 1270
DXXMQINSERT stored proceduredescription 1243
invocation example 1244
invocation syntax 1243
output 1245
parameter descriptions 1244
DXXMQINSERTALL stored proceduredescription 1252
invocation example 1254
invocation syntax 1253
output 1254
parameter descriptions 1253
DXXMQINSERTALLCLOB stored proceduredescription 1259
invocation example 1261
invocation syntax 1260
output 1262
parameter descriptions 1260
DXXMQINSERTCLOB stored proceduredescription 1248
invocation example 1249
invocation syntax 1248
output 1250
parameter descriptions 1248
DXXMQRETRIEVE stored proceduredescription 1265
invocation example 1268
invocation syntax 1266
output 1269
parameter descriptions 1266
DXXMQRETRIEVECLOB stored proceduredescription 1272
invocation example 1275
invocation syntax 1273
DXXMQRETRIEVECLOB stored procedure (continued)output 1276
parameter descriptions 1273
DXXMQSHRED stored proceduredescription 1245
invocation example 1247
invocation syntax 1246
output 1247
parameter descriptions 1246
DXXMQSHREDALL stored proceduredescription 1255
invocation example 1256
invocation syntax 1255
output 1257
parameter descriptions 1255
DXXMQSHREDALLCLOB stored proceduredescription 1257
invocation example 1258
invocation syntax 1257
output 1259
parameter descriptions 1258
DXXMQSHREDCLOB stored proceduredescription 1250
invocation example 1251
invocation syntax 1250
output 1252
parameter descriptions 1251
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
X-10 Application Programming and SQL Guide
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
fetch orientation 141
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 DESCRIPTOR clause 694
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
coding SQL statements 259
constant syntax 266
data type compatibility 267
data types 264
declaring tables 261
declaring views 261
defining the SQLDA 260
host variable, declaring 262
INCLUDE statement 261
including SQLCA 259
indicator variable 267
LOB variable 263
naming convention 261
Index X-11
Fortran application program (continued)numeric host variable 262
parallel option 262
precompiler option defaults 558
result set locator 263
ROWID variable 264
SQLCODE 259
SQLSTATE 259
statement labels 261
variable declaration 265
WHENEVER statement 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
precompiler option 553
host languagedeclarations in DB2I (DB2 Interactive) 156
dynamic SQL 671
host structureC 206
COBOL 242
description 102, 112
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
X-12 Application Programming and SQL Guide
host variable (continued)using INSERT with VALUES clause 105
using SELECT INTO 103
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
description 102, 108
graphicC 202
COBOL 239
PL/I 279
indicator variable array 110
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
keeping duplicate rows with ALL 18
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
program preparation 439
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
indicator variable 354
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
X-14 Application Programming and SQL Guide
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
programming considerations 1046
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
statement labels 743
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
indicator variable 106
indicator variable array 110
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
USING DESCRIPTOR clause 696
without parameter markers 694
OPEN (connection function of CAF)description 968
language examples 978
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
X-16 Application Programming and SQL Guide
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
scrollable cursor 870
PERIOD precompiler option 555
phone application, description 1103
PL/I application programbinary host variable 275
character host variable 274
character host variable array 279
coding considerations 272
coding SQL statements 269
data type compatibility 288
data types 284
DBCS constants 271
DCLGEN support 160
declaring tables 271
declaring views 271
graphic host variable 274
graphic host variable array 279
host variable 273
host variable array 273
INCLUDE statement 271
including SQLCA 269
including SQLDA 270
indicator variable array 290
indicator variables 290
LOB variable 276
LOB variable array 280
naming convention 271
numeric host variable 274
numeric host variable array 278
result set locator 276
ROWID variable 277
ROWID variable array 280, 282
SQLCODE 269
SQLSTATE 269
statement labels 271
table locator 276
variable declaration 287
WHENEVER statement 271
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
option descriptions 550
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
statements allowed 1209
PRIMARY KEY clauseALTER TABLE statement 307
CREATE TABLE statement 306
PRIMARY_ACCESSTYPE column of PLAN_TABLE 901
problem determination, guidelines 636
program preparation 541
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
X-18 Application Programming and SQL Guide
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
programming considerations 1079
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
coding SQL statements 293
data type conversion 297
DSNREXX 295
error handling 296
indicator variable 301
input data type 298, 299
isolation level 302
naming convention 296
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
end-of-data condition 131
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
page and row locking 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
fetch orientation 141
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
X-20 Application Programming and SQL Guide
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
using SELECT INTO 49
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
table, partition, and table space 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
sample C program 1137
SQL (Structured Query Language) (continued)dynamic (continued)
statements allowed 1209
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
program preparation 715
referencing SQLCODE and SQLSTATE 736
SQL variable 733
statements allowed 1215
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
stored procedures 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
X-22 Application Programming and SQL Guide
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 a table to itself 58
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
DSNTIAC subroutineassembler 184
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
sample C program 1137
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
sample C program 1137
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
statements allowed 1212
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
X-24 Application Programming and SQL Guide
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
keeping duplicate rows with ALL 18
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)
table, partition, and table space 464
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
page and row locking 473
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
function resolution 408
overloading operator 365
sourced 366
SQL 366
function resolution 405
host data typesassembler 372
C 372
COBOL 372
PL/I 372
implementer 360
implementing 367
indicatorsinput 376
result 377
X-26 Application Programming and SQL Guide
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
scrollable cursor 415
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 a table to itself 58
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
option descriptions 1227
Index X-27
WLM_REFRESH stored procedure (continued)sample JCL 1228
syntax diagram 1226
write-down privilege 335
XXDBDECOMPXML
authorization 1281
invocation syntax 1281
parameter descriptions 1281
stored procedure 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
invocation example 1280
invocation syntax 1279
parameter descriptions 1279
stored procedure 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
invocation example 1278
invocation syntax 1277
parameter descriptions 1278
stored procedure 1277
XSR_ADDSCHEMADOC stored procedure 1277
XSR_COMPLETE stored procedure 1279
XSR_REGISTERauthorization 1276
XSR_REGISTER (continued)invocation example 1277
invocation syntax 1276
parameter descriptions 1276
stored procedure 1276
XSR_REGISTER stored procedure 1276
XSR_REMOVEauthorization 1280
invocation example 1280
invocation syntax 1280
parameter descriptions 1280
stored procedure 1280
XSR_REMOVE stored procedure 1280
X-28 Application Programming and SQL Guide
����
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