IBM DB2 10.

5
for Linux, UNIX, and Windows

Developing Embedded SQL

Applications



SC27-4550-00

IBM DB2 10.5

for Linux, UNIX, and Windows

Developing Embedded SQL

Applications



SC27-4550-00

Note
Before using this information and the product it supports, read the general information under Appendix B, Notices, on
page 217.

Edition Notice
This document contains proprietary information of IBM. It is provided under a license agreement and is protected
by copyright law. The information contained in this publication does not include any product warranties, and any
statements provided in this manual should not be interpreted as such.
You can order IBM publications online or through your local IBM representative.
v To order publications online, go to the IBM Publications Center at http://www.ibm.com/shop/publications/
order
v To find your local IBM representative, go to the IBM Directory of Worldwide Contacts at http://www.ibm.com/
planetwide/
To order DB2 publications from DB2 Marketing and Sales in the United States or Canada, call 1-800-IBM-4YOU
(426-4968).
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
Copyright IBM Corporation 1993, 2013.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Chapter 1. Introduction to embedded
SQL . . . . . . . . . . . . . . . . 1
Embedding SQL statements in a host language . . .
Embedded SQL statements in C and C++
applications. . . . . . . . . . . . . .
Embedded SQL statements in FORTRAN
applications. . . . . . . . . . . . . .
Embedded SQL statements in COBOL applications
Embedded SQL statements in REXX applications
Supported development software for embedded SQL
applications. . . . . . . . . . . . . . .
Setting up the embedded SQL development
environment . . . . . . . . . . . . . .

2
2
4
5
6
8
8

Chapter 2. Designing embedded SQL

applications . . . . . . . . . . . . 11
Authorization Considerations for Embedded SQL .
Static and dynamic SQL statement execution in
embedded SQL applications . . . . . . . . .
Embedded SQL dynamic statements . . . . .
Determining when to execute SQL statements
statically or dynamically in embedded SQL
applications . . . . . . . . . . . . .
Performance of embedded SQL applications . . .
32-bit and 64-bit support for embedded SQL
applications . . . . . . . . . . . . . .
Restrictions on embedded SQL applications . . .
Restrictions on character sets using C and C++ to
program embedded SQL applications. . . . .
Restrictions on using COBOL to program
embedded SQL applications . . . . . . . .
Restrictions on using FORTRAN to program
embedded SQL applications . . . . . . . .
Restrictions on using REXX to program
embedded SQL applications . . . . . . . .
Recommendations for developing embedded SQL
applications with XML and XQuery . . . . .
Concurrent transactions and multi-threaded
database access in embedded SQL applications . .
Recommendations for using multiple threads . .
Code page and country or region code
considerations for multi-threaded UNIX
applications . . . . . . . . . . . . .
Troubleshooting multi-threaded embedded SQL
applications . . . . . . . . . . . . .

11
12
12

13
15
16
17
17
18
18
18
19
19
22

22
23

Chapter 3. Programming embedded

SQL applications . . . . . . . . . . 25
Embedded SQL source files . . . . . . . . .
Embedded SQL application template in C . . . .
Include files and definitions required for embedded
SQL applications . . . . . . . . . . . .
Include files for C and C++ embedded SQL
applications . . . . . . . . . . . . .
Copyright IBM Corp. 1993, 2013

25
26
29
29

Include files for COBOL embedded SQL

applications . . . . . . . . . . . . . 31
Include files for FORTRAN embedded SQL
applications . . . . . . . . . . . . . 34
Declaring the SQLCA for Error Handling . . . . 36
Connecting to DB2 databases in embedded SQL
applications . . . . . . . . . . . . . . 37
Data types that map to SQL data types in
embedded SQL applications . . . . . . . . . 38
Supported SQL data types in C and C++
embedded SQL applications . . . . . . . . 39
Supported SQL data types in COBOL embedded
SQL applications . . . . . . . . . . . 46
Supported SQL data types in FORTRAN
embedded SQL applications . . . . . . . . 49
Supported SQL data types in REXX embedded
SQL applications . . . . . . . . . . . 51
Host Variables in embedded SQL applications . . . 53
Declaring host variables in embedded SQL
applications . . . . . . . . . . . . . 55
Declaring Host Variables with the db2dclgn
Declaration Generator . . . . . . . . . . 56
Column data types and host variables in
embedded SQL applications . . . . . . . . 56
Declaring XML host variables in embedded SQL
applications . . . . . . . . . . . . . 57
Identifying XML values in an SQLDA . . . . 59
Identifying null SQL values with null indicator
variables . . . . . . . . . . . . . . 59
Including SQLSTATE and SQLCODE host
variables in embedded SQL applications. . . . 61
Referencing host variables in embedded SQL
applications . . . . . . . . . . . . . 61
Example: Referencing XML host variables in
embedded SQL applications . . . . . . . . 62
Host variables in C and C++ embedded SQL
applications . . . . . . . . . . . . . 63
Host variables in COBOL. . . . . . . . . 93
Host variables in FORTRAN . . . . . . . 104
Host variables in REXX . . . . . . . . . 110
Executing XQuery expressions in embedded SQL
applications . . . . . . . . . . . . . . 117
Executing SQL statements in embedded SQL
applications . . . . . . . . . . . . . . 118
Comments in embedded SQL applications . . . 118
Executing static SQL statements in embedded
SQL applications . . . . . . . . . . . 119
Retrieving host variable information from the
SQLDA structure in embedded SQL applications 120
Providing variable input to dynamically
executed SQL statements by using parameter
markers . . . . . . . . . . . . . . 131
Calling procedures in embedded SQL
applications . . . . . . . . . . . . . 133
Reading and scrolling through result sets in
embedded SQL applications . . . . . . . 135

iii

Error message retrieval in embedded SQL

applications . . . . . . . . . . . . . 140
Disconnecting from embedded SQL applications 143

Chapter 4. Building embedded SQL

applications . . . . . . . . . . . . 145
Precompilation of embedded SQL applications with
the PRECOMPILE command . . . . . . . .
Precompilation of embedded SQL applications
that access more than one database server . . .
Embedded SQL application packages and access
plans . . . . . . . . . . . . . . .
Package schema qualification using CURRENT
PACKAGE PATH special register . . . . . .
Precompiler generated timestamps . . . . .
Errors and warnings from precompilation of
embedded SQL applications . . . . . . .
Compiling and linking source files containing
embedded SQL . . . . . . . . . . . . .
Binding embedded SQL packages to a database
Effect of DYNAMICRULES bind option on
dynamic SQL . . . . . . . . . . . .
Using special registers to control the statement
compilation environment . . . . . . . .
Package recreation using the BIND command
and an existing bind file. . . . . . . . .
Rebinding existing packages with the REBIND
command . . . . . . . . . . . . .
Bind considerations . . . . . . . . . .
Blocking considerations . . . . . . . . .
Advantages of deferred binding . . . . . .
Performance improvements when using REOPT
option of the BIND command . . . . . . .
Binding applications and utilities (DB2 Connect
server). . . . . . . . . . . . . . . .
Package storage and maintenance . . . . . .
Package versioning . . . . . . . . . .
Resolution of unqualified table names . . . .

iv

Developing Embedded SQL Applications

146
148
149
149
152
153
153
154
154
157
157
157
158
159
159

Building embedded SQL applications using the

sample build script . . . . . . . . . . .
Error-checking utilities . . . . . . . . .
Building applications and routines written in C
and C++ . . . . . . . . . . . . . .
Building applications and routines written in
COBOL . . . . . . . . . . . . . .
Building and running embedded SQL
applications written in REXX . . . . . . .
Building embedded SQL applications from the
command line . . . . . . . . . . . . .
Building embedded SQL applications written in
C or C++ (Windows) . . . . . . . . . .

165
167
168
182
196
198
198

Chapter 5. Deploying and running

embedded SQL applications . . . . . 201
Use of the db2dsdriver.cfg configuration file by
embedded SQL applications . . . . . . .
Restrictions on linking to libdb2.so . . . . .

. 201
. 203

Chapter 6. Enabling compatibility

features for migration . . . . . . . . 205
Appendix A. Overview of the DB2
technical information . . . . . . . . 211
DB2 technical library in hardcopy or PDF format
211
Displaying SQL state help from the command line
processor . . . . . . . . . . . . . . . 214
Accessing different versions of the DB2
Information Center . . . . . . . . . . . 214
Terms and conditions. . . . . . . . . . . 214

160

Appendix B. Notices . . . . . . . . 217

160
163
163
164

Index . . . . . . . . . . . . . . . 221

Chapter 1. Introduction to embedded SQL

Embedded SQL applications connect to databases and execute embedded SQL
statements. The embedded SQL statements are contained in a package that must be
bound to the target database server.
You can develop embedded SQL applications for the DB2 database in the
following host programming languages: C, C++, and COBOL.
Building embedded SQL applications involves two prerequisite steps before
application compilation and linking.
v Preparing the source files containing embedded SQL statements using the DB2
precompiler.
The PREP (PRECOMPILE) command is used to invoke the DB2 precompiler, which
reads your source code, parses and converts the embedded SQL statements to
DB2 run-time services API calls, and finally writes the output to a new modified
source file. The precompiler produces access plans for the SQL statements, which
are stored together as a package within the database.
v Binding the statements in the application to the target database.
Binding is done by default during precompilation (the PREP command). If
binding is to be deferred (for example, running the BIND command later), then
the BINDFILE option needs to be specified at PREP time in order for a bind file to
be generated.
Once you have precompiled and bound your embedded SQL application, it is
ready to be compiled and linked using the host language-specific development
tools.
To aid in the development of embedded SQL applications, you can refer to the
embedded SQL template in C. Examples of working embedded SQL sample
applications can also be found in the %DB2PATH%\SQLLIB\samples directory.
Note: %DB2PATH% refers to the DB2 installation directory

Static and dynamic SQL

SQL statements can be executed in one of two ways: statically or dynamically.
Statically executed SQL statements
For statically executed SQL statements, the syntax is fully known at
precompile time. The structure of an SQL statement must be completely
specified for a statement to be considered static. For example, the names
for the columns and tables referenced in a statement must be fully known
at precompile time. The only information that can be specified at run time
are values for any host variables referenced by the statement. However,
host variable information, such as data types, must still be precompiled.
You precompile, bind, and compile statically executed SQL statements
before you run your application. Static SQL is best used on databases
whose statistics do not change a great deal.
Dynamically executed SQL statements
Dynamically executed SQL statements are built and executed by an
application at run-time. An interactive application that prompts the end
Copyright IBM Corp. 1993, 2013

user for key parts of an SQL statement, such as the names of the tables and
columns to be searched, is a good example of a situation suited for
dynamic SQL.
Related information:
Installing and configuring Optim Performance Manager Extended Insight

Embedding SQL statements in a host language

Structured Query Language (SQL) is a standardized language that you can use to
manipulate database objects and the data that they contain. Despite differences
between host languages, embedded SQL applications are made up of three main
elements that are required to setup and issue an SQL statement.
The elements you must create when you write an embedded SQL application
include:
1. A DECLARE SECTION for declaring host variables. The declaration of the
SQLCA structure does not need to be in the DECLARE section.
2. The main body of the application, which consists of the setup and execution of
SQL statements.
3. Placements of logic that either commit or rollback the changes made by the
SQL statements.
For each host language, there are differences between the general guidelines, which
apply to all languages, and rules that are specific to individual languages.

Embedded SQL statements in C and C++ applications

Before you can use the SQL statements, you must set up and enable your
application to support embedded SQL.
Embedded SQL C and C++ applications consist of three main elements to setup
and issue an SQL statement.
v A DECLARE SECTION for declaring host variables. The declaration of the
SQLCA structure does not need to be in the DECLARE section.
v The main body of the application, which consists of the setup and execution of
SQL statements
v Placements of logic that either commit or rollback the changes made by the SQL
statements
Correct C and C++ Element Syntax
Statement initializer
EXEC SQL
Statement string
Any valid SQL statement
Statement terminator
Semicolon (;)
For example, to issue an SQL statement statically within a C application, you need
to include a EXEC SQL statement within your application code:
EXEC SQL SELECT col INTO :hostvar FROM table;

The following example demonstrates how to issue an SQL statement dynamically

using the host variable stmt1:

Developing Embedded SQL Applications

strcpy(stmt1, "CREATE TABLE table1(col1 INTEGER)");

EXEC SQL EXECUTE IMMEDIATE :stmt1;

The following guidelines and rules apply to the execution of embedded SQL
statements in C and C++ applications:
v You can begin the SQL statement string on the same line as the EXEC SQL
statement initializer.
v Do not split the EXEC SQL between lines.
v You must use the SQL statement terminator. If you do not use it, the
precompiler will continue to the next terminator in the application. This can
cause indeterminate errors.
v C and C++ comments can be placed before the statement initializer or after the
statement terminator.
v Multiple SQL statements and C or C++ statements may be placed on the same
line. For example:
EXEC SQL OPEN c1; if (SQLCODE >= 0) EXEC SQL FETCH c1 INTO :hv;

v Carriage returns, line feeds, and TABs can be included within quoted strings.
The SQL precompiler will leave these as is.
v Do not use the #include statement to include files containing SQL statements.
SQL statements are precompiled before the module is compiled. The precompiler
will ignore the #include statement. Instead, use the SQL INCLUDE statement to
import the include files.
v SQL comments are allowed on any line that is part of an embedded SQL
statement, with the exception of dynamically issued statements.
The format for an SQL comment is a double dash (--), followed by a string of
zero or more characters, and terminated by a line end.
Do not place SQL comments after the SQL statement terminator. These SQL
comments cause compilation errors because compilers interpret them as C or
C++ syntax.
You can use SQL comments in a static statement string wherever blanks are
allowed.
The use of C and C++ comment delimiters /* */ are allowed in both static
and dynamic embedded SQL statements.
The use of //-style C++ comments are not permitted within static SQL
statements
v SQL string literals and delimited identifiers can be continued over line breaks in
C and C++ applications. To do this, use a back slash (\) at the end of the line
where the break is desired. For example, to select data from the NAME column
in the staff table where the NAME column equals 'Sanders' you could do
something similar to the following sample code:
EXEC SQL SELECT "NA\
ME" INTO :n FROM staff WHERE name=Sa\
nders;

Any new line characters (such as carriage return and line feed) are not included
in the string that is passed to the database manager as an SQL statement.
v Substitution of white space characters, such as end-of-line and TAB characters,
occurs as follows:
When they occur outside quotation marks (but inside SQL statements),
end-of-lines and TABs are substituted by a single space.
When they occur inside quotation marks, the end-of-line characters disappear,
provided the string is continued properly for a C program. TABs are not
modified.
Chapter 1. Embedded SQL

Note that the actual characters used for end-of-line and TAB vary from platform
to platform. For example, UNIX and Linux based systems use a line feed.

Embedded SQL statements in FORTRAN applications

You can include embedded SQL statements in FORTRAN applications. Before you
can use the SQL statements, you must setup and enable your application to
support embedded SQL.
Embedded SQL statements in FORTRAN applications consist of the following three
elements:
Correct FORTRAN Element Syntax
Statement initializer
EXEC SQL
Statement string
Any valid SQL statement with blanks as delimiters
Statement terminator
End of source line.
The end of the source line serves as the statement terminator. If the line is
continued, the statement terminator will then be the end of the last continued line.
For example:
EXEC SQL SELECT COL INTO :hostvar FROM TABLE

The following rules apply to embedded SQL statements in FORTRAN applications:

v Code SQL statements between columns 7 and 72 only.
v Use full-line FORTRAN comments, or SQL comments, but do not use the
FORTRAN end-of-line comment '!' character in SQL statements. This comment
character may be used elsewhere, including host variable declarations.
v Use blanks as delimiters when coding embedded SQL statements, even though
FORTRAN statements do not require blanks as delimiters.
v Use only one SQL statement for each FORTRAN source line. Normal FORTRAN
continuation rules apply for statements that require more than one source line.
Do not split the EXEC SQL statement initializer between lines.
v SQL comments are allowed on any line that is part of an embedded SQL
statement. These comments are not allowed in dynamically executed statements.
The format for an SQL comment is a double dash (--), followed by a string of
zero or more characters and terminated by a line end.
v FORTRAN comments are allowed almost anywhere within an embedded SQL
statement. The exceptions are:
Comments are not allowed between EXEC and SQL.
Comments are not allowed in dynamically executed statements.
The extension of using ! to code a FORTRAN comment at the end of a line is
not supported within an embedded SQL statement.
v Use exponential notation when specifying a real constant in SQL statements. The
database manager interprets a string of digits with a decimal point in an SQL
statement as a decimal constant, not a real constant.
v Statement numbers are not valid on SQL statements that precede the first
executable FORTRAN statement. If an SQL statement has a statement number
associated with it, the precompiler generates a labeled CONTINUE statement
that directly precedes the SQL statement.

Developing Embedded SQL Applications

v Use host variables exactly as declared when referencing host variables within an
SQL statement.
v Substitution of white space characters, such as end-of-line and TAB characters,
occurs as follows:
When they occur outside quotation marks (but inside SQL statements),
end-of-lines and TABs are substituted by a single space.
When they occur inside quotation marks, the end-of-line characters disappear,
provided the string is continued properly for a FORTRAN program. TABs are
not modified.
Note that the actual characters used for end-of-line and TAB vary from platform
to platform. For example, Windows-based platforms use the Carriage
Return/Line Feed for end-of-line, whereas UNIX and Linux based platforms use
just a Line Feed.

Embedded SQL statements in COBOL applications

You can include embedded SQL statements in COBOL applications. Before you can
use the SQL statements, you must set up and enable your application to support
embedded SQL.
Embedded SQL statements in COBOL applications consist of the following three
elements:
Correct COBOL Element Syntax
Statement initializer
EXEC SQL
Statement string
Any valid SQL statement
Statement terminator
END-EXEC.
For example:
EXEC SQL SELECT col INTO :hostvar FROM table END-EXEC.

The following rules apply to embedded SQL statements in COBOL applications:

v Executable SQL statements must be placed in the PROCEDURE DIVISION section.
The SQL statements can be preceded by a paragraph name, just as a COBOL
statement.
v SQL statements can begin in either Area A (columns 8 through 11) or Area B
(columns 12 through 72).
v Start each SQL statement with the statement initializer EXEC SQL and end it
with the statement terminator END-EXEC. The SQL precompiler includes each
SQL statement as a comment in the modified source file.
v You must use the SQL statement terminator. If you do not use it, the
precompiler will continue to the next terminator in the application. This may
cause indeterminate errors.
v SQL comments are allowed on any line that is part of an embedded SQL
statement. These comments are not allowed in dynamically executed statements.
The format for an SQL comment is a double dash (--), followed by a string of
zero or more characters and terminated by a line end. Do not place SQL
comments after the SQL statement terminator as they will cause compilation
errors because they seem to be part of the COBOL language.
v COBOL comments are allowed in most places. The exceptions are:
Chapter 1. Embedded SQL

v
v

v
v
v

Comments are not allowed between EXEC and SQL.

Comments are not allowed in dynamically executed statements.
SQL statements follow the same line continuation rules as the COBOL language.
However, do not split the EXEC SQL statement initializer between lines.
Do not use the COBOL COPY statement to include files containing SQL
statements. SQL statements are precompiled before the module is compiled. The
precompiler will ignore the COBOL COPY statement. Instead, use the SQL
INCLUDE statement to import the include files.
To continue a string constant to the next line, column 7 of the continuing line
must contain a '-' and column 12 or beyond must contain a string delimiter.
SQL arithmetic operators must be delimited by blanks.
Substitution of white space characters, such as end-of-line and TAB characters,
occurs as follows:
When they occur outside quotation marks (but inside SQL statements),
end-of-lines and TABs are substituted by a single space.
When they occur inside quotation marks, the end-of-line characters disappear,
provided the string is continued properly for a COBOL program. TABs are
not modified.
Note that the actual characters used for end-of-line and TAB vary from platform
to platform. For example, Windows-based platforms use Carriage Return/Line
Feed for end-of-line, whereas UNIX and Linux based systems use just a Line
Feed.

Embedded SQL statements in REXX applications

REXX applications use APIs that enable them to use most of the features provided
by database manager APIs and SQL.
Unlike applications written in a compiled language, REXX applications are not
precompiled. Instead, a dynamic SQL handler processes all SQL statements. By
combining REXX with these callable APIs, you have access to most of the database
manager capabilities. Although REXX does not directly support some APIs using
embedded SQL, they can be accessed using the DB2 command line processor from
within the REXX application.
As REXX is an interpreted language, you will find it is easier to develop and
debug your application prototypes in REXX, as compared to compiled host
languages. Although database applications coded in REXX do not provide the
performance of database applications that use compiled languages, they do
provide the ability to create database applications without precompiling,
compiling, linking, or using additional software.
Use the SQLEXEC routine to process all SQL statements. The character string
arguments for the SQLEXEC routine are made up of the following elements:
v SQL keywords
v Pre-declared identifiers
v Statement host variables
Make each request by passing a valid SQL statement to the SQLEXEC routine. Use
the following syntax:
CALL SQLEXEC statement

Developing Embedded SQL Applications

SQL statements can be continued onto more than one line. Each part of the
statement should be enclosed in single quotation marks, and a comma must
delimit additional statement text as follows:
CALL SQLEXEC SQL text,
additional text,
.
.
.
final text

The following code is an example of embedding an SQL statement in REXX:

statement = "UPDATE STAFF SET JOB = Clerk WHERE JOB = Mgr"
CALL SQLEXEC EXECUTE IMMEDIATE :statement
IF ( SQLCA.SQLCODE < 0) THEN
SAY Update Error: SQLCODE = SQLCA.SQLCODE

In this example, the SQLCODE field of the SQLCA structure is checked to determine
whether the update was successful.
The following rules apply to embedded SQL statements: in REXX applications
v The following SQL statements can be passed directly to the SQLEXEC routine:
CALL
CLOSE
COMMIT
CONNECT
CONNECT TO
CONNECT RESET
DECLARE
DESCRIBE
DISCONNECT
EXECUTE
EXECUTE IMMEDIATE
FETCH
FREE LOCATOR
OPEN
PREPARE
RELEASE
ROLLBACK
SET CONNECTION
Other SQL statements must be processed dynamically using the EXECUTE
IMMEDIATE, or PREPARE and EXECUTE statements in conjunction with the
SQLEXEC routine.
v You cannot use host variables in the CONNECT and SET CONNECTION
statements in REXX.
v Cursor names and statement names are predefined as follows:
c1 to c100
Cursor names, which range from c1 to c50 for cursors declared without
the WITH HOLD option, and c51 to c100 for cursors declared using the
WITH HOLD option.
The cursor name identifier is used for DECLARE, OPEN, FETCH, and
CLOSE statements. It identifies the cursor used in the SQL request.
s1 to s100
Statement names, which range from s1 to s100.

Chapter 1. Embedded SQL

The statement name identifier is used with the DECLARE, DESCRIBE,

PREPARE, and EXECUTE statements.
The pre-declared identifiers must be used for cursor and statement names. Other
names are not allowed.
v When declaring cursors, the cursor name and the statement name should
correspond in the DECLARE statement. For example, if c1 is used as a cursor
name, s1 must be used for the statement name.
v Do not use comments within an SQL statement.
Note: REXX does not support multi-threaded database access.

Supported development software for embedded SQL applications

Before you begin writing embedded SQL applications, you must determine if your
development software is supported. The operating system that you are developing
for determines which compilers, interpreters, and development software you must
use.
DB2 database systems support compilers, interpreters, and related development
software for embedded SQL applications in the following operating systems:
v AIX
v HP-UX
v Linux
v Solaris
v Windows
32-bit and 64-bit embedded SQL applications can be built from embedded SQL
source code.
The following host languages require specific compilers to develop embedded SQL
applications:
v C
v C++
v COBOL
v Fortran
v REXX

Setting up the embedded SQL development environment

Before you can start building embedded SQL applications, install the supported
compiler for the host language you will be using to develop your applications and
set up the embedded SQL environment.

Before you begin

v DB2 data server installed on a supported platform
v DB2 client installed
v Supported embedded SQL application development software installed - see
Supported embedded SQL application development software installed in
Getting Started with Database Application Development

Developing Embedded SQL Applications

About this task

Assign the user the authority to issue the PREP command and BIND command.
To verify that the embedded SQL application development environment is set up
properly, try building and running the embedded SQL application template found
in the topic: Embedded SQL application template in C.

Chapter 1. Embedded SQL

10

Developing Embedded SQL Applications

Chapter 2. Designing embedded SQL applications

When designing embedded SQL applications you must use static or dynamic
executed SQL statements.
There are two types of static SQL statements: statements that contain no host
variables (used mainly for initialization and simple SQL examples), and statements
that make use of host variables. Dynamic SQL statements also come in two flavors:
they can either contain no parameter markers (typical of interfaces such as CLP) or
contain parameter markers, which allows for greater flexibility within applications.
The choice of whether to use statically or dynamically executed statements depend
on a number of factors, including: portability, performance and restrictions of
embedded SQL applications.

Authorization Considerations for Embedded SQL

An authorization allows a user or group to perform a general task such as
connecting to a database, creating tables, or administering a system.
A privilege gives a user or group the right to access one specific database object in a
specified way. DB2 uses a set of privileges to provide protection for the
information that you store in it.
Most SQL statements require some type of privilege on the database objects which
the statement utilizes. Most API calls usually do not require any privilege on the
database objects which the call utilizes, however, many APIs require that you
possess the necessary authority to start them. You can use the DB2 APIs to perform
the DB2 administrative functions from within your application program. For
example, to re-create a package stored in the database without the need for a bind
file, you can use the sqlarbnd (or REBIND) API.
Groups provide a convenient means of performing authorization for a collection of
users without having to grant or revoke privileges for each user individually.
Group membership is considered for the execution of dynamic SQL statements, but
not for static SQL statements. PUBLIC privileges are, however, considered for the
execution of static SQL statements. For example, suppose you have an embedded
SQL stored procedure with statically bound SQL queries against a table called
STAFF. If you try to build this procedure with the CREATE PROCEDURE statement, and
your account belongs to a group that has the select privilege for the STAFF table,
the CREATE statement will fail with a SQL0551N error. For the CREATE statement to
work, your account directly needs the select privilege on the STAFF table.
When you design your application, consider the privileges your users will need to
run the application. The privileges required by your users depend on:
v Whether your application uses dynamic SQL, including JDBC and CLI, or static
SQL. For information about the privileges required to issue a statement, see the
description of that statement.
v Which APIs the application uses. For information about the privileges and
authorities required for an API call, see the description of that API.
Groups provide a convenient means of performing authorization for a collection of
users without having to grant or revoke privileges for each user individually. In
Copyright IBM Corp. 1993, 2013

11

general, group membership is considered for dynamic SQL statements, but is not
considered for static SQL statements. The exception to this general case occurs
when privileges are granted to PUBLIC: these are considered when static SQL
statements are processed.
Consider two users, PAYROLL and BUDGET, who need to perform queries against
the STAFF table. PAYROLL is responsible for paying the employees of the
company, so it needs to issue a variety of SELECT statements when issuing
paychecks. PAYROLL needs to be able to access each employee's salary. BUDGET
is responsible for determining how much money is needed to pay the salaries.
BUDGET should not, however, be able to see any particular employee's salary.
Because PAYROLL issues many different SELECT statements, the application you
design for PAYROLL could probably make good use of dynamic SQL. The
dynamic SQL would require that PAYROLL have SELECT privilege on the STAFF
table. This requirement is not a problem because PAYROLL requires full access to
the table.
However, BUDGET, should not have access to each employee's salary. This means
that you should not grant SELECT privilege on the STAFF table to BUDGET.
Because BUDGET does need access to the total of all the salaries in the STAFF
table, you could build a static SQL application to execute a SELECT
SUM(SALARY) FROM STAFF, bind the application and grant the EXECUTE
privilege on your application's package to BUDGET. This enables BUDGET to
obtain the required information, without exposing the information that BUDGET
should not see.

Static and dynamic SQL statement execution in embedded SQL

applications
Both static and dynamic SQL statement execution is supported in embedded SQL
applications. The decision to execute SQL statements statically or dynamically
requires an understanding of packages, how SQL statements are issued at run
time, host variables, parameter markers, and how these things are related to
application performance.

Static SQL in embedded SQL programs

An example of a statically issued statement in C is:
/* select values from table into host variables using STATIC SQL and print them*/
EXEC SQL SELECT id, name, dept, salary INTO :id, :name, :dept, :salary
FROM staff WHERE id = 310;

Dynamic SQL in embedded SQL programs

An example of a dynamically issued statement in C is:
/* Update column in table using DYNAMIC SQL*/
strcpy(hostVarStmtDyn, "UPDATE staff SET salary = salary + 1000
EXEC SQL PREPARE StmtDyn FROM :hostVarStmtDyn;
EXEC SQL EXECUTE StmtDyn USING :dept;

WHERE dept = ?");

Embedded SQL dynamic statements

Dynamic SQL statements accept a character-string host variable and a statement
name as arguments. The host variable contains the SQL statement text that is
processed dynamically.

12

Developing Embedded SQL Applications

The statement text is not processed when an application is precompiled. In fact, the
statement text does not have to exist at the time the application is precompiled.
Instead, the SQL statement is treated as a host variable for precompilation
purposes and the variable is referenced during application execution.
Dynamic SQL support statements are required to transform the host variable
containing SQL text into an executable form. Also, dynamic SQL support
statements operate on the host variable by referencing the statement name. These
support statements are:
EXECUTE IMMEDIATE
Prepares and executes a statement that does not use any host variables.
Use this statement as an alternative to the PREPARE and EXECUTE
statements.
For example consider the following statement in C:
strcpy (qstring,"INSERT INTO WORK_TABLE SELECT *
FROM EMP_ACT WHERE ACTNO >= 100");
EXEC SQL EXECUTE IMMEDIATE :qstring;

PREPARE
Turns the character string form of the SQL statement into an executable
form of the statement, assigns a statement name, and optionally places
information about the statement in an SQLDA structure.
EXECUTE
Executes a previously prepared SQL statement. The statement can be
executed repeatedly within a connection.
DESCRIBE
Places information about a prepared statement into an SQLDA.
For example consider the following statement in C;
strcpy(hostVarStmt, "DELETE FROM org WHERE deptnumb = 15");
EXEC SQL PREPARE Stmt FROM :hostVarStmt;
EXEC SQL DESCRIBE Stmt INTO :sqlda;
EXEC SQL EXECUTE Stmt;

Note: The content of dynamic SQL statements follows the same syntax as static
SQL statements, with the following exceptions:
v The statement cannot begin with EXEC SQL.
v The statement cannot end with the statement terminator. An exception to this is
the CREATE TRIGGER statement which can contain a semicolon (;).

Determining when to execute SQL statements statically or

dynamically in embedded SQL applications
There are several factors that you must consider before determining whether to
issue a static or dynamic SQL statement in an embedded SQL application.
The following table lists the considerations associated with use of static and
dynamic SQL statements.
Note: These are general suggestions only. Your application requirement, its
intended usage, and working environment dictate the actual choice. When in
doubt, prototyping your statements as static SQL, then as dynamic SQL, and
comparing the differences is the best approach.

Chapter 2. Designing

13

Table 1. Comparing Static and Dynamic SQL

Consideration

Likely Best
Choice

Uniformity of data being queried or operated upon by the SQL

statement
v Uniform data distribution
v Slight non-uniformity
v Highly non-uniform distribution

v Static
v Either
v Dynamic

Quantity of range predicates within the query

v Few
v Some
v Many

v Static
v Either
v Dynamic

Likelihood of repeated SQL statement execution

v Runs many times (10 or more times)
v Runs a few times (less than 10 times)
v Runs once

v Either
v Either
v Static

Nature of Query
v Random
v Permanent

v Dynamic
v Either

Types of SQL statements (DML/DDL/DCL)

v Transaction Processing (DML Only)
v Mixed (DML and DDL - DDL affects packages)
v Mixed (DML and DDL - DDL does not affect packages)

v Either
v Dynamic
v Either

Frequency with which the RUNSTATS command is issued

v Infrequently
v Regularly
v Frequently

v Static
v Either
v Dynamic

SQL statements are always compiled before they are run.

The difference is that dynamic SQL statements are compiled at runtime, so the
application might be slower due to the increased resource use associated with
compiling each of the dynamic statements at application runtime versus during a
single initial compilation stage as is the case with static SQL.
In a mixed environment, the choice between static and dynamic SQL must also
factor in the frequency in which packages are invalidated. If the DDL does
invalidate packages, dynamic SQL is more efficient as only those queries issued are
recompiled when they are next used. Others are not recompiled. For static SQL, the
entire package is rebound once it has been invalidated.
There are times when it does not matter whether you use static SQL or dynamic
SQL. For example it might be the case within an application that contains mostly
references to SQL statements to be issued dynamically that there might be one
statement that might more suitably be issued as static SQL. In such a case, to be
consistent in your coding, it might make sense to issue that one statement
dynamically too. Note that the considerations in the previous table are listed
roughly in order of importance.
Do not assume that a static version of an SQL statement is always faster than the
equivalent dynamic statement. In some cases, static SQL is faster because of the
resource use required to prepare the dynamic statement. In other cases, the same
statement prepared dynamically issues faster, because the optimizer can make use
of current database statistics, rather than the database statistics available at an

14

Developing Embedded SQL Applications

earlier bind time. Note that if your transaction takes less than a couple of seconds
to complete, static SQL will generally be faster. To choose which method to use,
you should prototype both forms of binding.
Note: Static and dynamic SQL each come in two types, statements which make use
of host variables and ones which don't. These types are:
1. Static SQL statements containing no host variables
This is an unlikely situation which you may see only for:
v Initialization code
v Simple SQL statements
Simple SQL statements without host variables perform well from a performance
perspective in that there is no runtime performance increase, and the DB2
optimizer capabilities can be fully realized.
2. Static SQL containing host variables
Static SQL statements which make use of host variables are considered as the
traditional style of DB2 applications. The static SQL statement avoids the
runtime resource usage associated with the PREPARE and catalog locks
acquired during statement compilation. Unfortunately, the full power of the
optimizer cannot be used because the optimizer does not know the entire SQL
statement. A particular problem exists with highly non-uniform data
distributions.
3. Dynamic SQL containing no parameter markers
This is typical of interfaces such as the CLP, which is often used for executing
on-demand queries. From the CLP, SQL statements can only be issued
dynamically.
4. Dynamic SQL containing parameter markers
The key benefit of dynamic SQL statements is that the presence of parameter
markers allows the cost of the statement preparation to be amortized over the
repeated executions of the statement, typically a select, or insert. This
amortization is true for all repetitive dynamic SQL applications. Unfortunately,
just like static SQL with host variables, parts of the DB2 optimizer will not
work because complete information is unavailable.

Performance of embedded SQL applications

Performance is an important factor to consider when developing database
applications. Embedded SQL applications can perform well because they support
static SQL statement execution and a mix of static and dynamic SQL statement
execution.
Due to how static SQL statements are compiled, there are steps that a developer or
database administrator must take to ensure that embedded SQL applications
continue to perform well over time.
The following factors can impact embedded SQL application performance:
v Changes in database schemas over time
v Changes in the cardinalities of tables (the number of rows in tables) over time
v Changes in the host variable values bound to SQL statements
Embedded SQL application performance is impacted by these factors because the
package is created once when a database might have a certain set of characteristics.
These characteristics are factored into the creation of the package run time access
Chapter 2. Designing

15

plans which define how the database manager will most efficiently issue SQL
statements. Over time a database schema and data might change rendering the run
time access plans sub-optimal. This can lead to degradation in application
performance.
For this reason it is important to periodically refresh the information that is used to
ensure that the package runtime access plans are well-maintained.
The RUNSTATS command is used to collect current statistics on tables and indexes,
especially if significant update activity has occurred or new indexes have been
created since the last time the RUNSTATS command was issued. This provides the
optimizer with the most accurate information with which to determine the best
access plan.
Performance of Embedded SQL applications can be improved in several ways:
v Run the RUNSTATS command to update database statistics.
v Rebind application packages to the database to regenerate the run time access
plans (based on the updated statistics) that the database will use to physically
retrieve the data on disk.
v Using the REOPT bind option in your static and dynamic programs.

32-bit and 64-bit support for embedded SQL applications

You can build embedded SQL applications on both 32-bit and 64-bit operating
systems. However, there are separate building and running considerations. Build
scripts contain a check to determine the bit width. If the bit width detected is
64-bit, an extra set of switches is set to accommodate the necessary changes.
DB2 database systems are supported on 32-bit and 64-bit versions of operating
systems listed later in this section. There are differences for building embedded
SQL applications in 32-bit and 64-bit environments in most cases on these
operating systems.
v AIX
v HP-UX
v Linux
v Solaris
v Windows
The only 32-bit instances that will be supported in DB2 Version 9 are:
v Linux on x86
v Windows on x86
v Windows on x64 (when using the DB2 for Windows on x86 install image)
The only 64-bit instances that will be supported in DB2 Version 9 are:
v AIX
v Sun
v HP IPF
v
v
v
v

16

Linux on x64
Linux on POWER
Linux on System z
Windows on x64 (when using the Windows for x64 install image)

Developing Embedded SQL Applications

v Windows on IPF
v Linux on IPF
DB2 database systems support running 32-bit applications and routines on all
supported 64-bit operating system environments except Linux IA64 and Linux
System z.
For each of the host languages, the host variables used can be better in either 32-bit
or 64-bit platform or both. Check the various data types for each of the
programming languages.

Restrictions on embedded SQL applications

Each supported host language has its own set of limitations and specifications.
C/C++ makes use of a sequence of three characters called trigraphs to overcome
the limitations of displaying certain special characters. COBOL has a set of rules to
aid in the use of object oriented COBOL applications. FORTRAN has areas of
interest which can affect the precompiling processes whereas REXX is confined in
certain areas such as language support.

Restrictions on character sets using C and C++ to program

embedded SQL applications
Some characters from the C or C++ character set are not available on all
keyboards. You can enter these characters into a C or C++ source program by
using a sequence of three characters called a trigraph. Trigraphs are not recognized
in SQL statements.
The precompiler recognizes the following trigraphs within host variable
declarations:
Trigraph
Definition
??(

Left bracket '['

??)

Right bracket ']'

??<

Left brace '{'

??>

Right brace '}'

The following trigraphs listed might occur elsewhere in a C or C++ source

program:
Trigraph
Definition
??=

Hash mark '#'

??/

Back slash '\'

??'

Caret '^'

??!

Vertical Bar '|'

??-

Tilde '~'

Chapter 2. Designing

17

Restrictions on using COBOL to program embedded SQL

applications
The restrictions for API calls in COBOL applications.
Restrictions for API calls in COBOL applications include:
v All integer variables used as value parameters in API calls must be declared
with a USAGE COMP-5 clause.
In an object-oriented COBOL program:
v SQL statements can only be used in the first program or class in a compile unit.
This restriction exists because the precompiler inserts temporary working data
into the first Working-Storage Section it sees.
v Every class containing SQL statements must have a class-level Working-Storage
Section, even if it is empty. This section is used to store data definitions
generated by the precompiler.

Restrictions on using FORTRAN to program embedded SQL

applications
Embedded SQL support for FORTRAN are stabilized in DB2 Version 5, and no
enhancements are planned for the future.
For example, the FORTRAN precompiler cannot handle SQL object identifiers, such
as table names, that are longer than 18 bytes. To use features introduced to DB2
database systems afterDB2 Version 5, such as table names from 19 to 128 bytes
long, you must write your applications in a language other than FORTRAN.
FORTRAN database application development is not supported with DB2 instances
in Windows or Linux environments.
FORTRAN does not support multi-threaded database access.
Some FORTRAN compilers treat lines with a 'D' or 'd' in column 1 as conditional
lines. These lines can either be compiled for debugging or treated as comments.
The precompiler will always treat lines with a 'D' or 'd' in column 1 as comments.
Some API parameters require addresses rather than values in the call variables.
The database manager provides the GET ADDRESS, DEREFERENCE ADDRESS,
and COPY MEMORY APIs, which simplify your ability to provide these
parameters.
The following items affect the precompiling process:
v The precompiler allows only digits, blanks, and tab characters within columns
1-5 on continuation lines.
v Hollerith constants are not supported in .sqf source files.

Restrictions on using REXX to program embedded SQL

applications
Restrictions on embedded SQL applications created using REXX limit the type of
SQL statement that you can use, and some languages are not supported.
Following are the restrictions for embedded SQL in REXX applications:

18

Developing Embedded SQL Applications

v Embedded SQL support for REXX stabilized in DB2 Universal Database

Version 5, and no enhancements are planned for the future. For example, REXX
cannot handle SQL object identifiers, such as table names, that are longer than
18 bytes. To use features introduced to DB2 database systems after Version 5,
such as table names from 19 to 128 bytes long, you must write your applications
in a language other than REXX.
v Compound SQL is not supported in REXX/SQL.
v REXX does not support static SQL.
v REXX applications are not supported under Japanese or Traditional Chinese
EUC environments.

Recommendations for developing embedded SQL applications

with XML and XQuery
If you are developing embedded SQL applications that use XML and XQuery data,
you must consider if all the required data is available, and what type of data it is.
The following recommendations and restrictions apply to using XML and XQuery
within embedded SQL applications.
v Applications must access all XML data in the serialized string format.
You must represent all data, including numeric and date time data, in its
serialized string format.
v Externalized XML data is limited to 2 GB.
v All cursors containing XML data are non-blocking (each fetch operation
produces a database server request).
v Whenever character host variables contain serialized XML data, the application
code page is assumed to be used as the encoding of the data and must match
any internal encoding that exists in the data.
v You must specify a LOB data type as the base type for an XML host variable.
v The following recommendations and restrictions apply to static SQL:
Character and binary host variables cannot be used to retrieve XML values
from a SELECT INTO operation.
Where an XML data type is expected for input, the use of CHAR, VARCHAR,
CLOB, and BLOB host variables will be subject to an XMLPARSE operation with
default whitespace handling characteristics (STRIP WHITESPACE). Any other
non-XML host variable type will be rejected.
There is no support for static XQuery expressions; attempts to precompile an
XQuery expression will fail with an error. You can only issue XQuery
expressions through the XMLQUERY function.
v An XQuery expression can be dynamically issued by pre-pending the expression
with the string "XQUERY".

Concurrent transactions and multi-threaded database access in

embedded SQL applications
One feature of some operating systems is the ability to run several threads of
execution within a single process. The multiple threads allow an application to
handle asynchronous events, and makes it easier to create event-driven
applications, without resorting to polling schemes.
The information that follows describes how the DB2 database manager works with
multiple threads, and lists some design guidelines that you should keep in mind.
Chapter 2. Designing

19

If you are not familiar with terms relating to the development of multi-threaded
applications (such as critical section and semaphore), consult the programming
documentation for your operating system.
A DB2 embedded SQL application can execute SQL statements from multiple
threads using contexts. A context is the environment from which an application
runs all SQL statements and API calls. All connections, units of work, and other
database resources are associated with a specific context. Each context is associated
with one or more threads within an application. Developing multi-threaded
embedded SQL applications with thread-safe code is only supported in C and C++.
It is possible to write your own precompiler, that along with features supplied by
the language allows concurrent multithread database access.
For each executable SQL statement in a context, the first run-time services call
always tries to obtain a latch. If it is successful, it continues processing. If not
(because an SQL statement in another thread of the same context already has the
latch), the call is blocked on a signaling semaphore until that semaphore is posted,
at which point the call gets the latch and continues processing. The latch is held
until the SQL statement has completed processing, at which time it is released by
the last run-time services call that was generated for that particular SQL statement.
The net result is that each SQL statement within a context is executed as an atomic
unit, even though other threads may also be trying to execute SQL statements at
the same time. This action ensures that internal data structures are not altered by
different threads at the same time. APIs also use the latch used by run-time
services; therefore, APIs have the same restrictions as run-time services routines
within each context.
Contexts may be exchanged between threads in a process, but not exchanged
between processes. One use of multiple contexts is to provide support for
concurrent transactions.
In the default implementation of threaded applications against a DB2 database,
serialization of access to the database is enforced by the database APIs. If one
thread performs a database call, calls made by other threads will be blocked until
the first call completes, even if the subsequent calls access database objects that are
unrelated to the first call. In addition, all threads within a process share a commit
scope. True concurrent access to a database can only be achieved through separate
processes, or by using the APIs that are described in this topic.
DB2 database systems provide APIs that can be used to allocate and manipulate
separate environments (contexts) for the use of database APIs and embedded SQL.
Each context is a separate entity, and any connection or attachment using one
context is independent of all other contexts (and thus all other connections or
attachments within a process). In order for work to be done on a context, it must
first be associated with a thread. A thread must always have a context when
making database API calls or when using embedded SQL.
All DB2 database system applications are multithreaded by default, and are
capable of using multiple contexts. You can use the following DB2 APIs to use
multiple contexts. Specifically, your application can create a context for a thread,
attach to or detach from a separate context for each thread, and pass contexts
between threads. If your application does not call any of these APIs, DB2 will
automatically manage the multiple contexts for your application:
v sqleAttachToCtx - Attach to context

20

Developing Embedded SQL Applications

v
v
v
v
v

sqleBeginCtx - Create and attach to an application context

sqleDetachFromCtx - Detach from context
sqleEndCtx - Detach and destory application context
sqleGetCurrentCtx - Get current context
sqleInterruptCtx - Interrupt context

These APIs have no effect (that is, they are no-ops) on platforms that do not
support application threading.
Contexts need not be associated with a given thread for the duration of a
connection or attachment. One thread can attach to a context, connect to a
database, detach from the context, and then a second thread can attach to the
context and continue doing work using the already existing database connection.
Contexts can be passed around among threads in a process, but not among
processes.
Even if the new APIs are used, the following APIs continue to be serialized:
v
v
v
v

sqlabndx - Bind
sqlaprep - Precompile Program
sqluexpr - Export
db2Import and sqluimpr - Import

Note:
1. The CLI automatically uses multiple contexts to achieve thread-safe, concurrent
database access on platforms that support multi-threading. While not
recommended, users can explicitly disable this feature if required.
2. By default, AIX does not permit 32-bit applications to attach to more than 11
shared memory segments per process, of which a maximum of 10 can be used
for DB2 database connections.
When this limit is reached, DB2 database systems return SQLCODE -1224 on an
SQL CONNECT. DB2 Connect also has the 10-connection limitation if local
users are running two-phase commit with a TP Monitor (TCP/IP).
The AIX environment variable EXTSHM can be used to increase the maximum
number of shared memory segments to which a process can attach.
To use EXTSHM with DB2 database systems, follow the listed steps:
In client sessions:
export EXTSHM=ON

When starting the DB2 server:

export EXTSHM=ON
db2set DB2ENVLIST=EXTSHM
db2start

On partitioned database environment, also add the following lines to your

userprofile or usercshrc files:
EXTSHM=ON
export EXTSHM

An alternative is to move the local database or DB2 Connect into another

machine and to access it remotely, or to access the local database or the DB2
Connect database with TCP/IP loop-back by cataloging it as a remote node that
has the TCP/IP address of the local machine.

Chapter 2. Designing

21

Recommendations for using multiple threads

Multithreaded applications might be difficult to maintain and use if you do not
carefully plan the application in advance. When you are writing a multithreaded
application, you must consider how you handle data structures.
Follow these guidelines when accessing a database from multiple thread
applications:
Serialize alteration of data structures.
Applications must ensure that user-defined data structures used by SQL
statements and database manager routines are not altered by one thread
while an SQL statement or database manager routine is being processed in
another thread. For example, do not allow a thread to reallocate an SQLDA
while it is being used by an SQL statement in another thread.
Consider using separate data structures.
It may be easier to give each thread its own user-defined data structures to
avoid having to serialize their usage. This guideline is especially true for
the SQLCA, which is used not only by every executable SQL statement,
but also by all of the database manager routines. There are three
alternatives for avoiding this problem with the SQLCA:
v Use EXEC SQL INCLUDE SQLCA, but add struct sqlca sqlca at the
beginning of any routine that is used by any thread other than the first
thread.
v Place EXEC SQL INCLUDE SQLCA inside each routine that contains SQL,
instead of in the global scope.
v Replace EXEC SQL INCLUDE SQLCA with #include "sqlca.h", then add
"struct sqlca sqlca" at the beginning of any routine that uses SQL.

Code page and country or region code considerations for

multi-threaded UNIX applications
Code page and conntry or region codes are specific to C and C++ embedded SQL
applications. On AIX, Solaris, and HP-UX, the functions that are used for runtime
querying of the code page and country or region code that you use for a database
connection are now thread safe.
However, these functions can create some lock contention (and resulting
performance degradation) in a multi-threaded application that uses a large number
of concurrent database connections.
You can use the DB2_FORCE_NLS_CACHE environment variable to eliminate the
chance of lock contention in multi-threaded applications. When
DB2_FORCE_NLS_CACHE is set to TRUE, the code page and country or region code
information is saved the first time a thread accesses it. From that point on, the
cached information will be used for any other thread that requests this
information. By saving this information, lock contention is eliminated, and in
certain situations a performance benefit will be realized.
You should not set DB2_FORCE_NLS_CACHE to TRUE if the application changes
locale settings between connections. If this situation occurs, the original locale
information will be returned even after the locale settings have been changed. In
general, multi-threaded applications will not change locale settings, which, ensures
that the application remains thread safe.

22

Developing Embedded SQL Applications

Troubleshooting multi-threaded embedded SQL applications

An application that uses multiple threads is more complex than a single-threaded
application.
This extra complexity can potentially lead to some unexpected problems.
When writing a multi-threaded application, following context issues must be
considered:
Database dependencies between two or more contexts.
Each context in an application has its own set of database resources,
including locks on database objects. This characteristic makes it possible
for two contexts, if they are accessing the same database object, to
deadlock. When the database manager detect a deadlock, SQLCODE -911 is
returned to the application and its unit of work is rolled back.
Application dependencies between two or more contexts.
Be careful with any programming techniques that establish inter-context
dependencies. Latches, semaphores, and critical sections are examples of
programming techniques that can establish such dependencies. If an
application has two contexts that have both application and database
dependencies between the contexts, it is possible for the application to
become deadlocked. If some of the dependencies are outside of the
database manager, the deadlock is not detected, thus the application gets
suspended or hung.
Deadlock prevention for multiple contexts.
Because the database manager cannot detect deadlocks between threads,
code your application in a way that avoids deadlocks.
As an example of a deadlock that the database manager cannot detect,
consider an application that has two contexts, both of which access a
common data structure. To avoid problems where both contexts change the
data structure simultaneously, the data structure is protected by a
semaphore. The sample contexts are shown in following pseudocode:
context 1
SELECT * FROM TAB1 FOR UPDATE....
UPDATE TAB1 SET....
get semaphore
access data structure
release semaphore
COMMIT
context 2
get semaphore
access data structure
SELECT * FROM TAB1...
release semaphore
COMMIT

Suppose the first context successfully executes the SELECT and the
UPDATE statements, while the second context gets the semaphore and
accesses the data structure. The first context now tries to get the
semaphore, but it cannot because the second context is holding the
semaphore. The second context now attempts to read a row from table
TAB1, but it stops on a database lock held by the first context. The
application is now in a state where context 1 cannot finish before context 2
is done and context 2 is waiting for context 1 to finish. The application is
deadlocked, but because the database manager does not know that about

Chapter 2. Designing

23

the semaphore dependency neither context is rolled back. The unresolved

dependency leaves the application suspended.
You can avoid the deadlock that can occur for the previous example in
several ways.
v Release all locks held before obtaining the semaphore.
Change the code for context 1 to perform a commit before it gets the
semaphore.
v Do not code SQL statements inside a section protected by semaphores.
Change the code for context 2 to release the semaphore before doing the
SELECT.
v Code all SQL statements within semaphores.
Change the code for context 1 to obtain the semaphore before running
the SELECT statement. While this technique will work, it is not highly
recommended because the semaphores will serialize access to the
database manager, which potentially negates the benefits of using
multiple threads.
v Set the locktimeout database configuration parameter to a value other
than -1.
While a value other than -1 will not prevent the deadlock, it will allow
execution to resume. Context 2 is eventually rolled back because it is
unable to obtain the requested lock. When handling the rollback error,
context 2 should release the semaphore. Once the semaphore has been
released, context 1 can continue and context 2 is free to try again its
work.
The techniques for avoiding deadlocks are described in terms of the
example, but you can apply them to all multi-threaded applications. In
general, treat the database manager as you would treat any protected
resource and you should not run into problems with multi-threaded
applications.

24

Developing Embedded SQL Applications

Chapter 3. Programming embedded SQL applications

Programming embedded SQL applications involves the same steps required to
assemble an application in your host programming language.
Once you determine that embedded SQL is the appropriate API to meet your
programming needs, and after you design your embedded SQL application, you
will be ready to program an embedded SQL application.
Prerequisites:
v Choose whether to use static or dynamic SQL statements
v Design of an embedded SQL application
Programming embedded SQL applications consists of the following sub-tasks:
v Including the required header files
v Choosing a supported embedded SQL programming language
v Declaring host variables for representing values to be included in SQL
statements
v Connecting to a data source
v Executing SQL statements
v Handling SQL errors and warnings related to SQL statement execution
v Disconnecting from the data source
Once you have a complete embedded SQL application you'll be ready to compile
and run your application: Building embedded SQL applications.

Embedded SQL source files

When you develop source code that includes embedded SQL, you must follow
specific file naming conventions for each of the supported host languages.

Input and output files for C and C++

By default, the source application can have the following extensions:
.sqc

For C files on all supported operating systems

.sqC

For C++ files on UNIX and Linux operating systems

.sqx

For C++ files on Windows operating systems

By default, the corresponding precompiler output files have the following

extensions:
.c

For C files on all supported operating systems

.C

For C++ files on UNIX and Linux operating systems

.cxx

For C++ files on Windows operating systems

You can use the OUTPUT precompile option to override the name and path of the
output modified source file. If you use the TARGET C or TARGET CPLUSPLUS
precompile option, the input file does not need a particular extension.

Copyright IBM Corp. 1993, 2013

25

Input and output files for COBOL

By default, the source application has an extension of:
.sqb

For COBOL files on all operating systems

However, if you use the TARGET precompile option (TARGET ANSI_COBOL,

TARGET IBMCOB or TARGET MFCOB), the input file can have any extension you
prefer.
By default, the corresponding precompiler output files have the following
extensions:
.cbl

For COBOL files on all operating systems

However, you can use the OUTPUT precompile option to specify a new name and
path for the output modified source file.

Input and output files for FORTRAN

By default, the source application has an extension of:
.sqf

For FORTRAN files on all operating systems

However, if you use the TARGET precompile option with the FORTRAN option
the input file can have any extension you prefer.
By default, the corresponding precompiler output files have the following
extensions:
.f

For FORTRAN files on UNIX and Linux operating systems

.for

For FORTRAN files on Windows operating systems

However, you can use the OUTPUT precompile option to specify a new name and
path for the output modified source file.

Embedded SQL application template in C

You are provided with a sample embedded SQL application to test your embedded
SQL development environment and to help you learn about the basic structure of
embedded SQL applications.
Embedded SQL applications require the following structure:
v Including the required header files
v Host variable declarations for values to be included in SQL statements
v A database connection
v The execution of SQL statements
v The handling of SQL errors and warnings related to SQL statement execution
v Dropping the database connection
The following source code demonstrates the basic structure required for embedded
SQL applications written in C.
Sample program: template.sqc

26

Developing Embedded SQL Applications

#include
#include
#include
#include
#include

<stdio.h>
<stdlib.h>
<string.h>
<sqlenv.h>
<sqlutil.h>

EXEC SQL BEGIN DECLARE SECTION;

short id;
char name[10];
short dept;
double salary;
char hostVarStmtDyn[50];
EXEC SQL END DECLARE SECTION;

int main()
{
int rc = 0;
EXEC SQL INCLUDE SQLCA;

3
4

/* connect to the database */

printf("\n Connecting to database...");
EXEC SQL CONNECT TO "sample";
if (SQLCODE <0)
{
printf("\nConnect Error: SQLCODE =
goto connect_reset;
}
else
{
printf("\n Connected to database.\n");
}

5
6

/* execute an SQL statement (a query) using static SQL; copy the single row
of result values into host variables*/
EXEC SQL SELECT id, name, dept, salary
7
INTO :id, :name, :dept, :salary
FROM staff WHERE id = 310;
if (SQLCODE <0)
6
{
printf("Select Error: SQLCODE =
}
else
{
/* print the host variable values to standard output */
printf("\n Executing a static SQL query statement, searching for
\n the id value equal to 310\n");
printf("\n ID
Name
DEPT
Salary\n");
printf("
}
strcpy(hostVarStmtDyn, "UPDATE staff
SET salary = salary + 1000
WHERE dept = ?");
/* execute an SQL statement (an operation) using a host variable
and DYNAMIC SQL*/
EXEC SQL PREPARE StmtDyn FROM :hostVarStmtDyn;
if (SQLCODE <0)
{
printf("Prepare Error: SQLCODE =
}
else
{
EXEC SQL EXECUTE StmtDyn USING :dept;
}
if (SQLCODE <0)
{
printf("Execute Error: SQLCODE =

8
6

Chapter 3. Programming

27

}
/* Read the updated row using STATIC SQL and CURSOR */
EXEC SQL DECLARE posCur1 CURSOR FOR
SELECT id, name, dept, salary
FROM staff WHERE id = 310;
if (SQLCODE <0)
{
printf("Declare Error: SQLCODE =
}
EXEC SQL OPEN posCur1;
EXEC SQL FETCH posCur1 INTO :id, :name, :dept, :salary ;
if (SQLCODE <0)
{
printf("Fetch Error: SQLCODE =
}
else
{
printf(" Executing an dynamic SQL statement, updating the
\n salary value for the id equal to 310\n");
printf("\n ID
Name
DEPT
Salary\n");
printf("
}

9
6

EXEC SQL CLOSE posCur1;

/* Commit the transaction */
printf("\n Commit the transaction.\n");
EXEC SQL COMMIT;
if (SQLCODE <0)
{
printf("Error: SQLCODE =
}
/* Disconnect from the database */
connect_reset :
EXEC SQL CONNECT RESET;
if (SQLCODE <0)
{
printf("Connection Error: SQLCODE =
}
return 0;
} /* end main */

10
6

11
6

Notes to Sample program: template.sqc:

Note

Description

1
2

Include files: This directive includes a file into your source application.
Declaration section: Declaration of host variables that will be used to hold
values referenced in the SQL statements of the C application.
Local variable declaration: This block declares the local variables to be used in
the application. These are not host variables.
Including the SQLCA structure: The SQLCA structure is updated after the
execution of each SQL statement. This template application uses certain SQLCA
fields for error handling.
Connection to a database: The initial step in working with the database is to
establish a connection to the database. Here, a connection is made by executing
the CONNECT SQL statement.
Error handling: Checks to see if an error occurred.
Executing a query: The execution of this SQL statement assigns data returned
from a table to host variables. The C code used after the SQL statement
execution prints the values in the host variables to standard output.

3
4

6
7

28

Developing Embedded SQL Applications

Note

Description

Executing an operation: The execution of this SQL statement updates a set of

rows in a table identified by their department number. Preparation (EXEC SQL
PREPARE StmtDyn FROM :hostVarStmtDyn;) is a step in which host variable
values, such as the one referenced in this statement, are bound to the SQL
statement to be executed.
Executing an operation: In this line and the previous line, this application uses
cursors in static SQL to select information in a table and print the data. After
the cursor is declared and opened, the data is fetched, and finally the cursor is
closed.
Commit the transaction: The COMMIT statement finalizes the database changes
that were made within a unit of work.
And finally, the database connection must be dropped.

10
11

Include files and definitions required for embedded SQL applications

Include files are required to provide functions and types that are used within the
library. You must include these files before the program can use library functions.
By default, include files are installed in the $HOME/sqllib/include folder.
Each host language has its own methods for including files, as well as using
different file extensions. Depending on the language specified certain precautions
such as specifying file paths must be taken.

Include files for C and C++ embedded SQL applications

The host-language-specific include files for C and C++ have the file extension .h.
The C and C++ include files are also called header files.
There are two methods for including files: the EXEC SQL INCLUDE statement and the
#include macro. The precompiler will ignore the #include, and only process files
included with the EXEC SQL INCLUDE statement. To locate files included using EXEC
SQL INCLUDE, the DB2 C precompiler searches the current directory first, then the
directories specified by the DB2INCLUDE environment variable. Consider the
following examples:
v EXEC SQL INCLUDE payroll;
If the file specified in the INCLUDE statement is not enclosed in quotation marks,
as shown previously, the C precompiler searches for payroll.sqc, then
payroll.h, in each directory in which it looks. On UNIX and Linux operating
systems, the C++ precompiler searches for payroll.sqC, then payroll.sqx, then
payroll.hpp, then payroll.h in each directory it looks. On Windows-32 bit
operating systems, the C++ precompiler searches for payroll.sqx, then
payroll.hpp, then payroll.h in each directory it looks.
v EXEC SQL INCLUDE pay/payroll.h;
If the file name is enclosed in quotation marks, as shown previously, no
extension is added to the name.
If the file name in quotation marks does not contain an absolute path, then the
contents of DB2INCLUDE are used to search for the file, prepended to whatever
path is specified in the INCLUDE file name. For example, on UNIX and Linux
operating systems, if DB2INCLUDE is set to '/disk2:myfiles/c', the C or C++
precompiler searches for './pay/payroll.h', then '/disk2/pay/payroll.h', and
finally './myfiles/c/pay/payroll.h'. The path where the file is actually found is
displayed in the precompiler messages. On Windows operating systems,
substitute back slashes (\) for the forward slashes in the previous example.
Chapter 3. Programming

29

Note that if the precompiler option COMPATIBILITY_MODE is set to ORA, you

can use double quotation marks to specify include file names, for example, EXEC
SQL INCLUDE "abc.h";. The DB2 database manager provides this feature to
facilitate the migration of embedded SQL C applications from other database
systems.
Note: The setting of DB2INCLUDE is cached by the command line processor. To
change the setting of DB2INCLUDE after any CLP commands have been issued, enter
the TERMINATE command, then reconnect to the database and precompile.
To help relate compiler errors back to the original source, the precompiler
generates #line macros in the output file. This allows the compiler to report errors
using the file name and line number of the source or included source file, rather
than the line number in the precompiled output source file.
However, if you specify the PREPROCESSOR option, all the #line macros generated by
the precompiler reference the preprocessed file from the external C preprocessor.
Some debuggers and other tools that relate source code to object code do not
always work well with the #line macro. If the tool you want to use behaves
unexpectedly, use the NOLINEMACRO option (used with DB2 PREP) when
precompiling. This option prevents the #line macros from being generated.
The include files that are intended to be used in your applications are described in
the following section.
SQLADEF (sqladef.h)
This file contains function prototypes used by precompiled C and C++
applications.
SQLCA (sqlca.h)
This file defines the SQL Communication Area (SQLCA) structure. The
SQLCA contains variables that are used by the database manager to
provide an application with error information about the execution of SQL
statements and API calls.
SQLCODES (sqlcodes.h)
This file defines constants for the SQLCODE field of the SQLCA structure.
SQLDA (sqlda.h)
This file defines the SQL Descriptor Area (SQLDA) structure. The SQLDA
is used to pass data between an application and the database manager.
SQLEXT (sqlext.h)
This file contains the function prototypes and constants of those ODBC
Level 1 and Level 2 APIs that are not part of the X/Open Call Level
Interface specification and is therefore used with the permission of
Microsoft Corporation.
SQLE819A (sqle819a.h)
If the code page of the database is 819 (ISO Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
500 (EBCDIC International) binary collation. This file is used by the
CREATE DATABASE API.
SQLE819B (sqle819b.h)
If the code page of the database is 819 (ISO Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
037 (EBCDIC US English) binary collation. This file is used by the CREATE
DATABASE API.

30

Developing Embedded SQL Applications

SQLE850A (sqle850a.h)
If the code page of the database is 850 (ASCII Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
500 (EBCDIC International) binary collation. This file is used by the
CREATE DATABASE API.
SQLE850B (sqle850b.h)
If the code page of the database is 850 (ASCII Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
037 (EBCDIC US English) binary collation. This file is used by the CREATE
DATABASE API.
SQLE932A (sqle932a.h)
If the code page of the database is 932 (ASCII Japanese), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 5035 (EBCDIC Japanese) binary collation. This file is used by the
CREATE DATABASE API.
SQLE932B (sqle932b.h)
If the code page of the database is 932 (ASCII Japanese), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 5026 (EBCDIC Japanese) binary collation. This file is used by the
CREATE DATABASE API.
SQLJACB (sqljacb.h)
This file defines constants, structures, and control blocks for the DB2
Connect interface.
SQLSTATE (sqlstate.h)
This file defines constants for the SQLSTATE field of the SQLCA structure.
SQLSYSTM (sqlsystm.h)
This file contains the platform-specific definitions used by the database
manager APIs and data structures.
SQLUDF (sqludf.h)
This file defines constants and interface structures for writing user-defined
functions (UDFs).
SQLUV (sqluv.h)
This file defines structures, constants, and prototypes for the asynchronous
Read Log API, and APIs used by the table load and unload vendors.

Include files for COBOL embedded SQL applications

The host-language-specific include files for COBOL have the file extension .cbl. If
you use the "System/390 host data type support" feature of the IBM COBOL
compiler, the DB2 include files for your applications are in the
$HOME/sqllib/include/cobol_i directory.
If you build the DB2 sample programs with the supplied script files, you must
change the include file path specified in the script files to the cobol_i directory
and not the cobol_a directory.
If you do not use the "System/390 host data type support" feature of the IBM
COBOL compiler, or you use an earlier version of this compiler, the DB2 include
files for your applications are in the following directory:
$HOME/sqllib/include/cobol_a

Chapter 3. Programming

31

To locate INCLUDE files, the DB2 COBOL precompiler searches the current
directory first, then the directories specified by the DB2INCLUDE environment
variable. Consider the following examples:
v EXEC SQL INCLUDE payroll END-EXEC.
If the file specified in the INCLUDE statement is not enclosed in quotation
marks, as shown previously, the precompiler searches for payroll.sqb, then
payroll.cpy, then payroll.cbl, in each directory in which it looks.
v EXEC SQL INCLUDE pay/payroll.cbl END-EXEC.
If the file name is enclosed in quotation marks, as shown previously, no
extension is added to the name.
If the file name in quotation marks does not contain an absolute path, the
contents of DB2INCLUDE are used to search for the file, prepended to whatever
path is specified in the INCLUDE file name. For example, with DB2 database
systems for AIX, if DB2INCLUDE is set to '/disk2:myfiles/cobol', the
precompiler searches for './pay/payroll.cbl', then '/disk2/pay/payroll.cbl',
and finally './myfiles/cobol/pay/payroll.cbl'. The path where the file is
actually found is displayed in the precompiler messages. On Windows
platforms, substitute back slashes (\) for the forward slashes in the previously
shown example.
Note: The setting of DB2INCLUDE is cached by the DB2 command line processor.
To change the setting of DB2INCLUDE after any CLP commands have been issued,
enter the TERMINATE command, then reconnect to the database and precompile.
The include files that are intended to be used in your applications are described
here:
SQLCA (sqlca.cbl)
This file defines the SQL Communication Area (SQLCA) structure. The
SQLCA contains variables that are used by the database manager to
provide an application with error information about the execution of SQL
statements and API calls.
SQLCA_92 (sqlca_92.cbl)
This file contains a FIPS SQL92 Entry Level compliant version of the SQL
Communications Area (SQLCA) structure. This file should be included in
place of the sqlca.cbl file when writing DB2 applications that conform to
the FIPS SQL92 Entry Level standard. The sqlca_92.cbl file is
automatically included by the DB2 precompiler when the LANGLEVEL
precompiler option is set to SQL92E.
SQLCODES (sqlcodes.cbl)
This file defines constants for the SQLCODE field of the SQLCA structure.
SQLDA (sqlda.cbl)
This file defines the SQL Descriptor Area (SQLDA) structure. The SQLDA
is used to pass data between an application and the database manager.
SQLEAU (sqleau.cbl)
This file contains constant and structure definitions required for the DB2
security audit APIs. If you use these APIs, you need to include this file in
your program. This file also contains constant and keyword value
definitions for fields in the audit trail record. These definitions can be used
by external or vendor audit trail extract programs.
SQLETSD (sqletsd.cbl)
This file defines the Table Space Descriptor structure, SQLETSDESC, which
is passed to the Create Database API, sqlgcrea.

32

Developing Embedded SQL Applications

SQLE819A (sqle819a.cbl)
If the code page of the database is 819 (ISO Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
500 (EBCDIC International) binary collation. This file is used by the
CREATE DATABASE API.
SQLE819B (sqle819b.cbl)
If the code page of the database is 819 (ISO Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
037 (EBCDIC US English) binary collation. This file is used by the CREATE
DATABASE API.
SQLE850A (sqle850a.cbl)
If the code page of the database is 850 (ASCII Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
500 (EBCDIC International) binary collation. This file is used by the
CREATE DATABASE API.
SQLE850B (sqle850b.cbl)
If the code page of the database is 850 (ASCII Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
037 (EBCDIC US English) binary collation. This file is used by the CREATE
DATABASE API.
SQLE932A (sqle932a.cbl)
If the code page of the database is 932 (ASCII Japanese), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 5035 (EBCDIC Japanese) binary collation. This file is used by the
CREATE DATABASE API.
SQLE932B (sqle932b.cbl)
If the code page of the database is 932 (ASCII Japanese), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 5026 (EBCDIC Japanese) binary collation. This file is used by the
CREATE DATABASE API.
SQL1252A (sql1252a.cbl)
If the code page of the database is 1252 (Windows Latin-1), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 500 (EBCDIC International) binary collation. This file is used by the
CREATE DATABASE API.
SQL1252B (sql1252b.cbl)
If the code page of the database is 1252 (Windows Latin-1), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 037 (EBCDIC US English) binary collation. This file is used by the
CREATE DATABASE API.
SQLSTATE (sqlstate.cbl)
This file defines constants for the SQLSTATE field of the SQLCA structure.
SQLUDF (sqludf.cbl)
This file defines constants and interface structures for writing user-defined
functions (UDFs).
SQLUTBCQ (sqlutbcq.cbl)
This file defines the Table Space Container Query data structure,
SQLB-TBSCONTQRY-DATA, which is used with the table space container
query APIs, sqlgstsc, sqlgftcq, and sqlgtcq.

Chapter 3. Programming

33

SQLUTBSQ (sqlutbsq.cbl)
This file defines the Table Space Query data structure,
SQLB-TBSQRY-DATA, which is used with the table space query APIs,
sqlgstsq, sqlgftsq, and sqlgtsq.

Include files for FORTRAN embedded SQL applications

The host-language-specific include files for FORTRAN have the file extension .f on
UNIX and Linux operating systems, and .for on Windows operating systems.
There are two methods for including files: the EXEC SQL INCLUDE statement and
the FORTRAN INCLUDE statement.
The precompiler ignores FORTRAN INCLUDE statements, and only process files
included with the EXEC SQL statement. To locate the INCLUDE file, the DB2
FORTRAN precompiler searches the current directory first, and then the directories
specified by the DB2INCLUDE environment variable.
Consider the following examples:
v EXEC SQL INCLUDE payroll
If the file specified in the INCLUDE statement is not enclosed in quotation
marks, as shown previously, the precompiler searches for payroll.sqf, then
payroll.f (payroll.for on Windows operating systems) in each directory in
which it looks.
v EXEC SQL INCLUDE pay/payroll.f
If the file name is enclosed in quotation marks, as shown previously, no
extension is added to the name. (For Windows operating systems, the file would
be specified as pay\payroll.for.)
If the file name in quotation marks does not contain an absolute path, then the
contents of DB2INCLUDE are used to search for the file, prepended to whatever
path is specified in the INCLUDE file name. For example, with DB2 for UNIX
and Linux operating systems, if DB2INCLUDE is set to '/disk2:myfiles/
fortran', the precompiler searches for './pay/payroll.f', then
'/disk2/pay/payroll.f', and finally './myfiles/cobol/pay/payroll.f'. The path
where the file is actually found is displayed in the precompiler messages. On
Windows operating systems, substitute back slashes (\) for the forward slashes,
and substitute for for the f extension in the previously shown example.
Note: The setting of DB2INCLUDE is cached by the DB2 command line processor.
To change the setting of DB2INCLUDE after any CLP commands have been issued,
enter the TERMINATE command, then reconnect to the database and precompile.
32-bit FORTRAN header files required for DB2 database application development,
previously found in $INSTHOME/sqllib/include are now found in
$INSTHOME/sqllib/include32.
In Version 8.1, these files were found in the $INSTDIR/sqllib/include directory
which was a symbolic link to one of the following directories: $DB2DIR/include or
$DB2DIR/include64 depending on whether or not it was a 32-bit instance or a 64-bit
instance.
In Version 9.1, $DB2DIR/include will contain all the include files (32-bit and 64-bit),
and $DB2DIR/include32 will contain 32-bit FORTRAN files only and a README
file to indicate that 32-bit include files are the same as the 64-bit ones with the
exception of FORTRAN.

34

Developing Embedded SQL Applications

The $DB2DIR/include32 directory will only exist on AIX, Solaris, HP-PA, and
HP-IPF.
You can use the following FORTRAN include files in your applications.
SQLCA (sqlca_cn.f, sqlca_cs.f)
This file defines the SQL Communication Area (SQLCA) structure. The
SQLCA contains variables that are used by the database manager to
provide an application with error information about the execution of SQL
statements and API calls.
Two SQLCA files are provided for FORTRAN applications. The default,
sqlca_cs.f, defines the SQLCA structure in an IBM SQL compatible
format. The sqlca_cn.f file, precompiled with the SQLCA NONE option,
defines the SQLCA structure for better performance.
SQLCA_92 (sqlca_92.f)
This file contains a FIPS SQL92 Entry Level compliant version of the SQL
Communications Area (SQLCA) structure. This file should be included in
place of either the sqlca_cn.f or the sqlca_cs.f files when writing DB2
applications that conform to the FIPS SQL92 Entry Level standard. The
sqlca_92.f file is automatically included by the DB2 precompiler when the
LANGLEVEL precompiler option is set to SQL92E.
SQLCODES (sqlcodes.f)
This file defines constants for the SQLCODE field of the SQLCA structure.
SQLDA (sqldact.f)
This file defines the SQL Descriptor Area (SQLDA) structure. The SQLDA
is used to pass data between an application and the database manager.
SQLEAU (sqleau.f)
This file contains constant and structure definitions required for the DB2
security audit APIs. If you use these APIs, you need to include this file in
your program. This file also contains constant and keyword value
definitions for fields in the audit trail record. These definitions can be used
by external or vendor audit trail extract programs.
SQLE819A (sqle819a.f)
If the code page of the database is 819 (ISO Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
500 (EBCDIC International) binary collation. This file is used by the
CREATE DATABASE API.
SQLE819B (sqle819b.f)
If the code page of the database is 819 (ISO Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
037 (EBCDIC US English) binary collation. This file is used by the CREATE
DATABASE API.
SQLE850A (sqle850a.f)
If the code page of the database is 850 (ASCII Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
500 (EBCDIC International) binary collation. This file is used by the
CREATE DATABASE API.
SQLE850B (sqle850b.f)
If the code page of the database is 850 (ASCII Latin-1), this sequence sorts
character strings that are not FOR BIT DATA according to the host CCSID
037 (EBCDIC US English) binary collation. This file is used by the CREATE
DATABASE API.
Chapter 3. Programming

35

SQLE932A (sqle932a.f)
If the code page of the database is 932 (ASCII Japanese), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 5035 (EBCDIC Japanese) binary collation. This file is used by the
CREATE DATABASE API.
SQLE932B (sqle932b.f)
If the code page of the database is 932 (ASCII Japanese), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 5026 (EBCDIC Japanese) binary collation. This file is used by the
CREATE DATABASE API.
SQL1252A (sql1252a.f)
If the code page of the database is 1252 (Windows Latin-1), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 500 (EBCDIC International) binary collation. This file is used by the
CREATE DATABASE API.
SQL1252B (sql1252b.f)
If the code page of the database is 1252 (Windows Latin-1), this sequence
sorts character strings that are not FOR BIT DATA according to the host
CCSID 037 (EBCDIC US English) binary collation. This file is used by the
CREATE DATABASE API.
SQLSTATE (sqlstate.f)
This file defines constants for the SQLSTATE field of the SQLCA structure.
SQLUDF (sqludf.f)
This file defines constants and interface structures for writing user-defined
functions (UDFs).

Declaring the SQLCA for Error Handling

You can declare the SQLCA in your application program so that the database
manager can return information to your application.

About this task

When you preprocess your program, the database manager inserts host language
variable declarations in place of the INCLUDE SQLCA statement. The system
communicates with your program using the variables for warning flags, error
codes, and diagnostic information.
After executing each SQL statement, the system returns a return code in both
SQLCODE and SQLSTATE. SQLCODE is an integer value that summarizes the
execution of the statement, and SQLSTATE is a character field that provides
common error codes across IBM's relational database products. SQLSTATE also
conforms to the ISO/ANS SQL92 and FIPS 127-2 standard.
Note: FIPS 127-2 refers to Federal Information Processing Standards Publication 127-2
for Database Language SQL. ISO/ANS SQL92 refers to American National Standard
Database Language SQL X3.135-1992 and International Standard ISO/IEC 9075:1992,
Database Language SQL.
Note that if SQLCODE is less than 0, it means an error has occurred and the
statement has not been processed. If the SQLCODE is greater than 0, it means a
warning has been issued, but the statement is still processed.

36

Developing Embedded SQL Applications

For a DB2 application written in C or C++, if the application is made up of

multiple source files, only one of the files include the EXEC SQL INCLUDE
SQLCA statement to avoid multiple definitions of the SQLCA. The remaining
source files must use the following lines:
#include "sqlca.h"
extern struct sqlca sqlca;

Procedure
To declare the SQLCA, code the INCLUDE SQLCA statement in your program:
v For C or C++ applications use:
EXEC SQL INCLUDE SQLCA;

v For Java applications, you do not explicitly use the SQLCA. Instead, use the
SQLException instance methods to get the SQLSTATE and SQLCODE values.
v For COBOL applications use:
EXEC SQL INCLUDE SQLCA END-EXEC.

v For FORTRAN applications use:

EXEC SQL INCLUDE SQLCA

What to do next
If your application must be compliant with the ISO/ANS SQL92 or FIPS 127-2
standard, do not use the statements previously shown or the INCLUDE SQLCA
statement.

Connecting to DB2 databases in embedded SQL applications

Before working with a database, you must establish a connection to that database.
Embedded SQL provides multiple ways in which to include code for establishing
database connections. Depending on which host programming language you use,
there might be one or more way to establish a database connection.
Database connections can be established implicitly or explicitly. An implicit
connection is a connection where the user ID is presumed to be the current user
ID. This type of connection is not recommended for database applications. Explicit
database connections, which require that a user ID and password be specified, are
strongly recommended.

Connecting to DB2 databases in C and C++ Embedded SQL

applications
When working with C and C++ applications, a database connection can be
established by executing the following statement.
EXEC SQL CONNECT TO sample;

If you want to use a specific user id (herrick) and password (mypassword), use the
following statement:
EXEC SQL CONNECT TO sample USER herrick USING mypassword;

Note that if the precompiler option COMPATIBILITY_MODE is set to ORA, the

following additional syntax for the CONNECT statement is supported. The DB2
database manager provides this feature to facilitate the migration of embedded
SQL C applications from other database systems.
EXEC SQL CONNECT [ username IDENTIFIED BY password ][ USING

dbname ] ;
Chapter 3. Programming

37

The parameters are described in the following table:

Parameter

Description

username

Either a host variable or a string specifying

the database user name

password

Either a host variable or a string specifying

the password

dbname

Either a host variable or a string specifying

the database name

Connecting to DB2 databases in COBOL Embedded SQL

applications
When working with COBOL applications, a database connection is established by
executing the following statement. This statement creates a connection to the
sample database using the default user name.
EXEC SQL CONNECT TO sample END-EXEC.

If you want to use a specific user id (herrick) and password (mypassword), use the
following statement:
EXEC SQL CONNECT TO sample USER herrick USING mypassword END-EXEC.

Connecting to DB2 databases in FORTRAN Embedded SQL

applications
When working with FORTRAN applications, a database connection is established
by executing the following statement. This statement creates a connection to the
sample database using the default user name.
EXEC SQL CONNECT TO sample

If you want to use a specific user id (herrick) and password (mypassword), use the
following statement:
EXEC SQL CONNECT TO sample USER herrick USING mypassword

Connecting to DB2 databases in REXX Embedded SQL

applications
When working with REXX applications, a database connection is established by
executing the following statement. This statement creates a connection to the
sample database using the default user name.
CALL SQLEXEC CONNECT TO sample

If you want to use a specific user id (herrick) and password (mypassword), use the
following statement:
CALL SQLEXEC CONNECT TO sample USER herrick USING mypassword

Data types that map to SQL data types in embedded SQL applications
To exchange data between an application and database, you must use the correct
data type mappings for the variables used.
When the precompiler finds a host variable declaration, it determines the
appropriate SQL type value. With each host language there are special mapping
rules which must be adhered to, unique only to that specific language.

38

Developing Embedded SQL Applications

Supported SQL data types in C and C++ embedded SQL

applications
Certain predefined C and C++ data types correspond to DB2 database column
types. You can declare only these C and C++ data types as host variables.
The following tables show the C and C++ equivalent of each column type. When
the precompiler finds a host variable declaration, it determines the appropriate
SQL type value. The database manager uses this value to convert the data
exchanged between the application and itself.
Table 2. SQL Data Types Mapped to C and C++ Declarations
SQL Column Type1

C and C++ Data Type

SMALLINT
(500 or 501)

short
short int
sqlint16

INTEGER
(496 or 497)

int
long
long int
sqlint322

BIGINT
(492 or 493)

long long
long
__int64
sqlint643

SQL Column Type Description

16-bit signed integer

32-bit signed integer

64-bit signed integer

float

Single-precision floating point

double

Double-precision floating point

No exact equivalent; use double

Packed decimal

REAL5
(480 or 481)
DOUBLE6
(480 or 481)
DECIMAL(p,s)
(484 or 485)

(Consider using the CHAR and DECIMAL

functions to manipulate packed decimal
fields as character data.)
char

Single character

CHAR(1)
(452 or 453)
CHAR(n)
(452 or 453)

No exact equivalent; use

Fixed-length character string
char[n+1] where n is large enough
to hold the data
1<=n<=254

Chapter 3. Programming

39

Table 2. SQL Data Types Mapped to C and C++ Declarations (continued)

SQL Column Type1

C and C++ Data Type

SQL Column Type Description

VARCHAR(n)
(448 or 449)

struct tag {
short int;
char[n]
}

Non null-terminated varying character string

with 2-byte string length indicator.
Note: A host variable structure of the
following form is always treated as a
VARCHAR host variable and cannot be
declared:

1<=n<=32 672

struct tag {
short int;
char[n]
}

Alternatively, use char[n+1] where Null-terminated variable-length character

n is large enough to hold the data string
Note: Assigned an SQL type of 460/461.
1<=n<=32 672
LONG VARCHAR8
(456 or 457)

struct tag {
short int;
char[n]
}

Non null-terminated varying character string

with 2-byte string length indicator

32 673<=n<=32 700
CLOB(n)
(408 or 409)

sql type is
clob(n)

Non null-terminated varying character string

with 4-byte string length indicator

1<=n<=2 147 483 647

CLOB locator variable7
(964 or 965)

sql type is
clob_locator

CLOB file reference variable7

(920 or 921)

sql type is
clob_file

BLOB(n)
(404 or 405)

sql type is
blob(n)

Identifies CLOB entities residing on the

server
Descriptor for file containing CLOB data

Non null-terminated varying binary string

with 4-byte string length indicator

1<=n<=2 147 483 647

Identifies BLOB entities on the server
BLOB locator variable7
(960 or 961)

sql type is
blob_locator

BLOB file reference variable7

(916 or 917)

sql type is
blob_file

Descriptor for the file containing BLOB data

DATE
(384 or 385)

TIME
(388 or 389)

40

Null-terminated character form

Allow at least 11 characters to accommodate

the null-terminator

VARCHAR structured form

Allow at least 10 characters

Null-terminated character form

Allow at least 9 characters to accommodate

the null-terminator

VARCHAR structured form

Allow at least 8 characters

Developing Embedded SQL Applications

Table 2. SQL Data Types Mapped to C and C++ Declarations (continued)

SQL Column Type1
TIMESTAMP(p)
4
(392 or 393)

C and C++ Data Type

SQL Column Type Description

Null-terminated character form

Allow 20- 33 characters to accommodate for

the null-terminator

VARCHAR structured form

Allow 19-32 characters.

XML value

XML8
(988 or 989)

struct {
sqluint32 length;
char
data[n];
}
1<=n<=2 147 483 647
SQLUDF_CLOB

BINARY

unsigned char myBinField[4];

Binary data

1<= n <=255
VARBINARY

struct
myVarBinField_t
{sqluint16 length;char data[12];}
myVarBinField;

Varbinary data

1<= n <=32704

The following data types are only available in the DBCS or EUC environment
when precompiled with the WCHARTYPE NOCONVERT option.
Table 3. SQL Data Types Mapped to C and C++ Declarations
SQL Column Type1

C and C++ Data Type

SQL Column Type Description

sqldbchar

Single double-byte character

No exact equivalent; use

sqldbchar[n+1] where n is large
enough to hold the data

Fixed-length double-byte character string

GRAPHIC(1)
(468 or 469)
GRAPHIC(n)
(468 or 469)

1<=n<=127
VARGRAPHIC(n)
(464 or 465)

struct tag {
short int;
sqldbchar[n]
}

Non null-terminated varying double-byte

character string with 2-byte string length
indicator

1<=n<=16 336
Alternatively use sqldbchar[n+1]
where n is large enough to hold
the data

Null-terminated variable-length double-byte

character string
Note: Assigned an SQL type of 400/401.

1<=n<=16 336

Chapter 3. Programming

41

Table 3. SQL Data Types Mapped to C and C++ Declarations (continued)

SQL Column Type1

C and C++ Data Type

LONG VARGRAPHIC8
(472 or 473)

struct tag {
short int;
sqldbchar[n]
}

SQL Column Type Description

Non null-terminated varying double-byte
character string with 2-byte string length
indicator

16 337<=n<=16 350

The following data types are only available in the DBCS or EUC environment
when precompiled with the WCHARTYPE CONVERT option.
Table 4. SQL Data Types Mapped to C and C++ Declarations
SQL Column Type1

C and C++ Data Type

SQL Column Type Description

wchar_t

v Single wide character (for C-type)

GRAPHIC(1)
(468 or 469)

GRAPHIC(n)
(468 or 469)

v Single double-byte character (for column

type)
No exact equivalent; use wchar_t
[n+1] where n is large enough to
hold the data

Fixed-length double-byte character string

1<=n<=127
VARGRAPHIC(n)
(464 or 465)

struct tag {
short int;
wchar_t [n]
}

Non null-terminated varying double-byte

character string with 2-byte string length
indicator

1<=n<=16 336
Alternately use char[n+1] where n Null-terminated variable-length double-byte
is large enough to hold the data
character string
Note: Assigned an SQL type of 400/401.
1<=n<=16 336
LONG VARGRAPHIC8
(472 or 473)

struct tag {
short int;
wchar_t [n]
}

Non null-terminated varying double-byte

character string with 2-byte string length
indicator

16 337<=n<=16 350

The following data types are only available in the DBCS or EUC environment.
Table 5. SQL Data Types Mapped to C and C++ Declarations
SQL Column Type1

C and C++ Data Type

SQL Column Type Description

DBCLOB(n)
(412 or 413)

sql type is
dbclob(n)

Non null-terminated varying double-byte

character string with 4-byte string length
indicator

1<=n<=1 073 741 823

42

Developing Embedded SQL Applications

Table 5. SQL Data Types Mapped to C and C++ Declarations (continued)

SQL Column Type1

C and C++ Data Type

DBCLOB locator variable7

(968 or 969)

sql type is
dbclob_locator

DBCLOB file reference

variable7
(924 or 925)

sql type is
dbclob_file

SQL Column Type Description

Identifies DBCLOB entities residing on the
server
Descriptor for file containing DBCLOB data

Note:
1. The first number under SQL Column Type indicates that an indicator variable is not provided, and the second
number indicates that an indicator variable is provided. An indicator variable is needed to indicate NULL values,
or to hold the length of a truncated string. These are the values that will be displayed in the SQLTYPE field of the
SQLDA for these data types.
2. For platform compatibility, use sqlint32. On 64-bit UNIX and Linux operating systems, "long" is a 64 bit integer.
On 64-bit Windows operating systems and 32-bit UNIX and Linux operating systems "long" is a 32 bit integer.
3. For platform compatibility, use sqlint64. The DB2 database system sqlsystm.h header file has a type definition for
sqlint64 as "__int64" on the supported Windows operating systems when using the Microsoft compiler, "long
long" on 32-bit UNIX and Linux operating systems, and "long" on 64 bit UNIX and Linux operating systems.
4.
The character string can be from 19 - 32 bytes in length without a null terminator depending on the number of
fractional seconds specified. The fractional seconds of the TIMESTAMP data type can be optionally specified with
0-12 digits of timestamp precision.
When a timestamp value is assigned to a timestamp variable with a different number of fractional seconds, the
value is either truncated or padded with 0's to match the format of the timestamp variable.
5. FLOAT(n) where 0 < n < 25 is a synonym for REAL. The difference between REAL and DOUBLE in the SQLDA is
the length value (4 or 8).
6. The following SQL types are synonyms for DOUBLE:
v FLOAT
v FLOAT(n) where 24 < n < 54 is a synonym for DOUBLE
v DOUBLE PRECISION
7. This is not a column type but a host variable type.
8. The SQL_TYP_XML/SQL_TYP_NXML value is returned by DESCRIBE requests only. It cannot be used directly
by the application to bind application resources to XML values.
9. The LONG VARCHAR and LONG VARGRAPHIC data types are deprecated and might be removed in a future
release. Choose the CLOB or DBCLOB data type instead.

The following items are additional rules for supported C and C++ data types:
v The data type char can be declared as char or unsigned char.
v The database manager processes null-terminated variable-length character string
data type char[n] (data type 460), as VARCHAR(m).
If LANGLEVEL is SAA1, the host variable length m equals the character
string length n in char[n] or the number of bytes preceding the first
null-terminator (\0), whichever is smaller.
If LANGLEVEL is MIA, the host variable length m equals the number of
bytes preceding the first null-terminator (\0).
v The database manager processes null-terminated, variable-length graphic string
data type, wchar_t[n] or sqldbchar[n] (data type 400), as VARGRAPHIC(m).
If LANGLEVEL is SAA1, the host variable length m equals the character
string length n in wchar_t[n] or sqldbchar[n], or the number of characters
preceding the first graphic null-terminator, whichever is smaller.

Chapter 3. Programming

43

 If LANGLEVEL is MIA, the host variable length m equals the number of

characters preceding the first graphic null-terminator.
v Unsigned numeric data types are not supported.
v The C and C++ data type int is not allowed because its internal representation
is machine dependent.

Data types for procedures, functions, and methods in C and C++

embedded SQL applications
There is a mapping between C and C++ and DB2 data types. When you are
writing your embedded SQL application, you must be aware of this mapping to
ensure that you do not have unexpected data type conversions or data truncation.
The following table lists the supported mappings between SQL data types and C
and C++ data types for procedures, UDFs, and methods.
Table 6. SQL Data Types Mapped to C and C++ Declarations
SQL Column Type1

C and C++ Data Type

SQL Column Type Description

short

16-bit signed integer

sqlint32

32-bit signed integer

sqlint64

64-bit signed integer

float

Single-precision floating point

double

Double-precision floating point

SMALLINT
(500 or 501)
INTEGER
(496 or 497)
BIGINT
(492 or 493)
REAL
(480 or 481)
DOUBLE
(480 or 481)
Not supported
DECIMAL(p,s)
(484 or 485)

CHAR(n)
(452 or 453)

To pass a decimal value, define the parameter

to be of a data type castable from DECIMAL
(for example CHAR or DOUBLE) and
explicitly cast the argument to this type.

char[n+1] where n is large enough Fixed-length, null-terminated character string

to hold the data
1<=n<=254

CHAR(n) FOR BIT DATA

(452 or 453)

char[n+1] where n is large enough Fixed-length character string

to hold the data
1<=n<=254

VARCHAR(n)
(448 or 449) (460 or 461)

char[n+1] where n is large enough Null-terminated varying length string

to hold the data
1<=n<=32 672

44

Developing Embedded SQL Applications

Table 6. SQL Data Types Mapped to C and C++ Declarations (continued)

SQL Column Type1

C and C++ Data Type

VARCHAR(n) FOR BIT DATA

(448 or 449)

struct {
sqluint16 length;
char[n]
}

SQL Column Type Description

Not null-terminated varying length character
string

1<=n<=32 672
LONG VARCHAR2
(456 or 457)

struct {
sqluint16 length;
char[n]
}

Not null-terminated varying length character

string

32 673<=n<=32 700
CLOB(n)
(408 or 409)

struct {
sqluint32 length;
char
data[n];
}

Not null-terminated varying length character

string with 4-byte string length indicator

1<=n<=2 147 483 647

BLOB(n)
(404 or 405)

struct {
sqluint32 length;
char
data[n];
}

Not null-terminated varying binary string

with 4-byte string length indicator

1<=n<=2 147 483 647

char[11]

Null-terminated character form

char[9]

Null-terminated character form

char[p+21] where p is large

enough to hold the data

Null-terminated character form

DATE
(384 or 385)
TIME
(388 or 389)
TIMESTAMP(p)
(392 or 393)

0<=p<=12
XML
(988/989)

Not supported

This descriptor type value (988/989) will be

defined to be used in the SQLDA for
describe, and to indicate XML Data (in its
serialized form). Existing character and
binary types (including LOBs and LOB file
reference types) can also be used to fetch and
insert the data (dynamic SQL only)

Note: The following data types are only available in the DBCS or EUC
environment when precompiled with the WCHARTYPE NOCONVERT option.

Chapter 3. Programming

45

Table 7. SQL Data Types Mapped to C and C++ Declarations

SQL Column Type1
GRAPHIC(n)
(468 or 469)

C and C++ Data Type

SQL Column Type Description

sqldbchar[n+1] where n is large

enough to hold the data

Fixed-length, null-terminated double-byte

character string

1<=n<=127
VARGRAPHIC(n)
(400 or 401)

sqldbchar[n+1] where n is large

enough to hold the data

Not null-terminated, variable-length

double-byte character string

1<=n<=16 336
LONG VARGRAPHIC2
(472 or 473)

struct {
sqluint16 length;
sqldbchar[n]
}

Not null-terminated, variable-length

double-byte character string

16 337<=n<=16 350
DBCLOB(n)
(412 or 413)

struct {
sqluint32 length;
sqldbchar data[n];
}

Not null-terminated varying length character

string with 4-byte string length indicator

1<=n<=1 073 741 823

Note:
1. The first number under SQL Column Type indicates that an indicator variable is not provided, and the second
number indicates that an indicator variable is provided. An indicator variable is needed to indicate NULL values,
or to hold the length of a truncated string. These are the values that will be displayed in the SQLTYPE field of the
SQLDA for these data types.
2. The LONG VARCHAR and LONG VARGRAPHIC data types are deprecated and might be removed in a future
release. Choose the CLOB or DBCLOB data type instead.

Supported SQL data types in COBOL embedded SQL

applications
Certain predefined COBOL data types correspond to DB2 database column types.
You can use only these COBOL data types as host variables.
The following table shows the COBOL equivalent of each column type. When the
precompiler finds a host variable declaration, it determines the appropriate SQL
type value. The database manager uses this value to convert the data exchanged
between the application and itself.
Not every possible data description for host variables is recognized. COBOL data
items must be consistent with the ones described in the following table. If you use
other data items, an error can result.
Table 8. SQL Data Types Mapped to COBOL Declarations
SQL Column Type1

COBOL Data Type

SQL Column Type

Description

01 name PIC S9(4) COMP-5.

16-bit signed integer

SMALLINT
(500 or 501)

46

Developing Embedded SQL Applications

Table 8. SQL Data Types Mapped to COBOL Declarations (continued)

SQL Column Type1

COBOL Data Type

SQL Column Type

Description

01 name PIC S9(9) COMP-5.

32-bit signed integer

01 name PIC S9(18) COMP-5.

64-bit signed integer

01 name PIC S9(m)V9(n) COMP-3.

Packed decimal

01 name USAGE IS COMP-1.

Single-precision floating
point

01 name USAGE IS COMP-2.

Double-precision floating
point

01 name PIC X(n).

Fixed-length character
string

INTEGER
(496 or 497)
BIGINT
(492 or 493)
DECIMAL(p,s)
(484 or 485)
REAL2
(480 or 481)
DOUBLE3
(480 or 481)
CHAR(n)
(452 or 453)
VARCHAR(n)
(448 or 449)

01 name.
49 length PIC S9(4) COMP-5.
49 name PIC X(n).

Variable-length character
string

1<=n<=32 672
LONG VARCHAR6
(456 or 457)

01 name.
49 length PIC S9(4) COMP-5.
49 data PIC X(n).

Long variable-length
character string

32 673<=n<=32 700
CLOB(n)
(408 or 409)

01 MY-CLOB USAGE IS SQL TYPE IS CLOB(n).

Large object
variable-length character
string

1<=n<=2 147 483 647

CLOB locator variable4
(964 or 965)
CLOB file reference variable4
(920 or 921)

01 MY-CLOB-LOCATOR USAGE IS SQL TYPE IS

CLOB-LOCATOR.

Identifies CLOB entities

residing on the server

01 MY-CLOB-FILE USAGE IS SQL TYPE IS

CLOB-FILE.

Descriptor for file

containing CLOB data

01 MY-BLOB USAGE IS SQL TYPE IS BLOB(n).

Large object
variable-length binary
string

BLOB(n)
(404 or 405)
1<=n<=2 147 483 647
BLOB locator variable4
(960 or 961)

01 MY-BLOB-LOCATOR USAGE IS SQL TYPE IS

BLOB-LOCATOR.

Identifies BLOB entities

residing on the server

Chapter 3. Programming

47

Table 8. SQL Data Types Mapped to COBOL Declarations (continued)

SQL Column Type1
BLOB file reference variable4
(916 or 917)

COBOL Data Type

SQL Column Type

Description

01 MY-BLOB-FILE USAGE IS SQL TYPE IS

BLOB-FILE.

Descriptor for file

containing BLOB data

01 identifier PIC X(10).

10-byte character string

01 identifier PIC X(8).

8-byte character string

01 identifier PIC X(p+20).

19 to 32 byte character
string

DATE
(384 or 385)
TIME
(388 or 389)
TIMESTAMP(p)
(392 or 393)

0<=p<=12

XML5
(988 or 989)

01 name USAGE IS SQL TYPE IS XML

AS CLOB (size).

A 19 byte character string

can be used, when p is 0.
XML value

The following data types are only available in the DBCS environment.
Table 9. SQL Data Types Mapped to COBOL Declarations
SQL Column Type1

COBOL Data Type

01 name PIC G(n) DISPLAY-1.

GRAPHIC(n)
(468 or 469)
VARGRAPHIC(n)
(464 or 465)

01 name.
49 length PIC S9(4) COMP-5.
49 name PIC G(n) DISPLAY-1.

SQL Column Type

Description
Fixed-length double-byte
character string
Variable length
double-byte character
string with 2-byte string
length indicator

1<=n<=16 336
LONG VARGRAPHIC6
(472 or 473)

01 name.
49 length PIC S9(4) COMP-5.
49 name PIC G(n) DISPLAY-1.

Variable length
double-byte character
string with 2-byte string
length indicator

16 337<=n<=16 350
DBCLOB(n)
(412 or 413)

DBCLOB locator variable4

(968 or 969)
DBCLOB file reference
variable4
(924 or 925)

48

01 MY-DBCLOB USAGE IS SQL TYPE IS DBCLOB(n). Large object

variable-length double-byte
character string with
4-byte string length
1<=n<=1 073 741 823
indicator
01 MY-DBCLOB-LOCATOR USAGE IS SQL TYPE IS
DBCLOB-LOCATOR.

Identifies DBCLOB entities

residing on the server

01 MY-DBCLOB-FILE USAGE IS SQL TYPE IS

DBCLOB-FILE.

Descriptor for file

containing DBCLOB data

Developing Embedded SQL Applications

Table 9. SQL Data Types Mapped to COBOL Declarations (continued)

SQL Column Type1

SQL Column Type

Description

COBOL Data Type

Note:
1. The first number under SQL Column Type indicates that an indicator variable is not provided, and the second
number indicates that an indicator variable is provided. An indicator variable is needed to indicate NULL values,
or to hold the length of a truncated string. These are the values that will be displayed in the SQLTYPE field of the
SQLDA for these data types.
2. FLOAT(n) where 0 < n < 25 is a synonym for REAL. The difference between REAL and DOUBLE in the SQLDA is
the length value (4 or 8).
3. The following SQL types are synonyms for DOUBLE:
v FLOAT
v FLOAT(n) where 24 < n < 54 is a synonym for DOUBLE.
v DOUBLE PRECISION
4. This is not a column type but a host variable type.
5. The SQL_TYP_XML/SQL_TYP_NXML value is returned by DESCRIBE requests only. It cannot be used directly
by the application to bind application resources to XML values.
6. The LONG VARCHAR and LONG VARGRAPHIC data types are deprecated and might be removed in a future
release. Choose the CLOB or DBCLOB data type instead.

The list of rules for supported COBOL data types are:

v PIC S9 and COMP-3/COMP-5 are required where shown.
v You can use level number 77 instead of 01 for all column types except
VARCHAR, LONG VARCHAR, VARGRAPHIC, LONG VARGRAPHIC and all
LOB variable types.
v Use the following rules when declaring host variables for DECIMAL(p,s) column
types. See the following sample:
01 identifier PIC S9(m)V9(n) COMP-3

Use V to denote the decimal point.

Values for n and m must be greater than or equal to 1.
The value for n + m cannot exceed 31.
The value for s equals the value for n.
The value for p equals the value for n + m.
The repetition factors (n) and (m) are optional. The following examples are all
valid:
01
01
01
01

identifier
identifier
identifier
identifier

PIC
PIC
PIC
PIC

S9(3)V COMP-3
SV9(3) COMP-3
S9V COMP-3
SV9 COMP-3

PACKED-DECIMAL can be used instead of COMP-3.

v Arrays are not supported by the COBOL precompiler.

Supported SQL data types in FORTRAN embedded SQL

applications
Certain predefined FORTRAN data types correspond to DB2 database column
types. You can declare only these FORTRAN data types as host variables.
The following table shows the FORTRAN equivalent of each column type. When
the precompiler finds a host variable declaration, it determines the appropriate
SQL type value. The database manager uses this value to convert the data
exchanged between the application and itself.

Chapter 3. Programming

49

Table 10. SQL Data Types Mapped to FORTRAN Declarations

SQL Column Type1

FORTRAN Data Type

SQL Column Type Description

INTEGER*2

16-bit, signed integer

INTEGER*4

32-bit, signed integer

REAL*4

Single precision floating point

REAL*8

Double precision floating point

No exact equivalent; use REAL*8

Packed decimal

CHARACTER*n

Fixed-length character string of length n

where n is from 1 to 254

SMALLINT
(500 or 501)
INTEGER
(496 or 497)
REAL2
(480 or 481)
DOUBLE3
(480 or 481)
DECIMAL(p,s)
(484 or 485)
CHAR(n)
(452 or 453)
VARCHAR(n)
(448 or 449)
LONG VARCHAR5
(456 or 457)
CLOB(n)
(408 or 409)

SQL TYPE IS VARCHAR(n) where Variable-length character string

n is from 1 to 32 672
SQL TYPE IS VARCHAR(n) where Long variable-length character string
n is from 32 673 to 32 700
SQL TYPE IS CLOB (n) where n is Large object variable-length character string
from 1 to 2 147 483 647
SQL TYPE IS CLOB_LOCATOR

Identifies CLOB entities residing on the

server

SQL TYPE IS CLOB_FILE

Descriptor for file containing CLOB data

SQL TYPE IS BLOB(n) where n is

from 1 to 2 147 483 647

Large object variable-length binary string

SQL TYPE IS BLOB_LOCATOR

Identifies BLOB entities on the server

SQL TYPE IS BLOB_FILE

Descriptor for the file containing BLOB data

CHARACTER*10

10-byte character string

CHARACTER*8

8-byte character string

CLOB locator variable4

(964 or 965)
CLOB file reference variable4
(920 or 921)
BLOB(n)
(404 or 405)
BLOB locator variable4
(960 or 961)
BLOB file reference variable4
(916 or 917)
DATE
(384 or 385)
TIME
(388 or 389)

50

Developing Embedded SQL Applications

Table 10. SQL Data Types Mapped to FORTRAN Declarations (continued)

SQL Column Type1
TIMESTAMP(p)
(392 or 393)
XML
(988 or 989)

FORTRAN Data Type

SQL Column Type Description

CHARACTER*19 to
CHARACTER*32

19 to 32 byte character string

SQL_TYP_XML

There is no XML support for FORTRAN;

applications are able to get the describe type
back but will not be able to make use of it.

Note:
1.

The first number under SQL Column Type indicates that an indicator variable is not provided, and the second
number indicates that an indicator variable is provided. An indicator variable is needed to indicate NULL values,
or to hold the length of a truncated string. These are the values that will be displayed in the SQLTYPE field of the
SQLDA for these data types.

2. FLOAT(n) where 0 < n < 25 is a synonym for REAL. The difference between REAL and DOUBLE in the SQLDA is
the length value (4 or 8).
3. The following SQL types are synonyms for DOUBLE:
v FLOAT
v FLOAT(n) where 24 < n < 54 is a synonym for DOUBLE.
v DOUBLE PRECISION
4. This is not a column type but a host variable type.
5. The LONG VARCHAR data type is deprecated, not recommended, and might be removed in a future release.
Choose the CLOB data type instead.

The rule for supported FORTRAN data types is:

v You can define dynamic SQL statements longer than 254 characters by using
VARCHAR, or CLOB host variables.

Supported SQL data types in REXX embedded SQL

applications
Certain predefined REXX data types correspond to DB2 database column types.
You can declare only these REXX data types as host variables.
The following table shows how SQLEXEC and SQLDBS interpret REXX variables
in order to convert their contents to DB2 data types.
Table 11. SQL Column Types Mapped to REXX Declarations
SQL Column Type1
SMALLINT
(500 or 501)
INTEGER
(496 or 497)
REAL2
(480 or 481)
DOUBLE3
(480 or 481)

REXX Data Type

SQL Column Type Description

A number without a decimal point

ranging from -32 768 to 32 767

16-bit signed integer

A number without a decimal point

ranging from -2 147 483 648 to 2 147 483
647

32-bit signed integer

A number in scientific notation ranging

Single-precision floating point
from -3.40282346 x 1038 to 3.40282346 x 1038
A number in scientific notation ranging
from -1.79769313 x 10308 to 1.79769313 x
10308

Double-precision floating point

Chapter 3. Programming

51

Table 11. SQL Column Types Mapped to REXX Declarations (continued)

SQL Column Type1

REXX Data Type

SQL Column Type Description

A number with a decimal point

Packed decimal

A string with a leading and trailing

quotation mark ('), which has length n
after removing the two quotation marks

Fixed-length character string of length n

where n is from 1 to 254

DECIMAL(p,s)
(484 or 485)
CHAR(n)
(452 or 453)

A string of length n with any non-numeric

characters, other than leading and trailing
blanks or the E in scientific notation
Equivalent to CHAR(n)

Variable-length character string of length

n, where n ranges from 1 to 4000

Equivalent to CHAR(n)

Variable-length character string of length

n, where n ranges from 1 to 32 700

Equivalent to CHAR(n)

Large object variable-length character

string of length n, where n ranges from 1
to 2 147 483 647

DECLARE :var_name LANGUAGE TYPE

CLOB LOCATOR

Identifies CLOB entities residing on the

server

DECLARE :var_name LANGUAGE TYPE

CLOB FILE

Descriptor for file containing CLOB data

VARCHAR(n)
(448 or 449)
LONG VARCHAR5
(456 or 457)
CLOB(n)
(408 or 409)
CLOB locator variable4
(964 or 965)
CLOB file reference
variable4
(920 or 921)
BLOB(n)
(404 or 405)

BLOB locator variable4

(960 or 961)
BLOB file reference
variable4
(916 or 917)

A string with a leading and trailing

Large object variable-length binary string
apostrophe, preceded by BIN, containing n of length n, where n ranges from 1 to 2
characters after removing the preceding
147 483 647
BIN and the two apostrophes.
DECLARE :var_name LANGUAGE TYPE
BLOB LOCATOR

Identifies BLOB entities on the server

DECLARE :var_name LANGUAGE TYPE

BLOB FILE

Descriptor for the file containing BLOB

data

Equivalent to CHAR(10)

10-byte character string

Equivalent to CHAR(8)

8-byte character string

Equivalent to CHAR(26)

26-byte character string

SQL_TYP_XML

There is no XML support for REXX;

applications are able to get the describe
type back but will not be able to make use
of it.

DATE
(384 or 385)
TIME
(388 or 389)
TIMESTAMP
(392 or 393)
XML
(988 or 989)

52

Developing Embedded SQL Applications

The following data types are only available in the DBCS environment.
Table 12. SQL Column Types Mapped to REXX Declarations
SQL Column Type1

REXX Data Type

GRAPHIC(n)
(468 or 469)

A string with a leading and trailing

Fixed-length graphic string of length
n, where n is from 1 to 127
apostrophe preceded by a G or N,
containing n DBCS characters after
removing the preceding character and
the two apostrophes
Equivalent to GRAPHIC(n)

Variable-length graphic string of

length n, where n ranges from 1 to
2000

Equivalent to GRAPHIC(n)

Long variable-length graphic string of

length n, where n ranges from 1 to 16
350

Equivalent to GRAPHIC(n)

Large object variable-length graphic

string of length n, where n ranges
from 1 to 1 073 741 823

DECLARE :var_name LANGUAGE

TYPE DBCLOB LOCATOR

Identifies DBCLOB entities residing

on the server

DECLARE :var_name LANGUAGE

TYPE DBCLOB FILE

Descriptor for file containing

DBCLOB data

VARGRAPHIC(n)
(464 or 465)
LONG VARGRAPHIC5
(472 or 473)
DBCLOB(n)
(412 or 413)
DBCLOB locator variable4
(968 or 969)
DBCLOB file reference
variable4
(924 or 925)

SQL Column Type Description

Note:
1. The first number under Column Type indicates that an indicator variable is not provided, and the second number
indicates that an indicator variable is provided. An indicator variable is needed to indicate NULL values, or to
hold the length of a truncated string.
2. FLOAT(n) where 0 < n < 25 is a synonym for REAL. The difference between REAL and DOUBLE in the SQLDA is
the length value (4 or 8).
3. The following SQL types are synonyms for DOUBLE:
v FLOAT
v FLOAT(n) where 24 < n < 54 is a synonym for DOUBLE.
v DOUBLE PRECISION
4. This is not a column type but a host variable type.
5. The LONG VARCHAR and LONG VARGRAPHIC data types are deprecated, not recommended, and might be
removed in a future release. Use the CLOB or DBCLOB data type instead.

Host Variables in embedded SQL applications

Host variables are variables that are referenced by embedded SQL statements. Host
variables are used to exchange data values between the database server and the
embedded SQL application.
Embedded SQL applications can also include host variable declarations for
relational SQL queries. Furthermore, a host variable can be used to contain an
XQuery expression to be executed. There is, however, no mechanism for passing
values to parameters in XQuery expressions.
Host variables are declared using the host language specific variable declaration
syntax in a declaration section.

Chapter 3. Programming

53

A declaration section is the portion of an embedded SQL application found near

the top of an embedded SQL source code file, and is bounded by two
non-executable SQL statements:
v BEGIN DECLARE SECTION
v END DECLARE SECTION
These statements enable the precompiler to find the variable declarations. Each
host variable declaration must be used in between these two statements, otherwise
the variables are considered to be only regular variables.
The following rules apply to host variable declaration sections:
v All host variables must be declared in the source file within a well formed
declaration section before they are referenced, except for host variables referring
to SQLDA structures.
v Multiple declare sections can be used in one source file.
v Host variable names must be unique within a source file. This is because the
DB2 precompiler does not account for host language-specific variable scoping
rules. As such, there is only one scope for host variables.
Note: This does not mean that the DB2 precompiler changes the scope of host
variables to global so that they can be accessed outside the scope in which they
are defined.
Consider the following example:
foo1(){
.
.
.
BEGIN SQL DECLARE SECTION;
int x;
END SQL DECLARE SECTION;
x=10;
.
.
.
}
foo2(){
.
.
.
y=x;
.
.
.
}

Depending on the language, this example will either fail to compile because
variable x is not declared in function foo2(), or the value of x is not set to 10 in
foo2(). To avoid this problem, you must either declare x as a global variable, or
pass x as a parameter to function foo2() as follows:
foo1(){
.
.
.
BEGIN SQL DECLARE SECTION;
int x;
END SQL DECLARE SECTION;

54

Developing Embedded SQL Applications

x=10;
foo2(x);
.
.
.
}
foo2(int x){
.
.
.
y=x;
.
.
.
}

Declaring host variables in embedded SQL applications

To transmit data between the database server and the application, declare host
variables in your application source code for things such as relational SQL queries
and host variable declarations for XQuery expressions.

About this task

The following table provides examples of host variable declarations for embedded
SQL host languages.
Table 13. Host Variable Declarations by Host Language
Language

Example Source Code

C and C++

EXEC SQL BEGIN DECLARE SECTION;

short
dept=38, age=26;
double
salary;
char
CH;
char
name1[9], NAME2[9];
short
nul_ind;
EXEC SQL END DECLARE SECTION;

COBOL

FORTRAN

EXEC
01
01
01
01
01
01
01
EXEC

SQL BEGIN DECLARE SECTION END-EXEC.

age
PIC S9(4) COMP-5 VALUE 26.
DEPT
PIC S9(9) COMP-5 VALUE 38.
salary
PIC S9(6)V9(3) COMP-3.
CH
PIC X(1).
name1
PIC X(8).
NAME2
PIC X(8).
nul-ind
PIC S9(4) COMP-5.
SQL END DECLARE SECTION END-EXEC.
EXEC SQL BEGIN DECLARE SECTION
integer*2
age
/26/
integer*4
dept /38/
real*8
salary
character
ch
character*8
name1,NAME2
integer*2
nul_ind
EXEC SQL END DECLARE SECTION

Chapter 3. Programming

55

Declaring Host Variables with the db2dclgn Declaration

Generator
You can use the Declaration Generator to generate declarations for a given table in
a database. It creates embedded SQL declaration source files which you can easily
insert into your applications. db2dclgn supports the C/C++, Java, COBOL, and
FORTRAN languages.

About this task

To generate declaration files, enter the db2dclgn command in the following format:
db2dclgn -d database-name -t table-name [options]

For example, to generate the declarations for the STAFF table in the SAMPLE
database in C in the output file staff.h, issue the following command:
db2dclgn -d sample -t staff -l C

The resulting staff.h file contains:

struct
{
short id;
struct
{
short length;
char data[9];
} name;
short dept;
char job[6];
short years;
double salary;
double comm;
} staff;

Column data types and host variables in embedded SQL

applications
Supported embedded SQL host languages have data types that correspond to the
majority of the database manager data types. You can use only these host language
data types in host variable declarations.
Each table column is given an SQL data type when the column is created. For
information about how these types are assigned to columns, see the CREATE
TABLE statement.
Note:
1. Every supported data type can have the NOT NULL attribute. This is treated as
another type.
2. Data types can be extended by defining user-defined distinct types (UDT).
UDTs are separate data types that use the representation of one of the built-in
SQL types.
Supported embedded SQL host languages have data types that correspond to the
majority of the database manager data types. Only these host language data types
can be used in host variable declarations. When the precompiler finds a host
variable declaration, it determines the appropriate SQL data type value. The
database manager uses this value to convert the data exchanged between itself and
the application.

56

Developing Embedded SQL Applications

As the application programmer, it is important for you to understand how the

database manager handles comparisons and assignments between different data
types. Simply put, data types must be compatible with each other during
assignment and comparison operations, whether the database manager is working
with two SQL column data types, two host-language data types, or one of each.
The general rule for data type compatibility is that all supported host-language
numeric data types are comparable and assignable with all database manager
numeric data types, and all host-language character types are compatible with all
database manager character types; numeric types are incompatible with character
types. However, there are also some exceptions to this general rule, depending on
host language idiosyncrasies and limitations imposed when working with large
objects.
Within SQL statements, DB2 provides conversions between compatible data types.
For example, in the following SELECT statement, SALARY and BONUS are
DECIMAL columns; however, each employee's total compensation is returned as
DOUBLE data:
SELECT EMPNO, DOUBLE(SALARY+BONUS) FROM EMPLOYEE

Note that the execution of this statement includes conversion between DECIMAL
and DOUBLE data types.
To make the query results more readable on your screen, you could use the
following SELECT statement:
SELECT EMPNO, CHAR(SALARY+BONUS) FROM EMPLOYEE

The CAST function used in the preceding example returns a character-string

representation of a number.
To convert data within your application, contact your compiler vendor for
additional routines, classes, built-in types, or APIs that support this conversion.
If your application code page is not the same as your database code page,
character data types can also be subject to character conversion.

Declaring XML host variables in embedded SQL applications

To exchange XML data between the database server and an embedded SQL
application, you need to declare host variables in your application source code.

About this task

DB2 V9.1 introduces an XML data type that stores XML data in a structured set of
nodes in a tree format. Columns with this XML data type are described as an
SQL_TYP_XML column SQLTYPE, and applications can bind various
language-specific data types for input to and output from these columns or
parameters. XML columns can be accessed directly using SQL, the SQL/XML
extensions, or XQuery. The XML data type applies to more than just columns.
Functions can have XML value arguments and produce XML values as well.
Similarly, stored procedures can take XML values as both input and output
parameters. Finally, XQuery expressions produce XML values regardless of
whether they access XML columns.
XML data is character in nature and has an encoding that specifies the character
set used. The encoding of XML data can be determined externally, derived from
Chapter 3. Programming

57

the base application type containing the serialized string representation of the XML
document. It can also be determined internally, which requires interpretation of the
data. For Unicode encoded documents, a byte order mark (BOM), consisting of a
Unicode character code at the beginning of a data stream is recommended. The
BOM is used as a signature that defines the byte order and Unicode encoding
form.
Existing character and binary types, which include CHAR, VARCHAR, CLOB, and
BLOB may be used in addition to XML host variables for fetching and inserting
data. However, they will not be subject to implicit XML parsing, as XML host
variables would. Instead, an explicit XMLPARSE function with default white space
stripping is injected and applied.
XML and XQuery restrictions on developing embedded SQL applications
To declare XML host variables in embedded SQL applications:
In the declaration section of the application, declare the XML host variables as LOB
data types:
v
SQL TYPE IS XML AS CLOB(n) <hostvar_name>

where <hostvar_name> is a CLOB host variable that contains XML data encoded
in the mixed code page of the application.
v
SQL TYPE IS XML AS DBCLOB(n) <hostvar_name>

where <hostvar_name> is a DBCLOB host variable that contains XML data

encoded in the application graphic code page.
v
SQL TYPE IS XML AS BLOB(n) <hostvar_name>

where <hostvar_name> is a BLOB host variable that contains XML data

internally encoded1.
v
SQL TYPE IS XML AS CLOB_FILE <hostvar_name>

where <hostvar_name> is a CLOB file that contains XML data encoded in the
application mixed code page.
v
SQL TYPE IS XML AS DBCLOB_FILE <hostvar_name>

where <hostvar_name> is a DBCLOB file that contains XML data encoded in the
application graphic code page.
v
SQL TYPE IS XML AS BLOB_FILE <hostvar_name>

where <hostvar_name> is a BLOB file that contains XML data internally

encoded1.
Note:
1. Refer to the algorithm for determining encoding with XML 1.0 specifications
(http://www.w3.org/TR/REC-xml/#sec-guessing-no-ext-info).

58

Developing Embedded SQL Applications

Identifying XML values in an SQLDA

To indicate that a base type holds XML data, you must update the sqlname field in
the associated SQLDA structure. If you do not indicate that a base type holds XML
data, your embedded SQL application might not return the expected results.
To indicate that a base type holds XML data, the sqlname field of the SQLVAR
must be updated as follows:
v sqlname.length must be 8
v The first two bytes of sqlname.data must be X0000
v The third and fourth bytes of sqlname.data must be X0000
v The fifth byte of sqlname.data must be X01 (referred to as the XML subtype
indicator only when the first two conditions are met)
v The remaining bytes must be X000000
If the XML subtype indicator is set in an SQLVAR whose SQLTYPE is non-LOB, an
SQL0804 error (rc=115) will be returned at runtime.
Note: SQL_TYP_XML can only be returned from the DESCRIBE statement. This
type cannot be used for any other requests. The application must modify the
SQLDA to contain a valid character or binary type, and set the sqlname field
appropriately to indicate that the data is XML.

Identifying null SQL values with null indicator variables

You must prepare embedded SQL applications for receiving null values by
associating a null-indicator variable with any host variable that can receive a null
value. A null-indicator variable is shared by both the database manager and the
host application.
Therefore, you must declare this variable in the application as a host variable,
which corresponds to the SQL data type SMALLINT.

About this task

A null-indicator variable is placed in an SQL statement immediately after the host
variable, and is prefixed with a colon. A space can separate the null-indicator
variable from the host variable, but is not required. However, do not put a comma
between the host variable and the null-indicator variable. You can also specify a
null-indicator variable by using the optional INDICATOR keyword, which you
place between the host variable and its null indicator.
The null-indicator variable is examined for a negative value. If the value is not
negative, the application can use the returned value of the host variable. If the
value is negative, the fetched value is null and the host variable should not be
used. The database manager does not change the value of the host variable in this
case.
Note: If the database configuration parameter dft_sqlmathwarn is set to 'YES', the
null-indicator variable value may be -2. This value indicates a null that was either
caused by evaluating an expression with an arithmetic error, or by an overflow
while attempting to convert the numeric result value to the host variable.
If the data type can handle nulls, the application must provide a null indicator.
Otherwise, an error may occur. If a null indicator is not used, an SQLCODE -305
(SQLSTATE 22002) is returned.
Chapter 3. Programming

59

If the SQLCA structure indicates a truncation warning, the null-indicator variables

can be examined for truncation. If a null-indicator variable has a positive value, a
truncation occurred.
v If the seconds' portion of a TIME data type is truncated, the null-indicator value
contains the seconds portion of the truncated data.
v For all other string data types, except large objects (LOB), the null-indicator
value represents the actual length of the data returned. User-defined distinct
types (UDT) are handled in the same way as their base type.
When processing INSERT or UPDATE statements, the database manager checks the
null-indicator variable, if one exists. If the indicator variable is negative, the
database manager sets the target column value to null, if nulls are allowed.
If the null-indicator variable is zero or positive, the database manager uses the
value of the associated host variable.
Starting in DB2 V10.1 Fix Pack 2 and later, if the new PRECOMPILE UNSAFENULL
option is set to YES, the NULL values will not cause unspecified indicator variable
error. This option is applicable only when COMPATIBILITY_MODE is set to ORA.
Starting in DB2 V10.1 Fix Pack 2 and later, application can check sqlca.sqlerrd[2] to
get cumulative sum of number of rows populated successfully till the last FETCH
using same cursor.
The SQLWARN1 field in the SQLCA structure might contain an X or W if the value
of a string column is truncated when it is assigned to a host variable. The field
contains an N if a null terminator is truncated.
A value of X is returned by the database manager only if all of the following
conditions are met:
v A mixed code page connection exists where conversion of character string data
from the database code page to the application code page involves a change in
the length of the data.
v A cursor is blocked.
v A null-indicator variable is provided by your application.
The value returned in the null-indicator variable will be the length of the resultant
character string in the application's code page.
In all other cases involving data truncation (as opposed to null terminator
truncation), the database manager returns a W. In this case, the database manager
returns a value in the null-indicator variable to the application that is the length of
the resultant character string in the code page of the select list item (either the
application code page, the database code page, or nothing).
Before you can use null-indicator variables in the host language, declare the
null-indicator variables. In the following example, suitable for C and C++
programs, the null-indicator variable cmind can be declared as:
EXEC SQL BEGIN DECLARE SECTION;
char cm[3];
short cmind;
EXEC SQL END DECLARE SECTION;

The following table provides examples for the supported host languages:

60

Developing Embedded SQL Applications

Table 14. Null-Indicator Variables by Host Language

Language

Example Source Code

C and C++

EXEC SQL FETCH C1 INTO :cm INDICATOR :cmind;

if ( cmind < 0 )
printf( "Commission is NULL\n" );

COBOL

EXEC SQL FETCH C1 INTO :cm INDICATOR :cmind END-EXEC

IF cmind LESS THAN 0
DISPLAY Commission is NULL

FORTRAN

EXEC SQL FETCH C1 INTO :cm INDICATOR :cmind

IF ( cmind .LT. 0 ) THEN
WRITE(*,*) Commission is NULL
ENDIF

REXX

CALL SQLEXEC FETCH C1 INTO :cm INDICATOR :cmind

IF ( cmind < 0 )
SAY Commission is NULL

Including SQLSTATE and SQLCODE host variables in

embedded SQL applications
You can review error information that is returned in the SQLCODE and SQLSTATE
fields of the SQLCA structure. The SQLCA structure is updated after every
executable SQL statement and most database manager API calls.

Before you begin

If your application is compliant with the FIPS 127-2 standard, you can declare host
variables named SQLSTATE and SQLCODE instead of explicitly declaring the
SQLCA structure in embedded SQL applications.
v The PREP option LANGLEVEL SQL92E needs to be specified

About this task

In the following example, the application checks the SQLCODE field of the SQLCA
structure to determine whether the update was successful.
Table 15. Embedding SQL Statements in a Host Language
Language

Sample Source Code

C and C++

EXEC SQL UPDATE staff SET job = Clerk WHERE job = Mgr;
if ( SQLCODE < 0 )
printf( "Update Error: SQLCODE =

COBOL

EXEC SQL UPDATE staff SET job = Clerk WHERE job = Mgr END_EXEC.
IF SQLCODE LESS THAN 0
DISPLAY UPDATE ERROR: SQLCODE = , SQLCODE.

FORTRAN

EXEC SQL UPDATE staff SET job = Clerk WHERE job = Mgr
if ( sqlcode .lt. 0 ) THEN
write(*,*) Update error: sqlcode = , sqlcode

Referencing host variables in embedded SQL applications

After you have declared a host variable in your embedded SQL application code,
you can reference it later in the application.

Chapter 3. Programming

61

About this task

When you use a host variable in an SQL statement, prefix its name with a colon (:).
If you use a host variable in host language programming syntax, omit the colon.
Reference the host variables using the syntax for the host language that you are
using. The following table provides examples.
Table 16. Host Variable References by Host Language
Language

Example Source Code

C or C++

EXEC SQL FETCH C1 INTO :cm;

printf( "Commission = %f\n", cm );

COBOL

EXEC SQL FETCH C1 INTO :cm END-EXEC

DISPLAY Commission = cm

FORTRAN

EXEC SQL FETCH C1 INTO :cm

WRITE(*,*) Commission = , cm

REXX

CALL SQLEXEC FETCH C1 INTO :cm

SAY Commission = cm

Example: Referencing XML host variables in embedded SQL

applications
You can create XML host variables in embedded SQL applications so that you can
read and process XML data.
The following sample applications demonstrate how to reference XML host
variables in C and COBOL.

Example: Embedded SQL C application:

The following code example has been formatted for clarity:
EXEC SQL BEGIN DECLARE;
SQL TYPE IS XML AS CLOB( 10K ) xmlBuf;
SQL TYPE IS XML AS BLOB( 10K ) xmlblob;
SQL TYPE IS CLOB( 10K ) clobBuf;
EXEC SQL END DECLARE SECTION;
// as XML AS CLOB
// The XML value written to xmlBuf will be prefixed by an XML declaration
// similar to: <?xml version = "1.0" encoding = "ISO-8859-1" ?>
// Note: The encoding name will depend upon the application codepage
EXEC SQL SELECT xmlCol INTO :xmlBuf
FROM myTable
WHERE id = 001;
EXEC SQL UPDATE myTable
SET xmlCol = :xmlBuf
WHERE id = 001;
// as XML AS BLOB
// The XML value written to xmlblob will be prefixed by an XML declaration
// similar to: <?xml version = "1.0" encoding = "UTF-8"?>
EXEC SQL SELECT xmlCol INTO :xmlblob
FROM myTable
WHERE id = 001;
EXEC SQL UPDATE myTable
SET xmlCol = :xmlblob
WHERE id = 001;
// as CLOB

62

Developing Embedded SQL Applications

// The output will be encoded in the application character codepage,

// but will not contain an XML declaration
EXEC SQL SELECT XMLSERIALIZE (xmlCol AS CLOB(10K)) INTO :clobBuf
FROM myTable
WHERE id = 001;
EXEC SQL UPDATE myTable
SET xmlCol = XMLPARSE (:clobBuf PRESERVE WHITESPACE)
WHERE id = 001;

Example: Embedded SQL COBOL application:

The following code example has been formatted for clarity:
EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 xmlBuf USAGE IS SQL TYPE IS XML as CLOB(5K).
01 clobBuf USAGE IS SQL TYPE IS CLOB(5K).
01 xmlblob USAGE IS SQL TYPE IS BLOB(5K).
EXEC SQL END DECLARE SECTION END-EXEC.
* as XML
EXEC SQL SELECT xmlCol INTO :xmlBuf
FROM myTable
WHERE id = 001 END-EXEC.
EXEC SQL UPDATE myTable
SET xmlCol = :xmlBuf
WHERE id = 001 END-EXEC.
* as BLOB
EXEC SQL SELECT xmlCol INTO :xmlblob
FROM myTable
WHERE id = 001 END-EXEC.
EXEC SQL UPDATE myTable
SET xmlCol = :xmlblob
WHERE id = 001 END-EXEC.
* as CLOB
EXEC SQL SELECT XMLSERIALIZE(xmlCol AS CLOB(10K)) INTO :clobBuf
FROM myTable
WHERE id= 001 END-EXEC.
EXEC SQL UPDATE myTable
SET xmlCol = XMLPARSE(:clobBuf) PRESERVE WHITESPACE
WHERE id = 001 END-EXEC.

Host variables in C and C++ embedded SQL applications

Host variables are C or C++ language variables that are referenced within SQL
statements. Host variables allow an application to exchange data with the database
manager.
After the application is precompiled, host variables are used by the compiler as
any other C or C++ variable. Follow the rules described in the following sections
when naming, declaring, and using host variables.

Long variable considerations

In applications that manually construct the SQLDA, long variables cannot be used
when sqlvar::sqltype==SQL_TYP_INTEGER. Instead, sqlint32 types must be used.
This problem is identical to using long variables in host variable declarations,
except that with a manually constructed SQLDA, the precompiler will not uncover
this error and run time errors will occur.
Any long and unsigned long casts that are used to access sqlvar::sqldata
information must be changed to sqlint32 and sqluint32. Val members for the
sqloptions and sqla_option structures are declared as sqluintptr. Therefore,
Chapter 3. Programming

63

assignment of pointer members into sqla_option::val or sqloptions::val

members should use sqluintptr casts rather than unsigned long casts. This change
will not cause runtime problems in 64-bit UNIX and Linux operating systems, but
should be made in preparation for 64-bit Windows applications, where the long
type is only 32-bit.

Multi-byte encoding considerations

Some character encoding schemes, particularly those from east-Asian regions,
require multiple bytes to represent a character. This external representation of data
is called the multi-byte character code representation of a character, and includes
double-byte characters (characters represented by two bytes). Host variables will be
chosen accordingly since graphic data in DB2 consists of double-byte characters.
To manipulate character strings with double-byte characters, it may be convenient
for an application to use an internal representation of data. This internal
representation is called the wide-character code representation of the double-byte
characters, and is the format customarily used in the wchar_t C or C++ data type.
Subroutines that conform to ANSI C and X/OPEN Portability Guide 4 (XPG4) are
available to process wide-character data, and to convert data in wide-character
format to and from multi-byte format.
Note that although an application can process character data in either multi-byte
format or wide-character format, interaction with the database manager is done
with DBCS (multi-byte) character codes only. That is, data is stored in and
retrieved from GRAPHIC columns in DBCS format. The WCHARTYPE
precompiler option is provided to allow application data in wide-character format
to be converted to/from multi-byte format when it is exchanged with the database
engine.

Host variable names in C and C++ embedded SQL applications

The SQL precompiler identifies host variables by their declared name.
The following rules apply when declaring host variable names:
v Host variable names must be no longer than 255 characters in length.
v Host variable names must not use the prefix SQL, sql, DB2, and db2, which are
reserved for system use. For example:
EXEC SQL BEGIN DECLARE SECTION;
char varsql;
/* allowed */
char sqlvar;
/* not allowed */
char SQL_VAR;
/* not allowed */
EXEC SQL END DECLARE SECTION;

v The precompiler supports the same scope rules as the C and C++ programming
languages. Therefore, you can use the same name for two different variables
each existing within their own scope. In the following example, both
declarations of the variable called empno are allowed; the second declaration
does not cause an error:
file: main.sqc
...
void scope1()
{
EXEC SQL BEGIN DECLARE SECTION ;
short empno;
EXEC SQL END DECLARE SECTION ;

64

Developing Embedded SQL Applications

...
}
void scope2()
{
EXEC SQL BEGIN DECLARE SECTION ;
char[15 + 1] empno;

/* this declaration is allowed */

EXEC SQL END DECLARE SECTION ;

...
}

Declare section for host variables in C and C++ embedded SQL

applications
You must use an SQL declare section to identify host variable declarations. SQL
declare sections alert the precompiler to any host variables that can be referenced
in subsequent SQL statements.
For example:
EXEC SQL BEGIN DECLARE SECTION;
char varsql;
/* allowed */
EXEC SQL END DECLARE SECTION;

The C or C++ precompiler only recognizes a subset of valid C or C++ declarations

as valid host variable declarations. These declarations define either numeric or
character variables. Host variables can be grouped into a single host structure. You
can declare C++ class data members as host variables.
A numeric host variable can be used as an input or output variable for any
numeric SQL input or output value. A character host variable can be used as an
input or output variable for any character, date, time, or timestamp SQL input or
output value. The application must ensure that output variables are long enough to
contain the values that they receive.
You can define, name, and use a host variable within the SQL declare section. In
the following example, a struct type called staff_record is first defined. Then the
variable named staff_detail is declared as being of type staff_record:
EXEC SQL BEGIN DECLARE SECTION ;
typedef struct {
short id;
VARCHAR name[10+1];
short years;
double salary;
} staff_record;
staff_record staff_detail;
EXEC SQL END DECLARE SECTION ;
...
SELECT id, name, years, salary
FROM staff
INTO :staff_detail
WHERE id = 10;
...

Example: SQL declare section template for C and C++ embedded

SQL applications
When you are creating an embedded SQL application in C or C++, there is a
template that you can use to declare your host variables and data structures.
Chapter 3. Programming

65

The following example is a sample SQL declare section with host variables
declared for supported SQL data types:
EXEC SQL BEGIN DECLARE SECTION;
.
.
.
short
short
sqlint32
sqlint32
float
double
char
char
struct

struct

sql type
sql type
sql type
sql type
sql type
sql type
sql type
sql type
sql type
sql type
sql type
struct

struct

struct

struct

66

Developing Embedded SQL Applications

age = 26;
year;
salary;
deptno;
bonus;
wage;
mi;
name[6];
{
short len;
char data[24];
} address;
{
short len;
char data[32695];
} voice;
is clob(1m)
chapter;
is clob_locator
chapter_locator;
is clob_file
chapter_file_ref;
is blob(1m)
video;
is blob_locator
video_locator;
is blob_file
video_file_ref;
is dbclob(1m)
tokyo_phone_dir;
is dbclob_locator
tokyo_phone_dir_lctr;
is dbclob_file
tokyo_phone_dir_flref;
is varbinary(12)
myVarBinField;
is binary(4)
myBinField;
{
short len;
sqldbchar data[100];
} vargraphic1;
{
short len;
wchar_t data[100];
} vargraphic2;
{
short len;
sqldbchar data[10000];
} long_vargraphic1;
{
short len;
wchar_t data[10000];

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

SQL
SQL
SQL
SQL
SQL
SQL
SQL
SQL

type
type
type
type
type
type
type
type

500
500
496
496
480
480
452
460

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

/* SQL type

448 */

/* SQL type

456 */

/* SQL type

408 */

/* SQL type

964 */

/* SQL type

920 */

/* SQL type

404 */

/* SQL type

960 */

/* SQL type

916 */

/* SQL type

412 */

/* SQL type

968 */

/* SQL type

924 */

/* SQL type

908 */

/* SQL type

912 */

/* SQL type 464 */

/* Precompiled with
WCHARTYPE NOCONVERT option */

/* SQL type 464 */

/* Precompiled with
WCHARTYPE CONVERT option */

/* SQL type 472 */

/* Precompiled with
WCHARTYPE NOCONVERT option */

} long_vargraphic2;
sqldbchar graphic1[100];
wchar_t

graphic2[100];

char
char
char
short

date[11];
time[9];
timestamp[27];
wage_ind;

/* SQL type 472 */

/* Precompiled with
WCHARTYPE CONVERT option */
/* SQL type 468 */
/* Precompiled with
WCHARTYPE NOCONVERT option */
/* SQL type 468 */
/* Precompiled with
WCHARTYPE CONVERT option */
/* SQL type 384 */
/* SQL type 388 */
/* SQL type 392 */
/* Null indicator */

.
.
.
EXEC SQL END DECLARE SECTION;

SQLSTATE and SQLCODE variables in C and C++ embedded

SQL application
Your embedded SQL application can declare the SQLCODE and SQLSTATE
variables to handle errors or help you debug your embedded SQL application.
When using the LANGLEVEL precompile option with a value of SQL92E, the
following two declarations can be included as host variables:
EXEC SQL BEGIN DECLARE SECTION;
char
SQLSTATE[6]
sqlint32 SQLCODE;
EXEC SQL END DECLARE SECTION;

The SQLCODE declaration is assumed during the precompile step. Note that when
using this option, the INCLUDE SQLCA statement must not be specified.
In an application that is made up of multiple source files, the SQLCODE and
SQLSTATE variables can be defined in the first source file as in the previous
example. Subsequent source files should modify the definitions as follows:
extern sqlint32 SQLCODE;
extern char
SQLSTATE[6];

C-array host and indicator variables

If you set the precompiler option COMPATIBILITY_MODE to ORA, you can use
C-array host variables and indicator variable arrays with FETCH INTO statements.

C-array host variables

By using C-array host variables, you can declare a cursor and do a bulk fetch into
the array variable until the end of the row is reached.
Array variables used in the same fetch need to have an equal number of elements,
otherwise the smallest number of elements declared for an array variable is used
and a warning is displayed. The size of the array variable can vary from 2 to 32K.
In one FETCH, the maximum number of records that can be retrieved is the
maximum number of elements declared for the array variables. If more rows are

Chapter 3. Programming

67

available after the first fetch, you can repeat the FETCH statement to obtain the
next set of rows. The cumulative sum of the total number of rows fetched is stored
in sqlca.sqlerrd[2].
In the following example, two array host variables are declared, empno and
lastname. Each can hold up to 100 elements. Because there is only one FETCH
statement, this example retrieves 100 rows, or less.
EXEC SQL BEGIN DECLARE SECTION;
char
empno[100][8];
char
lastname[100][15];
EXEC SQL END DECLARE SECTION;
EXEC SQL DECLARE empcr CURSOR FOR
SELECT empno, lastname FROM employee;
EXEC SQL OPEN empcr;
EXEC SQL WHENEVER NOT FOUND GOTO end_fetch;
while (1) {
EXEC SQL FETCH empcr INTO :empno :lastname;
...
...
}
end_fetch:
EXEC SQL CLOSE empcr;

/* bulk fetch
*/
/* 100 or less rows */

Starting in DB2 V10.1 Fix Pack 2 and later, DB2 for Linux, UNIX, and Windows
Embedded SQL C/C++ supports host variables as structure array during the fetch.
The array size is determined by the structure array defined in the DECLARE SECTION.
DB2 for Linux, UNIX, and Windows Embedded SQL C/C++ will not support
another structure array within the main structure array (nested structure arrays); if
it finds such usage, user will see a compiler error.
This table will be used in the following scenarios:
CREATE
INSERT
INSERT
INSERT

TABLE tn1 (c1 NUMBER, c2 VARCHAR2(10));

INTO TN1 VALUES (1, TEMP DATA1);
INTO TN1 VALUES (2, NULL);
INTO TN1 VALUES (NULL, NULL);

FETCH statement using structure for host variables with using structure for
indicators:
EXEC SQL BEGIN DECLARE SECTION;
struct MyStruct
{
int c1;
char c2[11];
}MyStructVar;
struct MyStructInd
{
short c1_ind;
short c2_ind;
}MyStructVarInd;
EXEC SQL END DECLARE SECTION;
...
EXEC SQL DECLARE cur3 CURSOR FOR SELECT C1, C2 FROM TN1;
EXEC SQL OPEN cur;
EXEC SQL WHENEVER NOT FOUND DO CONTINUE;
do
{

68

Developing Embedded SQL Applications

EXEC SQL FETCH cur3 INTO :MyStructVar :MyStructInd;

// print output after calling FETCH Statement
printf("%d(%d) %s(%d)\n",
MyStructVar.c1, MyStructVarInd.c1_ind,
MyStructVar.c2, MyStructVarInd.c2_ind);
} while (sqlca.sqlcode != 100);
printf ( "# of rows fetched : %d\n", sqlca.sqlerrd[2];

FETCH statement using structure array for host variable with structure array for
indicators:
EXEC SQL BEGIN DECLARE SECTION;
int rows_before, rows_fetched_this_time;
int nrows;
struct MyStruct
{
int c1;
char c2[11];
}MyStructVar[3];
struct MyStructInd
{
short c1_ind;
short c2_ind;
}MyStructVarInd[3];
EXEC SQL END DECLARE SECTION;
...
EXEC SQL DECLARE cur3 CURSOR FOR SELECT C1 FROM TN1;
EXEC SQL OPEN cur3;
EXEC SQL FETCH cur3 INTO :MyStructVar :MyStructInd;
rows_before=0;
EXEC SQL WHENEVER NOT FOUND DO BREAK;
while (1)
{
EXEC SQL FETCH cur3 INTO :MyStructVar :MyStructInd;
rows_fetched_this_time = sqlca.sqlerrd[2] - rows_before;
rows_before = sqlca.sqlerrd[2];
// print output after calling FETCH Statement
for (i= 0; i < rows_fetched_this_time; i++)
{
printf("%d(%d) %s(%d)\n",
MyStructVar[i].c1, MyStructVarInd[i].c1_ind,
MyStructVar[i].c2, MyStructVarInd[i].c2_ind,
}
printf("Total rows_before = %d\n", rows_before);
}
EXEC SQL WHENEVER NOT FOUND CONTINUE;
if (sqlca.sqlcode != SQL_ERROR)
{
rows_fetched_this_time = sqlca.sqlerrd[2] - rows_before;
for (i= 0; i < rows_fetched_this_time; i++)
{
printf("%d %d %s\n", c1[i], MyStructVar[i].c2);
}
}
else{
...
}
printf ( " Total # of rows fetched : %d\n", sqlca.sqlerrd[2];
Chapter 3. Programming

69

Note: Support is enabled only for PRECOMPILE option with COMPATIBILITY_MODE set
to ORA. A single FETCH operation does not support multiple structures or a
combination of structures and host variable arrays.

INDICATOR variable arrays

In FETCH statements, you can use indicator variable arrays to determine whether
any elements of array variables are NULL. If an indicator variable contains a value
less than zero, this identifies the corresponding array value as NULL.
You can use the keyword INDICATOR to identify an indicator variable, as shown
in the example.
In the following example, the indicator variable array called bonus_ind is declared.
It can have up to 100 elements, the same amount as declared for the array variable,
bonus. When the data is being fetched, if the value of bonus is NULL, the value in
bonus_ind will be negative.
EXEC SQL BEGIN DECLARE SECTION;
char
empno[100][8];
char
lastname[100][15];
short edlevel[100];
double bonus[100];
short bonus_ind[100];
EXEC SQL END DECLARE SECTION;
EXEC SQL DECLARE empcr CURSOR FOR
SELECT empno, lastname, edlevel, bonus
FROM employee
WHERE workdept = D21;
EXEC SQL OPEN empcr;
EXEC SQL WHENEVER NOT FOUND GOTO end_fetch;
while (1) {
EXEC SQL FETCH empcr INTO :empno :lastname :edlevel,
:bonus INDICATOR :bonus_ind
...
...
}
end_fetch:
EXEC SQL CLOSE empcr;

Instead of being identified by the INDICATOR keyword, an indicator variable can

immediately follow its corresponding host variable. In following example,
:bonus:bonus_ind is used instead of :bonus INDICATOR :bonus_ind.
EXEC SQL FETCH empcr INTO :empno :lastname :edlevel, :bonus:bonus_ind

If the number of elements for an indicator array variable does not match the
number of elements of the corresponding host array variable, an error is returned.
Starting in DB2 V10.1 Fix Pack 2 and later, you can use structure and structure
array as indicator placeholder. The current indicator table does not support as
indicators for the structure array host variables. Structure array for indicator will
be supported only with COMPATIBILITY_MODE set to ORA.
// declaring structure array of size 3 for indicator
EXEC SQL BEGIN DECLARE SECTION;
...
struct MyStructInd

70

Developing Embedded SQL Applications

{
short c1_ind;
short c2_ind;
} MyStructVarInd[3];
EXEC SQL END DECLARE SECTION;
...
// using structure array host variables & indicators structure type
// array while executing FETCH statement
// 'MyStructVar' is structure array for host variables
// 'MyStructVarInd' is structure array for indicators
EXEC SQL FETCH cur INTO :MyStructVar :MyStructVarInd;

Note: Array size of structure used for indicator must be equal or more than array
size of structure used for host variables. All members in structure array used for
indicator must be of data type short. Also, number of members in structures used
for host variables and corresponding indicators must be equal. If any of these
conditions are not met then PRECOMPILE will throw an error.

Declaration of numeric host variables in C and C++ embedded

SQL applications
Numeric host variables that you declare in your embedded C or C++ application
are treated as if they were declared in a C or C++ program. You can use host
variables to exchange data between the embedded application and the database
manager.
Following is the syntax for declaring numeric host variables in C or C++.
(1)
float

auto
extern
static
register

const
volatile

(2)

double
(3)
short
int
INTEGER (SQLTYPE 496)
BIGINT (SQLTYPE 492)

,



varname

;
=

*
&



value

const
volatile

INTEGER (SQLTYPE 496)

sqlint32
(4)
long
int

Chapter 3. Programming

71

BIGINT (SQLTYPE 492)

sqlint64
__int64
long long
int
(5)
long
int

Notes:
1

REAL (SQLTYPE 480), length 4

DOUBLE (SQLTYPE 480), length 8

SMALLINT (SQLTYPE 500)

For maximum application portability, use sqlint32 for INTEGER host

variables and sqlint64 for BIGINT host variables. By default, the use of long
host variables results in the precompiler error SQL0402 on platforms where
long is a 64 bit quantity, such as 64 BIT UNIX. Use the PREP option
LONGERROR NO to force DB2 to accept long variables as acceptable host
variable types and treat them as BIGINT variables.

For maximum application portability, use sqlint32 and sqlint64 for

INTEGER and BIGINT host variables. To use the BIGINT data type, your
platform must support 64 bit integer values. By default, the use of long host
variables results in the precompiler error SQL0402 on platforms where long is
a 64 bit quantity, such as 64 BIT UNIX. Use the PREP option LONGERROR
NO to force DB2 to accept long variables as acceptable host variable types
and treat them as BIGINT variables.

Declaration of fixed-length, null-terminated and variable-length

character host variables in C and C++ embedded SQL
applications
There are two forms of C and C++ variables that you can declare in an embedded
SQL application. Form 1 variables are fixed length and null-terminated character
host variables and form 2 are variable-length character host variables.
Form 1: Syntax for fixed and null-terminated character host variables in C or
C++ embedded SQL applications

char
auto
extern
static
register

const
volatile

unsigned

,



72

CHAR
C String

Developing Embedded SQL Applications

;
=

value



CHAR
(1)
varname

*
&

const
volatile

C String
(2)
varname
(

[
varname

*
&

length

const
volatile

Notes:
1

CHAR (SQLTYPE 452), length 1

Null-terminated C string (SQLTYPE 460); length can be any valid constant

expression

Form 2: Syntax for variable-length character host variables in C and C++

embedded SQL applications

struct
auto
extern
static
register

tag

const
volatile

(1)

{ short

var1 ;
int

char var2 [ length ]

; }

unsigned

,



varname



Values


*
&

const
volatile

Values
=

{ value-1 ,

value-2

Chapter 3. Programming

73

Notes:
1

In form 2, length can be any valid constant expression. Its value after
evaluation determines if the host variable is VARCHAR (SQLTYPE 448) or
LONG VARCHAR (SQLTYPE 456).

Variable-Length Character Host Variable Considerations:

1. Although the database manager converts character data to either form 1 or
form 2 whenever possible, form 1 corresponds to column types CHAR or
VARCHAR, whereas form 2 corresponds to column types VARCHAR and
LONG VARCHAR.
2. If form 1 is used with a length specifier [n], the value for the length specifier
after evaluation must be no greater than 32 672, and the string contained by the
variable should be null-terminated.
3. If form 2 is used, the value for the length specifier after evaluation must be no
greater than 32 700.
4. In form 2, var1 and var2 must be simple variable references (no operators), and
cannot be used as host variables (varname is the host variable).
5. varname can be a simple variable name, or it can include operators such as
*varname. See the description of pointer data types in C and C++ for more
information.
6. The precompiler determines the SQLTYPE and SQLLEN of all host variables. If
a host variable appears in an SQL statement with an indicator variable, the
SQLTYPE is assigned to be the base SQLTYPE plus one for the duration of that
statement.
7. The precompiler permits some declarations which are not syntactically valid in
C or C++. Refer to your compiler documentation if in doubt about a particular
declaration syntax.

Declaration of graphic host variables in C and C++ embedded

SQL applications
To handle graphic data in C or C++ applications, you must use host variables
based on either the wchar_t C or C++ data type or the sqldbchar data type.
You can assign graphic data host variables to columns of a table that are
GRAPHIC, VARGRAPHIC, or DBCLOB. For example, you can update or select
DBCS data from GRAPHIC or VARGRAPHIC columns of a table.
There are three valid forms for a graphic host variable:
v Single-graphic form
Single-graphic host variables have an SQLTYPE of 468/469 that is equivalent to
the GRAPHIC(1) SQL data type.
v Null-terminated graphic form
Null-terminated refers to the situation where all the bytes of the last character of
the graphic string contain binary zeros ('\0's). They have an SQLTYPE of
400/401.
v VARGRAPHIC structured form
VARGRAPHIC structured host variables have an SQLTYPE of 464/465 if their
length is between 1 and 16 336 bytes. They have an SQLTYPE of 472/473 if their
length is between 2 000 and 16 350 bytes.

74

Developing Embedded SQL Applications

wchar_t and sqldbchar data types for graphic data in C and C++
embedded SQL applications
The size and encoding of DB2 graphic data is constant from one platform to
another for a particular code page. However, the size and internal format of the
ANSI C or C++ wchar_t data type depends on which compiler and operating
system you are using.
The sqldbchar data type, however, is defined by DB2 to be two bytes in size, and
is intended to be a portable way of manipulating DBCS and UCS-2 data in the
same format in which it is stored in the database.
You can define all DB2 C graphic host variable types using either wchar_t or
sqldbchar. You must use wchar_t if you build your application using the
WCHARTYPE CONVERT precompile option.
Note: When specifying the WCHARTYPE CONVERT option on a Windows
operating system, you must note that wchar_t on Windows operating systems is
Unicode. Therefore, if your C or C++ compiler's wchar_t is not Unicode, the
wcstombs() function call can fail with SQLCODE -1421 (SQLSTATE=22504). If this
happens, you can specify the WCHARTYPE NOCONVERT option, and explicitly
call the wcstombs() and mbstowcs() functions from within your program.
If you build your application with the WCHARTYPE NOCONVERT precompile
option, you should use sqldbchar for maximum portability between different DB2
client and server platforms. You can use wchar_t with WCHARTYPE
NOCONVERT, but only on platforms where wchar_t is defined as two bytes in
length.
If you incorrectly use either wchar_t or sqldbchar in host variable declarations, you
will receive an SQLCODE 15 (no SQLSTATE) at precompile time.

WCHARTYPE precompiler option for graphic data in C and C++

embedded SQL applications
You can use the WCHARTYPE precompiler option to specify if you want to use
multi-byte format or in wide-character format for your graphic data.
There are two possible values for the WCHARTYPE option:
CONVERT
If you select the WCHARTYPE CONVERT option, character codes are
converted between the graphic host variable and the database manager.
For graphic input host variables, the character code conversion from
wide-character format to multi-byte DBCS character format is performed
before the data is sent to the database manager, using the ANSI C function
wcstombs(). For graphic output host variables, the character code
conversion from multi-byte DBCS character format to wide-character
format is performed before the data received from the database manager is
stored in the host variable, using the ANSI C function mbstowcs().
The advantage to using WCHARTYPE CONVERT is that it allows your
application to fully exploit the ANSI C mechanisms for dealing with
wide-character strings (L-literals, 'wc' string functions, and so on) without
having to explicitly convert the data to multi-byte format before
communicating with the database manager. The disadvantage is that the
implicit conversions may have an impact on the performance of your
application at run time, and may increase memory requirements.

Chapter 3. Programming

75

If you select WCHARTYPE CONVERT, declare all graphic host variables

using wchar_t instead of sqldbchar.
If you want WCHARTYPE CONVERT behavior, but your application does
not need to be precompiled (for example, a CLI application), then define
the C preprocessor macro SQL_WCHART_CONVERT at compile time. This
ensures that certain definitions in the DB2 header files use the data type
wchar_t instead of sqldbchar.
NOCONVERT (default)
If you choose the WCHARTYPE NOCONVERT option, or do not specify
any WCHARTYPE option, no implicit character code conversion occurs
between the application and the database manager. Data in a graphic host
variable is sent to and received from the database manager as unaltered
DBCS characters. This has the advantage of improved performance, but the
disadvantage that your application must either refrain from using
wide-character data in wchar_t host variables, or must explicitly call the
wcstombs() and mbstowcs() functions to convert the data to and from
multi-byte format when interfacing with the database manager.
If you select WCHARTYPE NOCONVERT, declare all graphic host
variables using the sqldbchar type for maximum portability to other DB2
client/server platforms.
Other guidelines you need to observe are:
v Because wchar_t or sqldbchar support is used to handle DBCS data, its use
requires DBCS or EUC capable hardware and software. This support is only
available in the DBCS environment of DB2 for Linux, UNIX, and Windows, or
for dealing with GRAPHIC data in any application (including single-byte
applications) connected to a UCS-2 database.
v Non-DBCS characters, and wide-characters that can be converted to non-DBCS
characters, should not be used in graphic strings. Non-DBCS characters refers to
single-byte characters, and non-double byte characters. Graphic strings are not
validated to ensure that their values contain only double-byte character code
points. Graphic host variables must contain only DBCS data, or, if WCHARTYPE
CONVERT is in effect, wide-character data that converts to DBCS data. You
should store mixed double-byte and single-byte data in character host variables.
Note that mixed data host variables are unaffected by the setting of the
WCHARTYPE option.
v In applications where the WCHARTYPE NOCONVERT precompile option is
used, L-literals should not be used in conjunction with graphic host variables,
because L-literals are in wide-character format. An L-literal is a C wide-character
string literal prefixed by the letter L which has the data type "array of
wchar_t". For example, L"dbcs-string" is an L-literal.
v In applications where the WCHARTYPE CONVERT precompile option is used,
L-literals can be used to initialize wchar_t host variables, but cannot be used in
SQL statements. Instead of using L-literals, SQL statements should use graphic
string constants, which are independent of the WCHARTYPE setting.
v The setting of the WCHARTYPE option affects graphic data passed to and from
the database manager using the SQLDA structure as well as host variables. If
WCHARTYPE CONVERT is in effect, graphic data received from the application
through an SQLDA will be presumed to be in wide-character format, and will be
converted to DBCS format via an implicit call to wcstombs(). Similarly, graphic
output data received by an application will have been converted to
wide-character format before being placed in application storage.

76

Developing Embedded SQL Applications

v Not-fenced stored procedures must be precompiled with the WCHARTYPE

NOCONVERT option. Ordinary fenced stored procedures may be precompiled
with either the CONVERT or NOCONVERT options, which will affect the
format of graphic data manipulated by SQL statements contained in the stored
procedure. In either case, however, any graphic data passed into the stored
procedure through the SQLDA will be in DBCS format. Likewise, data passed
out of the stored procedure through the SQLDA must be in DBCS format.
v If an application calls a stored procedure through the Database Application
Remote Interface (DARI) interface (the sqleproc() API), any graphic data in the
input SQLDA must be in DBCS format, or in UCS-2 if connected to a UCS-2
database, regardless of the state of the calling application's WCHARTYPE
setting. Likewise, any graphic data in the output SQLDA will be returned in
DBCS format, or in UCS-2 if connected to a UCS-2 database, regardless of the
WCHARTYPE setting.
v If an application calls a stored procedure through the SQL CALL statement,
graphic data conversion will occur on the SQLDA, depending on the calling
application's WCHARTYPE setting.
v Graphic data passed to user-defined functions (UDFs) will always be in DBCS
format. Likewise, any graphic data returned from a UDF will be assumed to be
in DBCS format for DBCS databases, and UCS-2 format for EUC and UCS-2
databases.
v Data stored in DBCLOB files through the use of DBCLOB file reference variables
is stored in either DBCS format, or, in the case of UCS-2 databases, in UCS-2
format. Likewise, input data from DBCLOB files is retrieved either in DBCS
format, or, in the case of UCS-2 databases, in UCS-2 format.
Note:
1. For DB2 for Windows operating systems, the WCHARTYPE CONVERT option is
supported for applications compiled with the Microsoft Visual C++ compiler.
However, do not use the CONVERT option with this compiler if your application
inserts data into a DB2 database in a code page that is different from the
database code page. DB2 server normally performs a code page conversion in
this situation; however, the Microsoft C runtime environment does not handle
substitution characters for certain double byte characters. This could result in
run time conversion errors.
2. If you precompile C applications using the WCHARTYPE CONVERT option,
DB2 validates the applications' graphic data on both input and output as the
data is passed through the conversion functions. If you do not use the
CONVERT option, no conversion of graphic data, and hence no validation
occurs. In a mixed CONVERT/NOCONVERT environment, this may cause
problems if invalid graphic data is inserted by a NOCONVERT application and
then fetched by a CONVERT application. This data fails the conversion with an
SQLCODE -1421 (SQLSTATE 22504) on a FETCH in the CONVERT application.

Declaration of VARGRAPHIC type host variables in the

structured form in C or C++ embedded SQL applications
VARGRAPHIC type host variables that you declare in your embedded C or C++
application are treated as if they were declared in a C or C++ program. You can
use host variables to exchange data between the embedded application and the
database manager.
The following is the syntax for declaring a graphic host variable using the
VARGRAPHIC structured form.

Chapter 3. Programming

77



struct
auto
extern
static
register

tag

const
volatile

(1)

{ short

var-1 ;

(2)
sqldbchar
wchar_t

int

var-2 [ length

] ; }

,



Variable


*
&



const
volatile

Variable:
variable-name
= {

value-1

value-2

Notes:
1

To determine which of the two graphic types to be used, see the description
of the wchar_t and sqldbchar data types in C and C++.

length can be any valid constant expression. Its value after evaluation
determines if the host variable is VARGRAPHIC (SQLTYPE 464) or LONG
VARGRAPHIC (SQLTYPE 472). The value of length must be greater than or
equal to 1, and not greater than the maximum length of LONG
VARGRAPHIC which is 16 350.

Graphic declaration (VARGRAPHIC structured form) Considerations:

1. var-1 and var-2 must be simple variable references (no operators) and cannot be
used as host variables.
2. value-1 and value-2 are initializers for var-1 and var-2. value-1 must be an integer
and value-2 must be a wide-character string literal (L-literal) if the
WCHARTYPE CONVERT precompiler option is used.
3. The struct tag can be used to define other data areas, but itself cannot be used
as a host variable.

Declaration of GRAPHIC type host variables in single-graphic

and null-terminated graphic forms in C and C++ embedded SQL
applications
Single and null-terminated GRAPHIC type host variables that you declare in your
embedded C or C++ application are treated as if they were declared in a C or C++
program. You can use host variables to exchange data between the embedded
application and the database manager.
Following is the syntax for declaring a graphic host variable using the
single-graphic form and the null-terminated graphic form.

78

Developing Embedded SQL Applications

(1)



auto
extern
static
register

const
volatile

sqldbchar
wchar_t

,



CHAR
C string

;
=



value

CHAR
(2)
varname

*
&

const
volatile

C string
(3)
varname
(

[
varname

*
&

length

const
volatile

Notes:
1

To determine which of the two graphic types to be used, see the description
of the wchar_t and sqldbchar data types in C and C++.

GRAPHIC (SQLTYPE 468), length 1

Null-terminated graphic string (SQLTYPE 400)

Graphic host variable considerations:

1. The single-graphic form declares a fixed-length graphic string host variable of
length 1 with SQLTYPE of 468 or 469.
2. value is an initializer. A wide-character string literal (L-literal) must be used if
the WCHARTYPE CONVERT precompiler option is used.
3. length can be any valid constant expression, and its value after evaluation must
be greater than or equal to 1, and not greater than the maximum length of
VARGRAPHIC, which is 16 336.
4. Null-terminated graphic strings are handled differently, depending on the value
of the standards level precompile option setting.

Chapter 3. Programming

79

Declaration of large object type host variables in C and C++

embedded SQL applications
Large object (LOB) type host variables that you declare in your embedded C or
C++ application are treated as if they were declared in a C or C++ program. You
can use host variables to exchange data between the embedded application and the
database manager.
The syntax for declaring large object (LOB) host variables in C or C++ is:

SQL TYPE IS
auto
extern
static
register

const
volatile

XML AS

BLOB
CLOB
DBCLOB

(1)

(

length

,



variable-name

*
&

LOB data



const
volatile

LOB data

= { init-len , " init-data " }

=SQL_BLOB_INIT ( " init-data " )
=SQL_CLOB_INIT ( " init-data " )
=SQL_DBCLOB_INIT ( " init-data " )

Notes:
1

length can be any valid constant expression, in which the constant K, M, or G

can be used. The value of length after evaluation for BLOB and CLOB must
be 1 <= length <= 2 147 483 647. The value of length after evaluation for
DBCLOB must be 1 <= length <= 1 073 741 823.

LOB host variable considerations:

1. The SQL TYPE IS clause is needed to distinguish the three LOB-types from
each other so that type checking and function resolution can be carried out for
LOB-type host variables that are passed to functions.
2. SQL TYPE IS, BLOB, CLOB, DBCLOB, K, M, G can be in mixed case.
3. The maximum length allowed for the initialization string "init-data" is 32 702
bytes, including string delimiters (the same as the existing limit on C and C++
strings within the precompiler).
4. The initialization length, init-len, must be a numeric constant (for example, it
cannot include K, M, or G).

80

Developing Embedded SQL Applications

5. A length for the LOB must be specified; that is, the following declaration is not
permitted:
SQL TYPE IS BLOB my_blob;

6. If the LOB is not initialized within the declaration, no initialization will be done
within the precompiler-generated code.
7. If a DBCLOB is initialized, it is the user's responsibility to prefix the string with
an 'L' (indicating a wide-character string).
Note: Wide-character literals, for example, L"Hello", should only be used in a
precompiled program if the WCHARTYPE CONVERT precompile option is
selected.
8. The precompiler generates a structure tag which can be used to cast to the host
variable's type.

BLOB example:
Declaration:
static Sql Type is Blob(2M) my_blob=SQL_BLOB_INIT("mydata");

Results in the generation of the following structure:

static struct my_blob_t {
sqluint32
length;
char
data[2097152];
} my_blob=SQL_BLOB_INIT("mydata");

CLOB example:
Declaration:
volatile sql type is clob(125m) *var1, var2 = {10, "data5data5"};

Results in the generation of the following structure:

volatile struct var1_t {
sqluint32
length;
char
data[131072000];
} * var1, var2 = {10, "data5data5"};

DBCLOB example:
Declaration:
SQL TYPE IS DBCLOB(30000) my_dbclob1;

Precompiled with the WCHARTYPE NOCONVERT option, results in the

generation of the following structure:
struct my_dbclob1_t {
sqluint32
length;
sqldbchar
data[30000];
} my_dbclob1;

Declaration:
SQL TYPE IS DBCLOB(30000) my_dbclob2 = SQL_DBCLOB_INIT(L"mydbdata");

Precompiled with the WCHARTYPE CONVERT option, results in the generation of

the following structure:

Chapter 3. Programming

81

struct my_dbclob2_t {
sqluint32
length;
wchar_t
data[30000];
} my_dbclob2 = SQL_DBCLOB_INIT(L"mydbdata");

Declaration of large object locator type host variables in C and

C++ embedded SQL applications
Large object (LOB) locator host variables that you declare in your embedded C or
C++ application are treated as if they were declared in a C or C++ program. You
can use host variables to exchange data between the embedded application and the
database manager.
The syntax for declaring large object (LOB) locator host variables in C or C++ is:

SQL TYPE IS
auto
extern
static
register

const
volatile

BLOB_LOCATOR
CLOB_LOCATOR
DBCLOB_LOCATOR

,





Variable

Variable

*
&

variable-name
const
volatile

= init-value

LOB locator host variable considerations:

1. SQL TYPE IS, BLOB_LOCATOR, CLOB_LOCATOR, DBCLOB_LOCATOR can
be in mixed case.
2. init-value permits the initialization of pointer and reference locator variables.
Other types of initialization will have no meaning.
CLOB locator example (other LOB locator type declarations are similar):
Declaration:
SQL TYPE IS CLOB_LOCATOR my_locator;

Results in the generation of the following declaration:

sqluint32 my_locator;

Declaration of file reference type host variables in C and C++

embedded SQL applications
File reference type host variables that you declare in your embedded C or C++
application are treated as if they were declared in a C or C++ program. You can
use host variables to exchange data between the embedded application and the
database manager.

82

Developing Embedded SQL Applications

The syntax for declaring file reference host variables in C or C++ is:

Syntax for file reference host variables in C or C++

,

SQL TYPE IS
auto
extern
static
register

const
volatile

XML AS

BLOB_FILE
CLOB_FILE
DBCLOB_FILE



Variable

Variable

*
&

variable-name
const
volatile

= init-value

Figure 1. Syntax Diagram

Note: SQL TYPE IS, BLOB_FILE, CLOB_FILE, DBCLOB_FILE can be in mixed

case.
CLOB file reference example (other LOB file reference type declarations are
similar):
Declaration:
static volatile SQL TYPE IS BLOB_FILE my_file;

Results in the generation of the following structure:

static volatile struct {
sqluint32
name_length;
sqluint32
data_length;
sqluint32
file_options;
char
name[255];
} my_file;

Note: This structure is equivalent to the sqlfile structure located in the sql.h
header. See Figure 1 to refer to the syntax diagram.

Declaration of host variables as pointers in C and C++ embedded

SQL applications
You can declare host variables as pointers to specific data types. However, there
are some formatting guidelines that you should be aware of.
Before you can declare a host variable pointer, you must consider the following
restrictions:
v If a host variable is declared as a pointer, no other host variable can be declared
with that same name within the same source file. The following example is not
allowed:
char mystring[20];
char (*mystring)[20];

Chapter 3. Programming

83

v Use parentheses when declaring a pointer to a null-terminated character array.

In all other cases, parentheses are not allowed. For example:
EXEC SQL BEGIN DECLARE SECTION;
char (*arr)[10]; /* correct
*/
char *(arr);
/* incorrect */
char *arr[10];
/* incorrect */
EXEC SQL END DECLARE SECTION;

The first declaration is a pointer to a 10-byte character array. This is a valid host
variable. The second is not a valid declaration. The parentheses are not allowed
in a pointer to a character. The third declaration is an array of pointers. This is
not a supported data type.
The host variable declaration:
char *ptr;

is accepted, but it does not mean null-terminated character string of undetermined

length. Instead, it means a pointer to a fixed-length, single-character host variable.
This might not be what is intended. To define a pointer host variable that can
indicate different character strings, use the first declaration form shown
previously in this topic.
v When pointer host variables are used in SQL statements, they should be prefixed
by the same number of asterisks as they were declared with, as in the following
example:
EXEC SQL BEGIN DECLARE SECTION;
char (*mychar)[20];
/* Pointer to character array of 20 bytes */
EXEC SQL END DECLARE SECTION;
EXEC SQL SELECT column INTO :*mychar FROM table;

/* Correct */

v Only the asterisk can be used as an operator over a host variable name.
v The maximum length of a host variable name is not affected by the number of
asterisks specified, because asterisks are not considered part of the name.
v Whenever using a pointer variable in an SQL statement, you should leave the
optimization level precompile option (OPTLEVEL) at the default setting of 0 (no
optimization). This means that no SQLDA optimization will be done by the
database manager.

Declaration of class data members as host variables in C++

embedded SQL applications
You can declare class data members as host variables, but you cannot decalre
classes or objects as host variables.
The following example illustrates the method to use:
class STAFF
{
private:
EXEC SQL BEGIN DECLARE SECTION;
char
staff_name[20];
short int
staff_id;
double
staff_salary;
EXEC SQL END DECLARE SECTION;
short
staff_in_db;
.
.
};

Data members are only directly accessible in SQL statements through the implicit
this pointer provided by the C++ compiler in class member functions. You cannot
explicitly qualify an object instance (such as SELECT name INTO :my_obj.staff_name
...) in an SQL statement.

84

Developing Embedded SQL Applications

If you directly refer to class data members in SQL statements, the database
manager resolves the reference using the this pointer. For this reason, you should
leave the optimization level precompile option (OPTLEVEL) at the default setting
of 0 (no optimization).
The following example shows how you might directly use class data members
which you have declared as host variables in an SQL statement.
class STAFF
{
.
.
.
public:
.
.
.
short int hire( void )
{
EXEC SQL INSERT INTO staff ( name,id,salary )
VALUES ( :staff_name, :staff_id, :staff_salary );
staff_in_db = (sqlca.sqlcode == 0);
return sqlca.sqlcode;
}
};

In this example, class data members staff_name, staff_id, and staff_salary are
used directly in the INSERT statement. Because they have been declared as host
variables (see the first example in this section), they are implicitly qualified to the
current object with the this pointer. In SQL statements, you can also refer to data
members that are not accessible through the this pointer. You do this by referring
to them indirectly using pointer or reference host variables.
The following example shows a new method, asWellPaidAs that takes a second
object, otherGuy. This method references its members indirectly through a local
pointer or reference host variable, as you cannot reference its members directly
within the SQL statement.
short int STAFF::asWellPaidAs( STAFF otherGuy )
{
EXEC SQL BEGIN DECLARE SECTION;
short &otherID = otherGuy.staff_id
double otherSalary;
EXEC SQL END DECLARE SECTION;
EXEC SQL SELECT SALARY INTO :otherSalary
FROM STAFF WHERE id = :otherID;
if( sqlca.sqlcode == 0 )
return staff_salary >= otherSalary;
else
return 0;
}

Declaration of binary type host variables in C, C++ embedded

SQL applications
Binary host variables that you declare in your embedded C and C++ applications
are treated as if they were declared in a C or C++ program. You can use host
variables to exchange data between the embedded application and the database
manager.
The syntax for binary and varbinary locator host variables in C, C++ is:
Chapter 3. Programming

85



SQL TYPE IS 

BINARY
VARBINARY

length



Example
Declaring:
SQL TYPE IS BINARY(4) myBinField;

Results in the generation of the following C code:

unsigned char myBinField[4];
where length

N (1<= N <=255)

Declaring:
SQL TYPE IS VARBINARY(12) myVarBinField;

Results in the generation of the following C code:

struct myVarBinField_t { sqluint16 length;
char data[12];
} myVarBinField;
Where length is N (1<= N <=32704)

Embedded SQL application support of BINARY and VARBINARY

Embedded SQL application can copy BINARY data of predetermined length after
you declare the BINARY data type variable in the declare section. The
VARBINARY data type variable can be declared in the declare section of the
embedded SQL application with set length to copy the VARBINARY data.
The following example shows you how to use the BINARY and VARBINARY data
types in an embedded application:
EXEC SQL BEGIN DECLARE SECTION;
sql type is binary(50) binary1 ;
sql type is varbinary(100) binary2 ;
EXEC SQL END DECLARE SECTION;
char strng1[50];
char strng2[50];
memset( binary1, 0x00, sizeof(binary1) );
memset( binary2.data, 0x00, sizeof(binary2.data) );
strcpy( strng1, "AAAAAAZZZZZMMMMMMMMMJJJJJJJJJJJJJJ" );
strcpy( strng2, "BBBBBBBBBBBBBBBCCCCCCCCCCCDDDDDDDDEEEEEEEEEEEK" );
memcpy( binary1, strng1, strlen(strng1) );
memcpy( binary2.data, strng2, strlen(strng2) );
binary2.length = strlen(binary2.data);
EXEC SQL INSERT INTO test1 VALUES ( :binary1, :binary2 );

On retrieval from the database, the length of the data is set properly in the
corresponding structure.

Scope resolution and class member operators in C and C++

embedded SQL applications
You cannot use the C++ scope resolution operator '::', nor the C and C++ member
operators '.' or '->' in embedded SQL statements.

86

Developing Embedded SQL Applications

You can easily accomplish the same thing through use of local pointer or reference
variables, which are set outside the SQL statement, to point to the required scoped
variable, then used inside the SQL statement to refer to it. The following example
shows the correct method to use:
EXEC SQL BEGIN DECLARE SECTION;
char (& localName)[20] = ::name;
EXEC SQL END DECLARE SECTION;
EXEC SQL
SELECT name INTO :localName FROM STAFF
WHERE name = Sanders;

Japanese or Traditional Chinese EUC, and UCS-2 Considerations

in C and C++ embedded SQL applications
If your application code page is Japanese or Traditional Chinese EUC, or if your
application connects to a UCS-2 database, you can access GRAPHIC columns at a
database server by using either the CONVERT or the NOCONVERT option with
wchar_t or sqldbchar graphic host variables or input/output SQLDAs.
In this section, DBCS format refers to the UCS-2 encoding scheme for EUC data.
Consider listed cases:
v CONVERT option used
The DB2 client converts graphic data from the wide character format to your
application code page, then to UCS-2 before sending the input SQLDA to the
database server. Any graphic data is sent to the database server tagged with the
UCS-2 code page identifier. Mixed character data is tagged with the application
code page identifier. When graphic data is retrieved from a database by a client,
it is tagged with the UCS-2 code page identifier. The DB2 client converts the
data from UCS-2 to the client application code page, then to the wide character
format. If an input SQLDA is used instead of a host variable, you are required to
ensure that graphic data is encoded using the wide character format. This data
will be converted to UCS-2, then sent to the database server. These conversions
will impact performance.
v NOCONVERT option used
The graphic data is assumed by DB2 to be encoded using UCS-2 and is tagged
with the UCS-2 code page, and no conversions are done. DB2 assumes that the
graphic host variable is being used as a bucket. When the NOCONVERT option
is chosen, graphic data retrieved from the database server is passed to the
application encoded using UCS-2. Any conversions from the application code
page to UCS-2 and from UCS-2 to the application code page are your
responsibility. Data tagged as UCS-2 is sent to the database server without any
conversions or alterations.
To minimize conversions you can either use the NOCONVERT option and handle
the conversions in your application, or not use GRAPHIC columns. For the client
environments where wchar_t encoding is in two-byte Unicode, for example
Windows 2000 or AIX version 5.1 and higher, you can use the NOCONVERT
option and work directly with UCS-2. In such cases, your application might handle
the difference between big-endian and little-endian architectures. With the
NOCONVERT option, DB2 database systems use sqldbchar, which is always
two-byte big-endian.
Do not assign IBM eucJP/IBM eucTW CS0 (7-bit ASCII) and IBM eucJP CS2
(Katakana) data to graphic host variables either after conversion to UCS-2 (if
NOCONVERT is specified) or by conversion to the wide character format (if
CONVERT is specified). The reason is that characters in both of these EUC code
sets become single-byte when converted from UCS-2 to PC DBCS.
Chapter 3. Programming

87

In general, although eucJP and eucTW store GRAPHIC data as UCS-2, the
GRAPHIC data in these databases is still non-ASCII eucJP or eucTW data.
Specifically, any space padded to such GRAPHIC data is DBCS space (also known
as ideographic space in UCS-2, U+3000). For a UCS-2 database, however,
GRAPHIC data can contain any UCS-2 character, and space padding is done with
UCS-2 space, U+0020. Keep this difference in mind when you code applications to
retrieve UCS-2 data from a UCS-2 database versus UCS-2 data from eucJP and
eucTW databases.

Binary storage of variable values using the FOR BIT DATA clause
in C and C++ embedded SQL applications
You can declare certain database columns by using the FOR BIT DATA clause.
These columns, which generally contain characters, are used to hold binary
information.
You cannot use the standard C or C++ string type 460 for columns designated FOR
BIT DATA. The database manager truncates this data type when a null character is
encountered. Use either the VARCHAR (SQL type 448) or CLOB (SQL type 408)
structures.

Initialization of host variables in C and C++ embedded SQL

applications
In C and C++ declare sections, you can declare and initialize multiple variables on
a single line. However, you must initialize variables using the "=" symbol, not
parentheses.
The following example shows the correct and incorrect methods of initialization in
a declare section:
EXEC SQL BEGIN DECLARE SECTION;
short my_short_2 = 5;
/* correct
*/
short my_short_1(5);
/* incorrect */
EXEC SQL END DECLARE SECTION;

Macro expansion and the DECLARE SECTION of C and C++

embedded SQL applications
The C or C++ precompiler cannot directly process any C macro that is used in a
declaration within a declare section. You must first preprocess the source file with
an external C preprocessor by specifying the exact command for invoking a C
preprocessor to the precompiler through the PREPROCESSOR option.
When you specify the PREPROCESSOR option, the precompiler first processes all
the SQL INCLUDE statements by incorporating the contents of all the files referred
to in the SQL INCLUDE statement into the source file. The precompiler then
invokes the external C preprocessor using the command you specify with the
modified source file as input. The preprocessed file, which the precompiler always
expects to have an extension of .i, is used as the new source file for the rest of the
precompiling process.
Any #line macro generated by the precompiler no longer references the original
source file, but instead references the preprocessed file. To relate any compiler
errors back to the original source file, retain comments in the preprocessed file.
This helps you to locate various sections of the original source files, including the
header files. The option to retain comments is commonly available in C
preprocessors, and you can include the option in the command you specify
through the PREPROCESSOR option. You must not have the C preprocessor
output any #line macros itself, as they can be incorrectly mixed with ones
generated by the precompiler.

88

Developing Embedded SQL Applications

Notes on using macro expansion:

1. The command you specify through the PREPROCESSOR option must include
all the required options, but not the name of the input file. For example, for
IBM C on AIX you can use the option:
xlC -P -DMYMACRO=1

2. The precompiler expects the command to generate a preprocessed file with a .i

extension. However, you cannot use redirection to generate the preprocessed
file. For example, you cannot use the following option to generate a
preprocessed file:
xlC -E > x.i

3. Any errors the external C preprocessor encounters are reported in a file with a
name corresponding to the original source file, but with a .err extension.
For example, you can use macro expansion in your source code as follows:
#define SIZE 3
EXEC SQL BEGIN DECLARE SECTION;
char a[SIZE+1];
char b[(SIZE+1)*3];
struct
{
short length;
char data[SIZE*6];
} m;
SQL TYPE IS BLOB(SIZE+1) x;
SQL TYPE IS CLOB((SIZE+2)*3) y;
SQL TYPE IS DBCLOB(SIZE*2K) z;
EXEC SQL END DECLARE SECTION;

The previous declarations resolve to the following example after you use the
PREPROCESSOR option:
EXEC SQL BEGIN DECLARE SECTION;
char a[4];
char b[12];
struct
{
short length;
char data[18];
} m;
SQL TYPE IS BLOB(4) x;
SQL TYPE IS CLOB(15) y;
SQL TYPE IS DBCLOB(6144) z;
EXEC SQL END DECLARE SECTION;

Host structure support in the declare section of C and C++

embedded SQL applications
A host structure contains a list of host variables that can be referred to by
embedded SQL statements. With host structure support, the C or C++ precompiler
allows host variables to be grouped into a single host structure.
Host structure support provides a shorthand for referencing that same set of host
variables in an SQL statement.
For example, the following host structure can be used to access some of the
columns in the STAFF table of the SAMPLE database:
struct tag
{
short id;
struct
Chapter 3. Programming

89

{
short length;
char data[10];
} name;
struct
{
short
years;
double salary;
} info;
} staff_record;

The fields of a host structure can be any of the valid host variable types. Valid
types include all numeric, character, and large object types. Nested host structures
are also supported up to 25 levels. In the example shown previously, the field info
is a sub-structure, whereas the field name is not, as it represents a VARCHAR field.
The same principle applies to LONG VARCHAR, VARGRAPHIC and LONG
VARGRAPHIC. Pointer to host structure is also supported.
There are two ways to reference the host variables grouped in a host structure in
an SQL statement:
v The host structure name can be referenced in an SQL statement.
EXEC SQL SELECT id, name, years, salary
INTO :staff_record
FROM staff
WHERE id = 10;

The precompiler converts the reference to staff_record into a list, separated by

commas, of all the fields declared within the host structure. Each field is
qualified with the host structure names of all levels to prevent naming conflicts
with other host variables or fields. This is equivalent to the following method.
v Fully qualified host variable names can be referenced in an SQL statement.
EXEC SQL SELECT id, name, years, salary
INTO :staff_record.id, :staff_record.name,
:staff_record.info.years, :staff_record.info.salary
FROM staff
WHERE id = 10;

References to field names must be fully qualified, even if there are no other host
variables with the same name. Qualified sub-structures can also be referenced. In
the preceding example, :staff_record.info can be used to replace
:staff_record.info.years, :staff_record.info.salary.
Because a reference to a host structure (first example) is equivalent to a
comma-separated list of its fields, there are instances where this type of reference
might lead to an error. For example:
EXEC SQL DELETE FROM :staff_record;

Here, the DELETE statement expects a single character-based host variable. By

giving a host structure instead, the statement results in a precompile-time error:
SQL0087N Host variable "staff_record" is a structure used where structure
references are not permitted.

Other uses of host structures, which can cause an SQL0087N error to occur, include
PREPARE, EXECUTE IMMEDIATE, CALL, indicator variables and SQLDA
references. Host structures with exactly one field are permitted in such situations,
as are references to individual fields (second example).

90

Developing Embedded SQL Applications

Null or truncation indicator variables and indicator tables in C

and C++ embedded SQL applications
For each host variable that can receive null values, you must declare indicator
variables as a short data type.
An indicator table is a collection of indicator variables to be used with a host
structure. An indicator table must be declared as an array of short integers. For
example:
short ind_tab[10];

The preceding example declares an indicator table with 10 elements. It can be used
in an SQL statement as follows:
EXEC SQL SELECT id, name, years, salary
INTO :staff_record INDICATOR :ind_tab
FROM staff
WHERE id = 10;

The following lists each host structure field with its corresponding indicator
variable in the table:
staff_record.id
ind_tab[0]
staff_record.name
ind_tab[1]
staff_record.info.years
ind_tab[2]
staff_record.info.salary
ind_tab[3]
Note: An indicator table element, for example ind_tab[1], cannot be referenced
individually in an SQL statement. The keyword INDICATOR is optional. The
number of structure fields and indicators do not have to match; any extra
indicators are unused, as are extra fields that do not have indicators assigned to
them.
A scalar indicator variable can also be used in the place of an indicator table to
provide an indicator for the first field of the host structure. This is equivalent to
having an indicator table with only one element. For example:
short scalar_ind;
EXEC SQL SELECT id, name, years, salary
INTO :staff_record INDICATOR :scalar_ind
FROM staff
WHERE id = 10;

If an indicator table is specified along with a host variable instead of a host

structure, only the first element of the indicator table, for example ind_tab[0], will
be used:
EXEC SQL SELECT id
INTO :staff_record.id INDICATOR :ind_tab
FROM staff
WHERE id = 10;

If an array of short integers is declared within a host structure:

Chapter 3. Programming

91

struct tag
{
short i[2];
} test_record;

The array will be expanded into its elements when test_record is referenced in an
SQL statement making :test_record equivalent to :test_record.i[0],
:test_record.i[1].

Null terminated strings in C and C++ embedded SQL applications

C and C++ null-terminated strings have their own SQLTYPE (460/461 for character
and 468/469 for graphic).
C and C++ null-terminated strings are handled differently, depending on the value
of the LANGLEVEL precompiler option. If a host variable of one of these
SQLTYPE values and declared length n is specified within an SQL statement, and
the number of bytes (for character types) or double-byte characters (for graphic
types) of data is k, then:
v If the LANGLEVEL option on the PREP command is SAA1 (the default):
For Output:
If...

Then...

k>n

n characters are moved to the target host variable, SQLWARN1

is set to 'W', and SQLCODE 0 (SQLSTATE 01004). No
null-terminator is placed in the string. If an indicator variable
was specified with the host variable, the value of the indicator
variable is set to k.

k=n

k characters are moved to the target host variable, SQLWARN1 is

set to 'N', and SQLCODE 0 (SQLSTATE 01004). No
null-terminator is placed in the string. If an indicator variable
was specified with the host variable, the value of the indicator
variable is set to 0.

k<n

k characters are moved to the target host variable and a null

character is placed in character k + 1. If an indicator variable was
specified with the host variable, the value of the indicator
variable is set to 0.

For input:
When the database manager encounters an input host variable of one of
these SQLTYPE values that does not end with a null-terminator, it will
assume that character n+1 will contain the null-terminator character.
v If the LANGLEVEL option on the PREP command is MIA:
For output:
If...

Then...

k >= n n - 1 characters are moved to the target host variable,

SQLWARN1 is set to 'W', and SQLCODE 0 (SQLSTATE 01501).
The nth character is set to the null-terminator. If an indicator
variable was specified with the host variable, the value of the
indicator variable is set to k.
k+1=n
k characters are moved to the target host variable, and the

92

Developing Embedded SQL Applications

null-terminator is placed in character n. If an indicator variable

was specified with the host variable, the value of the indicator
variable is set to 0.
k+1<n
k characters are moved to the target host variable, n - k -1 blanks
are appended on the right starting at character k + 1, then the
null-terminator is placed in character n. If an indicator variable
was specified with the host variable, the value of the indicator
variable is set to 0.
For input:
When the database manager encounters an input host variable of one of
these SQLTYPE values that does not end with a null character,
SQLCODE -302 (SQLSTATE 22501) is returned.
As previously defined, when specified in any other SQL context, a host variable of
SQLTYPE 460 with length n is treated as a VARCHAR data type with length n and
a host variable of SQLTYPE 468 with length n is treated as a VARGRAPHIC data
type with length n.

Host variables in COBOL

Host variables are COBOL language variables that are referenced within SQL
statements. Host variables allow an application to exchange data with the database
manager.
After the application is precompiled, host variables are used by the compiler as
any other COBOL variable. Follow the rules described in the following sections
when naming, declaring, and using host variables.

Host variable names in COBOL

The SQL precompiler identifies host variables by their declared name.
You must comply with the following rules when declaring host variable names:
v Specify variable names up to 255 characters in length.
v Begin host variable names with prefixes other than SQL, sql, DB2, or db2, which
are reserved for system use.
v FILLER items using the declaration syntaxes are permitted in group host
variable declarations, and will be ignored by the precompiler. However, if you
use FILLER more than once within an SQL DECLARE section, the precompiler
fails. You can not include FILLER items in VARCHAR, LONG VARCHAR,
VARGRAPHIC or LONG VARGRAPHIC declarations.
v You can use hyphens in host variable names.
SQL interprets a hyphen enclosed by spaces as a subtraction operator. Use
hyphens without spaces in host variable names.
v The REDEFINES clause is permitted in host variable declarations.
v Level-88 declarations are permitted in the host variable declare section, but are
ignored.

Declare section for host variables in COBOL embedded SQL

applications
You must use an SQL declare section must be used to identify host variable
declarations. The SQL declare section alerts the precompiler to any host variables
that can be referenced in subsequent SQL statements.

Chapter 3. Programming

93

For example:
EXEC SQL BEGIN DECLARE SECTION END-EXEC.
77 dept
pic s9(4) comp-5.
01 userid
pic x(8).
01 passwd.
EXEC SQL END DECLARE SECTION END-EXEC.

The COBOL precompiler only recognizes a subset of valid COBOL declarations.

Example: SQL declare section template for COBOL embedded

SQL applications
When you are creating an embedded SQL application in COBOL, there is a
template that you can use to declare your host variables and data structures.
The following code is a sample SQL declare section with a host variable declared
for each supported SQL data type.
EXEC
*
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01

SQL BEGIN DECLARE SECTION END-EXEC.

age
PIC S9(4) COMP-5.
/* SQL type 500 */
divis
PIC S9(9) COMP-5.
/* SQL type 496 */
salary
PIC S9(6)V9(3) COMP-3.
/* SQL type 484 */
bonus
USAGE IS COMP-1.
/* SQL type 480 */
wage
USAGE IS COMP-2.
/* SQL type 480 */
nm
PIC X(5).
/* SQL type 452 */
varchar.
49 leng
PIC S9(4) COMP-5.
/* SQL type 448 */
49 strg
PIC X(14).
/* SQL type 448 */
longvchar.
49 len
PIC S9(4) COMP-5.
/* SQL type 456 */
49 str
PIC X(6027).
/* SQL type 456 */
MY-CLOB USAGE IS SQL TYPE IS CLOB(1M).
/* SQL
MY-CLOB-LOCATOR USAGE IS SQL TYPE IS CLOB-LOCATOR.
/* SQL
MY-CLOB-FILE USAGE IS SQL TYPE IS CLOB-FILE.
/* SQL
MY-BLOB USAGE IS SQL TYPE IS BLOB(1M).
/* SQL
MY-BLOB-LOCATOR USAGE IS SQL TYPE IS BLOB-LOCATOR.
/* SQL
MY-BLOB-FILE USAGE IS SQL TYPE IS BLOB-FILE.
/* SQL
MY-DBCLOB USAGE IS SQL TYPE IS DBCLOB(1M).
/* SQL
MY-DBCLOB-LOCATOR USAGE IS SQL TYPE IS DBCLOB-LOCATOR. /* SQL
MY-DBCLOB-FILE USAGE IS SQL TYPE IS DBCLOB-FILE.
/* SQL
MY-PICTURE PIC G(16000) USAGE IS DISPLAY-1.
/* SQL
dt
PIC X(10).
/* SQL type 384 */
tm
PIC X(8).
/* SQL type 388 */
tmstmp
PIC X(26).
/* SQL type 392 */
wage-ind
PIC S9(4) COMP-5.
/* SQL type 464 */

type
type
type
type
type
type
type
type
type
type

408
964
920
404
960
916
412
968
924
464

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

*
EXEC SQL END DECLARE SECTION END-EXEC.

BINARY/COMP-4 data types in COBOL embedded SQL

applications
The DB2 COBOL precompiler supports the use of BINARY, COMP, and COMP-4
data types wherever integer host variables and indicators are permitted.
If you use these data types, you must ensure that the target COBOL compiler
views, or can be made to view, the BINARY, COMP, or COMP-4 data types as
equivalent to the COMP-5 data type.
In the examples provided, such host variables and indicators are shown with the
type COMP-5. Target compilers supported by DB2 that treat COMP, COMP-4,
BINARY COMP and COMP-5 as equivalent are:
v IBM COBOL Set for AIX
v Micro Focus COBOL for AIX

94

Developing Embedded SQL Applications

SQLSTATE and SQLCODE Variables in COBOL embedded SQL

application
To handle errors or debug your embedded SQL application, you should test the
values of the SQLCODE or SQLSTATE variable. You can return these values as
output parameters or as part of a diagnostic message string, or you can insert
these values into a table to provide basic tracing support.
When using the LANGLEVEL precompile option with a value of SQL92E, the
following two declarations can be included as host variables:
EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 SQLSTATE PIC X(5).
01 SQLCODE PIC S9(9) USAGE COMP.
.
.
.
EXEC SQL END DECLARE SECTION END-EXEC.

If neither of these is specified, the SQLCODE declaration is assumed during the

precompile step. The SQLCODE and SQLSTATE variables can be declared using
level 01 (as shown in the previous example) or level 77. Note that when using this
option, the INCLUDE SQLCA statement should not be specified.
For applications made up of multiple source files, the SQLCODE and SQLSTATE
declarations can be included in each source file as shown previously.

Declaration of numeric host variables in COBOL embedded SQL

applications
Numeric host variables that you declare in your embedded COBOL application are
treated as if they were declared in a COBOL program. You can use host variables
to exchange data between the embedded application and the database manager.
The syntax for numeric host variables is:
IS

01
77

variable-name

picture-string

PICTURE
PIC

IS
USAGE



IS

(1)
COMP-3
COMPUTATIONAL-3
COMP-5
COMPUTATIONAL-5

VALUE

value

Notes:
1

An alternative for COMP-3 is PACKED-DECIMAL.

Floating point
(1)

01
77

variable-name
IS

COMPUTATIONAL-1
COMP-1

(2)

USAGE
COMPUTATIONAL-2
COMP-2

Chapter 3. Programming

95



IS
VALUE

value

Notes:
1

REAL (SQLTYPE 480), Length 4

DOUBLE (SQLTYPE 480), Length 8

Numeric host variable considerations:

1. Picture-string must have one of the following forms:
v S9(m)V9(n)
v S9(m)V
v S9(m)
2. Nines can be expanded (for example., "S999" instead of S9(3)")
3. m and n must be positive integers.

Declaration of fixed length and variable length character host

variables in COBOL embedded SQL applications
Fixed-length and variable-length character host variables that you declare in your
embedded COBOL application are treated as if they were declared in a COBOL
program. You can use host variables to exchange data between the embedded
application and the database manager.
The syntax for character host variables is:

Fixed Length
IS

01
77

variable-name

picture-string

PICTURE
PIC



IS
VALUE

value

Variable length


01 variable-name .



IS

49 identifier-1

PICTURE
PIC

S9(4)

IS
USAGE

96

Developing Embedded SQL Applications

COMP-5
COMPUTATIONAL-5

IS
VALUE

value



IS


49 identifier-2

PICTURE
PIC

picture-string



IS
VALUE

value

Character host variable consideration:

1. Picture-string must have the form X(m). Alternatively, X's can be expanded (for
example, "XXX" instead of "X(3)").
2. m is from 1 to 254 for fixed-length strings.
3. m is from 1 to 32 700 for variable-length strings.
4. If m is greater than 32 672, the host variable will be treated as a LONG
VARCHAR string, and its use might be restricted.
5. Use X and 9 as the picture characters in any PICTURE clause. Other characters
are not allowed.
6. Variable-length strings consist of a length item and a value item. You can use
acceptable COBOL names for the length item and the string item. However,
refer to the variable-length string by the collective name in SQL statements.
7. In a CONNECT statement, such as the following example, COBOL character
string host variables dbname and userid will have any trailing blanks removed
before processing:
EXEC SQL CONNECT TO :dbname USER :userid USING :p-word
END-EXEC.

However, because blanks can be significant in passwords, the p-word host

variable should be declared as a VARCHAR data item, so that your application
can explicitly indicate the significant password length for the CONNECT
statement as follows:
EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 dbname PIC X(8).
01 userid PIC X(8).
01 p-word.
49 L PIC S9(4) COMP-5.
49 D PIC X(18).
EXEC SQL END DECLARE SECTION END-EXEC.
PROCEDURE DIVISION.
MOVE "sample" TO dbname.
MOVE "userid" TO userid.
MOVE "password" TO D OF p-word.
MOVE 8
TO L of p-word.
EXEC SQL CONNECT TO :dbname USER :userid USING :p-word
END-EXEC.

Declaration of fixed length and variable length graphic host

variables in COBOL embedded SQL applications
Fixed-length and variable-length graphic host variables that you declare in your
embedded COBOL application are treated as if they were declared in a COBOL
program. You can use host variables to exchange data between the embedded
application and the database manager.
Following is the syntax for graphic host variables.

Chapter 3. Programming

97

Fixed Length
IS

01
77

variable-name

picture-string

PICTURE
PIC

USAGE

IS
DISPLAY-1



IS
VALUE

value

Variable Length


01 variable-name .



IS

49 identifier-1

S9(4)

PICTURE
PIC

IS

COMP-5
COMPUTATIONAL-5



IS
VALUE

value

USAGE

IS

49 identifier-2

picture-string

PICTURE
PIC

USAGE

IS

DISPLAY-1



IS
VALUE

value

Graphic Host Variable Considerations:

1. Picture-string must have the form G(m). Alternatively, G's can be expanded (for
example, "GGG" instead of "G(3)").
2. m is from 1 to 127 for fixed-length strings.
3. m is from 1 to 16 350 for variable-length strings.
4. If m is greater than 16 336, the host variable will be treated as a LONG
VARGRAPHIC string, and its use might be restricted.

Declaration of large object type host variables in COBOL

embedded SQL applications
Large object (LOB) type host variables that you declare in your embedded COBOL
application are treated as if they were declared in a COBOL program. You can use
host variables to exchange data between the embedded application and the
database manager.
The syntax for declaring large object (LOB) host variables in COBOL is:

98

Developing Embedded SQL Applications



01 variable-name

SQL TYPE IS
USAGE
IS

(

length

BLOB
CLOB
DBCLOB



K
M
G

LOB host variable considerations:

1. For BLOB and CLOB 1 <= lob-length <= 2 147 483 647.
2. For DBCLOB 1 <= lob-length <= 1 073 741 823.
3. SQL TYPE IS, BLOB, CLOB, DBCLOB, K, M, G can be in either uppercase,
lowercase, or mixed.
4. Initialization within the LOB declaration is not permitted.
5. The host variable name prefixes LENGTH and DATA in the precompiler
generated code.
BLOB example:
Declaring:
01 MY-BLOB USAGE IS SQL TYPE IS BLOB(2M).

Results in the generation of the following structure:

01 MY-BLOB.
49 MY-BLOB-LENGTH PIC S9(9) COMP-5.
49 MY-BLOB-DATA PIC X(2097152).

CLOB example:
Declaring:
01 MY-CLOB USAGE IS SQL TYPE IS CLOB(125M).

Results in the generation of the following structure:

01 MY-CLOB.
49 MY-CLOB-LENGTH PIC S9(9) COMP-5.
49 MY-CLOB-DATA PIC X(131072000).

DBCLOB example:
Declaring:
01 MY-DBCLOB USAGE IS SQL TYPE IS DBCLOB(30000).

Results in the generation of the following structure:

01 MY-DBCLOB.
49 MY-DBCLOB-LENGTH PIC S9(9) COMP-5.
49 MY-DBCLOB-DATA PIC G(30000) DISPLAY-1.

Declaration of large object locator type host variables in COBOL

embedded SQL applications
Large object (LOB) locator type host variables that you declare in your embedded
COBOL application are treated as if they were declared in a COBOL program. You
can use host variables to exchange data between the embedded application and the
database manager.
Chapter 3. Programming

99

The syntax for declaring large object (LOB) locator host variables in COBOL is:


01 variable-name

SQL TYPE IS
USAGE
IS

BLOB-LOCATOR
CLOB-LOCATOR
DBCLOB-LOCATOR



LOB locator host variable considerations:

1. SQL TYPE IS, BLOB-LOCATOR, CLOB-LOCATOR, DBCLOB-LOCATOR can be
either uppercase, lowercase, or mixed.
2. Initialization of locators is not permitted.
BLOB locator example (other LOB locator types are similar):
Declaring:
01 MY-LOCATOR USAGE SQL TYPE IS BLOB-LOCATOR.

Results in the generation of the following declaration:

01 MY-LOCATOR PIC S9(9) COMP-5.

Declaration of file reference type host variables in COBOL

embedded SQL applications
File reference type host variables that you declare in your embedded COBOL
application are treated as if they were declared in a COBOL program. You can use
host variables to exchange data between the embedded application and the
database manager.
The syntax for declaring file reference host variables in COBOL is:


01 variable-name

SQL TYPE IS
USAGE
IS

BLOB-FILE
CLOB-FILE
DBCLOB-FILE



v SQL TYPE IS, BLOB-FILE, CLOB-FILE, DBCLOB-FILE can be either uppercase,

lowercase, or mixed.
BLOB file reference example (other LOB types are similar):
Declaring:
01 MY-FILE USAGE IS SQL TYPE IS BLOB-FILE.

Results in the generation of the following declaration:

01 MY-FILE.
49 MY-FILE-NAME-LENGTH PIC S9(9) COMP-5.
49 MY-FILE-DATA-LENGTH PIC S9(9) COMP-5.
49 MY-FILE-FILE-OPTIONS PIC S9(9) COMP-5.
49 MY-FILE-NAME PIC X(255).

Grouping data items using REDEFINES in COBOL embedded

SQL applications
You can use the REDEFINES clause when declaring host variables. If you declare a
member of a group data item with the REDEFINES clause, and that group data
item is referred to as a whole in an SQL statement, any subordinate items
containing the REDEFINES clause are not expanded.
For example:

100

Developing Embedded SQL Applications

01 foo1.
10 a pic s9(4) comp-5.
10 a1 redefines a pic x(2).
10 b pic x(10).

Referring to foo1 in an SQL statement as follows:

... INTO :foo1 ...

This statement is equivalent to:

... INTO :foo1.a, :foo1.b ...

That is, the subordinate item a1 that is declared with the REDEFINES clause, is not
automatically expanded out in such situations. If a1 is unambiguous, you can
explicitly refer to a subordinate with a REDEFINES clause in an SQL statement, as
follows:
... INTO :foo1.a1 ...

or
... INTO :a1 ...

Japanese or Traditional Chinese EUC, and UCS-2 considerations

for COBOL embedded SQL applications
Any graphic data that is sent from your application running under an eucJp or
eucTW code set, or connected to a UCS-2 database, is tagged with the UCS-2 code
page identifier. Your application must convert a graphic-character string to UCS-2
before sending it to the database server.
Likewise, graphic data retrieved from a UCS-2 database by any application, or
from any database by an application running under an EUC eucJP or eucTW code
page, is encoded using UCS-2. This requires your application to convert from
UCS-2 to your application code page internally, unless the user is to be presented
with UCS-2 data.
Your application is responsible for converting to and from UCS-2 because this
conversion must be conducted before the data is copied to, and after it is copied
from, the SQLDA. DB2 for Linux, UNIX, and Windows does not supply any
conversion routines that are accessible to your application. Instead, you must use
the system calls available from your operating system. In the case of a UCS-2
database, you might also consider using the VARCHAR and VARGRAPHIC scalar
functions.

Binary storage of variable values using the FOR BIT DATA clause
in COBOL embedded SQL applications
You can declare certain database columns using the FOR BIT DATA clause. These
columns, which generally contain characters, are used to hold binary information.
The CHAR(n), VARCHAR, LONG VARCHAR, and BLOB data types are the
COBOL host variable types that can contain binary data. You must use these data
types when working with columns with the FOR BIT DATA attribute.
Note: The LONG VARCHAR data type is deprecated and might be removed in a
future release.

Chapter 3. Programming

101

Host structure support in the declare section of COBOL

embedded SQL applications
In an application program, a host structure contains a list of host variables that can
be referred to by embedded SQL statements. The COBOL precompiler supports
declarations of group data items in the host variable declare section.
Host structure support provides a shorthand for referring to a set of elementary
data items in an SQL statement. For example, the following group data item can be
used to access some of the columns in the STAFF table of the SAMPLE database:
01 staff-record.
05 staff-id
05 staff-name.
49 l
49 d
05 staff-info.
10 staff-dept
10 staff-job

pic s9(4) comp-5.

pic s9(4) comp-5.
pic x(9).
pic s9(4) comp-5.
pic x(5).

Group data items in the declare section can have any of the valid host variable
types described previously as subordinate data items. This includes all numeric
and character types, as well as all large object types. You can nest group data items
up to 10 levels. Note that you must declare VARCHAR character types with the
subordinate items at level 49, as in the example shown previously. If they are not
at level 49, the VARCHAR is treated as a group data item with two subordinates,
and is subject to the rules of declaring and using group data items. In the previous
example, staff-info is a group data item, whereas staff-name is a VARCHAR.
The same principle applies to LONG VARCHAR, VARGRAPHIC, and LONG
VARGRAPHIC. You may declare group data items at any level between 02 and 49.
You can use group data items and their subordinates in four ways:
Method 1.
The entire group may be referenced as a single host variable in an SQL statement:
EXEC SQL SELECT id, name, dept, job
INTO :staff-record
FROM staff WHERE id = 10 END-EXEC.

The precompiler converts the reference to staff-record into a list, separated by

commas, of all the subordinate items declared within staff-record. Each
elementary item is qualified with the group names of all levels to prevent naming
conflicts with other items. This is equivalent to the following method.
Method 2.
The second way of using group data items:
EXEC SQL SELECT id, name, dept, job
INTO
:staff-record.staff-id,
:staff-record.staff-name,
:staff-record.staff-info.staff-dept,
:staff-record.staff-info.staff-job
FROM staff WHERE id = 10 END-EXEC.

Note: The reference to staff-id is qualified with its group name using the prefix
staff-record., and not staff-id of staff-record as in pure COBOL.

102

Developing Embedded SQL Applications

Assuming there are no other host variables with the same names as the
subordinates of staff-record, the preceding statement can also be coded as in
method 3, eliminating the explicit group qualification.
Method 3.
Here, subordinate items are referenced in a typical COBOL fashion, without being
qualified to their particular group item:
EXEC SQL SELECT id, name, dept, job
INTO
:staff-id,
:staff-name,
:staff-dept,
:staff-job
FROM staff WHERE id = 10 END-EXEC.

As in pure COBOL, this method is acceptable to the precompiler as long as a given

subordinate item can be uniquely identified. If, for example, staff-job occurs in
more than one group, the precompiler issues an error indicating an ambiguous
reference:
SQL0088N Host variable "staff-job" is ambiguous.

Method 4.
To resolve the ambiguous reference, you can use partial qualification of the
subordinate item, for example:
EXEC SQL SELECT id, name, dept, job
INTO
:staff-id,
:staff-name,
:staff-info.staff-dept,
:staff-info.staff-job
FROM staff WHERE id = 10 END-EXEC.

Because a reference to a group item alone, as in method 1, is equivalent to a

comma-separated list of its subordinates, there are instances where this type of
reference leads to an error. For example:
EXEC SQL CONNECT TO :staff-record END-EXEC.

Here, the CONNECT statement expects a single character-based host variable. By

giving the staff-record group data item instead, the host variable results in the
following precompile-time error:
SQL0087N Host variable "staff-record" is a structure used where
structure references are not permitted.

Other uses of group items that cause an SQL0087N to occur include PREPARE,
EXECUTE IMMEDIATE, CALL, indicator variables, and SQLDA references. Groups
with only one subordinate are permitted in such situations, as are references to
individual subordinates, as in methods 2, 3, and 4 shown previously.

Null-indicator variables and null or truncation indicator variable

tables in COBOL embedded SQL applications
You must prepare embedded SQL applications for receiving null values by
associating a null-indicator variable with any host variable that can receive a null
value. A null-indicator variable is shared by both the database manager and the
host application.

Chapter 3. Programming

103

Null-indicator variables in COBOL must be declared as a PIC S9(4) COMP-5 data

type. The COBOL precompiler supports the declaration of null-indicator variable
tables (known as indicator tables), which are convenient to use with group data
items. They are declared as follows:
01 <indicator-table-name>.
05 <indicator-name> pic s9(4) comp-5
occurs <table-size> times.

For example:
01 staff-indicator-table.
05 staff-indicator pic s9(4) comp-5
occurs 7 times.

This indicator table can be used effectively with the first format of group item
reference shown previously:
EXEC SQL SELECT id, name, dept, job
INTO :staff-record :staff-indicator
FROM staff WHERE id = 10 END-EXEC.

Here, the precompiler detects that staff-indicator was declared as an indicator

table, and expands it into individual indicator references when it processes the
SQL statement. staff-indicator(1) is associated with staff-id of staff-record,
staff-indicator(2) is associated with staff-name of staff-record, and so on.
Note: If there are k more indicator entries in the indicator table than there are
subordinates in the data item (for example, if staff-indicator has 10 entries,
making k=6), the k extra entries at the end of the indicator table are ignored.
Likewise, if there are k fewer indicator entries than subordinates, the last k
subordinates in the group item do not have indicators associated with them. Note
that you can refer to individual elements in an indicator table in an SQL statement.

Host variables in FORTRAN

Host variables are FORTRAN language variables that are referenced within SQL
statements. Host variables allow an application to exchange data with the database
manager.
After the application is precompiled, host variables are used by the compiler as
any other FORTRAN variable. Follow the rules described in the following sections
when naming, declaring, and using host variables.

Host variable names in FORTRAN embedded SQL applications

The SQL precompiler identifies host variables by their declared name.
When you declare a host variable name, you must consider the following
restrictions:
v Specify variable names up to 255 characters in length.
v Begin host variable names with prefixes other than SQL, sql, DB2, or db2, which
are reserved for system use.

Declare section for host variables in FORTRAN embedded SQL

applications
You must use an SQL declare section must be used to identify host variable
declarations. The declare section alerts the precompiler to any host variables that
can be referenced in subsequent SQL statements.

104

Developing Embedded SQL Applications

The FORTRAN precompiler only recognizes a subset of valid FORTRAN

declarations as valid host variable declarations. These declarations define either
numeric or character variables. A numeric host variable can be used as an input or
output variable for any numeric SQL input or output value. A character host
variable can be used as an input or output variable for any character, date, time or
timestamp SQL input or output value. The programmer must ensure that output
variables are long enough to contain the values that they will receive.

Example: SQL declare section template for FORTRAN embedded

SQL applications
When you are creating an embedded SQL application in FORTRAN, there is a
template that you can use to declare your host variables and data structures.
The following example is a sample SQL declare section with a host variable
declared for each supported data type:
EXEC SQL BEGIN DECLARE SECTION
INTEGER*2
AGE /26/
INTEGER*4
DEPT
REAL*4
BONUS
REAL*8
SALARY
CHARACTER
MI
CHARACTER*112 ADDRESS
SQL TYPE IS VARCHAR (512) DESCRIPTION
SQL TYPE IS VARCHAR (32000) COMMENTS
SQL TYPE IS CLOB (1M) CHAPTER
SQL TYPE IS CLOB_LOCATOR CHAPLOC
SQL TYPE IS CLOB_FILE CHAPFL
SQL TYPE IS BLOB (1M) VIDEO
SQL TYPE IS BLOB_LOCATOR VIDLOC
SQL TYPE IS BLOB_FILE VIDFL
CHARACTER*10 DATE
CHARACTER*8 TIME
CHARACTER*26 TIMESTAMP
INTEGER*2
WAGE_IND
EXEC SQL END DECLARE SECTION

/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type
/* SQL type

500 */
496 */
480 */
480 */
452 */
452 */
448 */
448 */
408 */
964 */
920 */
404 */
960 */
916 */
384 */
388 */
392 */
500 */

SQLSTATE and SQLCODE variables in FORTRAN embedded SQL

application
To handle errors or debug your embedded SQL application, you should test the
values of the SQLCODE or SQLSTATE variable. You can return these values as
output parameters or as part of a diagnostic message string, or you can insert
these values into a table to provide basic tracing support.
When using the LANGLEVEL precompile option with a value of SQL92E, the
following two declarations can be included as host variables:
EXEC SQL BEGIN DECLARE SECTION;
CHARACTER*5 SQLSTATE
INTEGER
SQLCOD
.
.
.
EXEC SQL END DECLARE SECTION

The SQLCOD declaration is assumed during the precompile step. The variable named
SQLSTATE can also be SQLSTA. Note that when using this option, the INCLUDE
SQLCA statement should not be specified.
For applications that contain multiple source files, the declarations of SQLCOD and
SQLSTATE can be included in each source file, as shown previously.

Chapter 3. Programming

105

Declaration of numeric host variables in FORTRAN embedded

SQL applications
Numeric host variables that you declare in your embedded FORTRAN application
are treated as if they were declared in a FORTRAN program. Host variables allow
you to exchange data between the embedded application and the database
manager.
The following illustrates the syntax for numeric host variables in FORTRAN.
,

 varname

INTEGER*2
INTEGER*4
REAL*4
REAL *8
DOUBLE PRECISION


/ initial-value /

Numeric host variable considerations:

1. REAL*8 and DOUBLE PRECISION are equivalent.
2. Use an E rather than a D as the exponent indicator for REAL*8 constants.

Declaration of fixed-length and variable length character host

variables in FORTRAN embedded SQL applications
You must declare character host variables when you program an embedded SQL
application in FORTRAN. Host variables are treated like FORTRAN variables, and
allow for the exchange of data between the embedded application and the
database manager.
The syntax for fixed-length character host variables is:

Fixed length
Syntax for character host variables in FORTRAN: fixed length
,
 varname

CHARACTER
*n


/ initial-value /

Following is the syntax for variable-length character host variables.

Variable length
,


SQL TYPE IS VARCHAR (length)

 varname



Character host variable considerations:

1. *n has a maximum value of 254.
2. When length is between 1 and 32 672 inclusive, the host variable has type
VARCHAR(SQLTYPE 448).
3. When length is between 32 673 and 32 700 inclusive, the host variable has type
LONG VARCHAR(SQLTYPE 456).

106

Developing Embedded SQL Applications

4. Initialization of VARCHAR and LONG VARCHAR host variables is not

permitted within the declaration.

VARCHAR example:
Declaring:
sql type is varchar(1000) my_varchar

Results in the generation of the following structure:

character
integer*2
character
equivalence(

my_varchar(1000+2)
my_varchar_length
my_varchar_data(1000)
my_varchar(1),
+
my_varchar_length )
equivalence( my_varchar(3),
+
my_varchar_data )

The application can manipulate both my_varchar_length and my_varchar_data; for

example, to set or examine the contents of the host variable. The base name (in this
case, my_varchar), is used in SQL statements to refer to the VARCHAR as a whole.

LONG VARCHAR example:

Declaring:
sql type is varchar(10000) my_lvarchar

Results in the generation of the following structure:

character
integer*2
character
equivalence(

my_lvarchar(10000+2)
my_lvarchar_length
my_lvarchar_data(10000)
my_lvarchar(1),
+
my_lvarchar_length )
equivalence( my_lvarchar(3),
+
my_lvarchar_data )

The application can manipulate both my_lvarchar_length and my_lvarchar_data;

for example, to set or examine the contents of the host variable. The base name (in
this case, my_lvarchar), is used in SQL statements to refer to the LONG VARCHAR
as a whole.
Note: In a CONNECT statement, such as in the following example, the FORTRAN
character string host variables dbname and userid will have any trailing blanks
removed before processing.
EXEC SQL CONNECT TO :dbname USER :userid USING :passwd

However, because blanks can be significant in passwords, you should declare host
variables for passwords as VARCHAR, and have the length field set to reflect the
actual password length:
EXEC SQL BEGIN DECLARE SECTION
character*8 dbname, userid
sql type is varchar(18) passwd
EXEC SQL END DECLARE SECTION
character*18 passwd_string
equivalence(passwd_data,passwd_string)
dbname = sample
userid = userid
passwd_length= 8
passwd_string = password
EXEC SQL CONNECT TO :dbname USER :userid USING :passwd
Chapter 3. Programming

107

Declaration of large object type host variables in FORTRAN

embedded SQL applications
Large object (LOB) host variables that you declare in your embedded FORTRAN
application are treated as if they were declared in a FORTRAN program. Host
variables allow you to exchange data between the embedded application and the
database manager.
The syntax for declaring large object (LOB) host variables in FORTRAN is:
,


SQL TYPE IS

BLOB
CLOB

)  variable-name

length



K
M
G

LOB host variable considerations:

1. GRAPHIC types are not supported in FORTRAN.
2. SQL TYPE IS, BLOB, CLOB, K, M, G can be in either uppercase, lowercase, or
mixed.
3. For BLOB and CLOB 1 <= lob-length <= 2 147 483 647.
4. The initialization of a LOB within a LOB declaration is not permitted.
5. The host variable name prefixes 'length' and 'data' in the precompiler generated
code.

BLOB example:
Declaring:
sql type is blob(2m) my_blob

Results in the generation of the following structure:

character
integer*4
character
equivalence(

my_blob(2097152+4)
my_blob_length
my_blob_data(2097152)
my_blob(1),
+
my_blob_length )
equivalence( my_blob(5),
+
my_blob_data )

CLOB example:
Declaring:
sql type is clob(125m) my_clob

Results in the generation of the following structure:

character
integer*4
character
equivalence(

my_clob(131072000+4)
my_clob_length
my_clob_data(131072000)
my_clob(1),
+
my_clob_length )
equivalence( my_clob(5),
+
my_clob_data )

108

Developing Embedded SQL Applications

Declaration of large object locator type host variables in

FORTRAN embedded SQL applications
Large Object (LOB) locator type host variables that you declare in your embedded
FORTRAN application are treated as if they were declared in a FORTRAN
program. Host variables allow you to exchange data between the embedded
application and the database manager.
The syntax for declaring large object (LOB) locator host variables in FORTRAN is:
,


SQL TYPE IS

 variable-name

BLOB_LOCATOR
CLOB_LOCATOR



LOB locator host variable considerations:

1. GRAPHIC types are not supported in FORTRAN.
2. SQL TYPE IS, BLOB_LOCATOR, CLOB_LOCATOR can be either uppercase,
lowercase, or mixed.
3. Initialization of locators is not permitted.
CLOB locator example (BLOB locator is similar):
Declaring:
SQL TYPE IS CLOB_LOCATOR my_locator

Results in the generation of the following declaration:

integer*4 my_locator

Declaration of file reference type host variables in FORTRAN

embedded SQL applications
File reference type host variables that you declare in your embedded FORTRAN
application are treated as if they were declared in a FORTRAN program. Host
variables allow you to exchange data between the embedded application and the
database manager.
The syntax for declaring file reference host variables in FORTRAN is:
,


SQL TYPE IS

BLOB_FILE
CLOB_FILE

 variable-name



File reference host variable considerations:

1. Graphic types are not supported in FORTRAN.
2. SQL TYPE IS, BLOB_FILE, CLOB_FILE can be either uppercase, lowercase, or
mixed.
Example of a BLOB file reference variable (CLOB file reference variable is
similar):
SQL TYPE IS BLOB_FILE my_file

Results in the generation of the following declaration:

Chapter 3. Programming

109

character
integer*4
integer*4
integer*4
character*255
equivalence(

my_file(267)
my_file_name_length
my_file_data_length
my_file_file_options
my_file_name
my_file(1),
+
my_file_name_length )
equivalence( my_file(5),
+
my_file_data_length )
equivalence( my_file(9),
+
my_file_file_options )
equivalence( my_file(13),
+
my_file_name )

Considerations for graphic (multi-byte) character sets in

FORTRAN embedded SQL applications
Graphic (multi-byte) host variable data types are not supported in FORTRAN.
Only mixed-character host variables are supported through the character data
type. However, it is possible to create a user SQL descriptor area (SQLDA) that
contains graphic data.

Japanese or Traditional Chinese EUC, and UCS-2 considerations

for FORTRAN embedded SQL applications
Any graphic data sent from your application running under an eucJp or eucTW
code set, or connected to a UCS-2 database, is tagged with the UCS-2 code page
identifier. Your application must convert a graphic-character string to UCS-2 before
sending it to a the database server.
Likewise, graphic data retrieved from a UCS-2 database by any application, or
from any database by an application running under an EUC eucJP or eucTW code
page, is encoded using UCS-2. This requires your application to convert from
UCS-2 to your application code page internally, unless the user is to be presented
with UCS-2 data.
Your application is responsible for converting to and from UCS-2 because this
conversion must be conducted before the data is copied to, and after it is copied
from, the SQLDA. DB2 database systems do not supply any conversion routines
that are accessible to your application. Instead, you must use the system calls
available from your operating system. In the case of a UCS-2 database, you can
also consider using the VARCHAR and VARGRAPHIC scalar functions.

Null or truncation indicator variables in FORTRAN embedded

SQL applications
You must declare indicator variables as INTEGER*2 data types.

Host variables in REXX

Host variables are REXX language variables that are referenced within SQL
statements. Host variables allow an application to exchange data with the database
manager. After an application is precompiled, host variables are used by the
compiler as any other REXX variable.
Follow the rules described in the following sections when naming, declaring, and
using host variables.

110

Developing Embedded SQL Applications

Host variable names in REXX embedded SQL applications

You can use any properly named REXX variable as a host variable. A variable
name can be up to 64 characters long and cannot end with a period. A host
variable name can consist of numbers, alphabetic characters, and the characters @,
_, !, ., ?, and $.

Host variable references in REXX embedded SQL applications

The REXX interpreter examines every string without quotation marks in a
procedure. If the string represents a variable in the current REXX variable pool,
REXX replaces the string with the current value.
The following example is how you can reference a host variable in REXX:
CALL SQLEXEC FETCH C1 INTO :cm
SAY Commission = cm

To ensure that a character string is not converted to a numeric data type, enclose
the string with single quotation marks as in the following example:
VAR = 100

REXX sets the variable VAR to the 3 byte character string 100. If single quotation
marks are to be included as part of the string, follow this example:
VAR = "100"

When inserting numeric data into a CHARACTER field, the REXX interpreter
treats numeric data as integer data, thus you must concatenate numeric strings
explicitly and surround them with single quotation marks.

Predefined REXX Variables

The SQLEXEC function and the SQLDBS and SQLDB2 routines set predefined
REXX variables as a result of certain operations.
Predefined REXX variables include:
RESULT
Each operation sets this return code. Possible values are:
n

Where n is a positive value indicating the number of bytes in a

formatted message. The GET ERROR MESSAGE API alone returns
this value.

The API was executed. The REXX variable SQLCA contains the
completion status of the API. If SQLCA.SQLCODE is not zero,
SQLMSG contains the text message associated with that value.

-1

There is not enough memory available to complete the API. The

requested message was not returned.

-2

SQLCA.SQLCODE is set to 0. No message was returned.

-3

SQLCA.SQLCODE contained an invalid SQLCODE. No message

was returned.

-6

The SQLCA REXX variable could not be built. This indicates that
there was not enough memory available or the REXX variable pool
was unavailable for some reason.

-7

The SQLMSG REXX variable could not be built. This indicates that
there was not enough memory available or the REXX variable pool
was unavailable for some reason.
Chapter 3. Programming

111

-8

The SQLCA.SQLCODE REXX variable could not be fetched from

the REXX variable pool.

-9

The SQLCA.SQLCODE REXX variable was truncated during the

fetch. The maximum length for this variable is 5 bytes.

-10

The SQLCA.SQLCODE REXX variable could not be converted from

ASCII to a valid long integer.

-11

The SQLCA.SQLERRML REXX variable could not be fetched from

the REXX variable pool.

-12

The SQLCA.SQLERRML REXX variable was truncated during the

fetch. The maximum length for this variable is 2 bytes.

-13

The SQLCA.SQLERRML REXX variable could not be converted

from ASCII to a valid short integer.

-14

The SQLCA.SQLERRMC REXX variable could not be fetched from

the REXX variable pool.

-15

The SQLCA.SQLERRMC REXX variable was truncated during the

fetch. The maximum length for this variable is 70 bytes.

-16

The REXX variable specified for the error text could not be set.

-17

The SQLCA.SQLSTATE REXX variable could not be fetched from

the REXX variable pool.

-18

The SQLCA.SQLSTATE REXX variable was truncated during the

fetch. The maximum length for this variable is 2 bytes.

Note: The values -8 through -18 are returned only by the GET ERROR
MESSAGE API.
SQLMSG
If SQLCA.SQLCODE is not 0, this variable contains the text message
associated with the error code.
SQLISL
The isolation level. Possible values are:
RR
Repeatable read.
RS
Read stability.
CS
Cursor stability. This is the default.
UR
Uncommitted read.
NC
No commit. (NC is only supported by some host or System i
servers.)
SQLCA
The SQLCA structure updated after SQL statements are processed and DB2
APIs are called.
SQLRODA
The input/output SQLDA structure for stored procedures invoked using
the CALL statement. It is also the output SQLDA structure for stored
procedures invoked using the Database Application Remote Interface
(DARI) API.
SQLRIDA
The input SQLDA structure for stored procedures invoked using the
Database Application Remote Interface (DARI) API.

112

Developing Embedded SQL Applications

SQLRDAT
An SQLCHAR structure for server procedures invoked using the Database
Application Remote Interface (DARI) API.

Considerations while programming REXX embedded SQL

applications
REXX is an interpreted language, which means that no precompiler, compiler, or
linker is used. Instead, three DB2 APIs are used to create DB2 applications in
REXX. You can use these APIs to access different DB2 elements.

About this task

The three APIs that are available for creating embedded SQL applications in REXX
are:
SQLEXEC
Supports the SQL language.
SQLDBS
Supports command-like versions of DB2 APIs.
SQLDB2
Supports a REXX specific interface to the command-line processor. See the
description of the API syntax for REXX for details and restrictions on how
this interface can be used.
Before using any of the DB2 APIs or issuing SQL statements in an application, you
must register the SQLDBS, SQLDB2 and SQLEXEC routines. This notifies the REXX
interpreter of the REXX/SQL entry points. The method you use for registering
varies slightly between Windows-based and AIX platforms.
Use the following examples for correct syntax for registering each routine:
Sample registration on Windows operating systems
/* ------------ Register SQLDBS with REXX -------------------------*/
If Rxfuncquery(SQLDBS) <> 0 then
rcy = Rxfuncadd(SQLDBS,DB2AR,SQLDBS)
If rcy \= 0 then
do
say SQLDBS was not successfully added to the REXX environment
signal rxx_exit
end
/* ------------ Register SQLDB2 with REXX -------------------------*/
If Rxfuncquery(SQLDB2) <> 0 then
rcy = Rxfuncadd(SQLDB2,DB2AR,SQLDB2)
If rcy \= 0 then
do
say SQLDB2 was not successfully added to the REXX environment
signal rxx_exit
end
/* ----------------- Register SQLEXEC with REXX --------------------*/
If Rxfuncquery(SQLEXEC) <> 0 then
rcy = Rxfuncadd(SQLEXEC,DB2AR,SQLEXEC)
If rcy \= 0 then
do
say SQLEXEC was not successfully added to the REXX environment
signal rxx_exit
end

Sample registration on AIX

Chapter 3. Programming

113

/* ------------ Register SQLDBS, SQLDB2 and SQLEXEC with REXX --------*/

rcy = SysAddFuncPkg("db2rexx")
If rcy \= 0 then
do
say db2rexx was not successfully added to the REXX environment
signal rxx_exit
end

On Windows-based platforms, the RxFuncAdd commands need to be executed

only once for all sessions.
On AIX, the SysAddFuncPkg should be executed in every REXX/SQL application.
Details on the Rxfuncadd and SysAddFuncPkg APIs are available in the REXX
documentation for Windows-based platforms and AIX.
It is possible that tokens within statements or commands that are passed to the
SQLEXEC, SQLDBS, and SQLDB2 routines could correspond to REXX variables. In
this case, the REXX interpreter substitutes the variable's value before calling
SQLEXEC, SQLDBS, or SQLDB2.
To avoid this situation, enclose statement strings in quotation marks (' ' or " "). If
you do not use quotation marks, any conflicting variable names are resolved by
the REXX interpreter, instead of being passed to the SQLEXEC, SQLDBS or
SQLDB2 routines.

Declaration of large object type host variables in REXX

embedded SQL applications
When you fetch a LOB column into a REXX host variable, it is stored as an
uncounted string. LOB columns are handled in the same manner as other
character-based SQL types such as CHAR, VARCHAR, GRAPHIC, and LONG.
On input, if the size of the contents of your host variable is larger than 32K, or if it
meets other criteria set out listed in the following table, it will be assigned the
appropriate LOB type.
In REXX SQL, LOB types are determined from the string content of your host
variable as follows:
Host variable string content

Resulting LOB type

CLOB

:hv1='ordinary quoted string longer than 32K ...'

CLOB
:hv2="'string with embedded delimiting quotation marks ",
"longer than 32K...'"
DBCLOB
:hv3="G'DBCS string with embedded delimiting single ",
"quotation marks, beginning with G, longer than 32K...'"
BLOB
:hv4="BIN'string with embedded delimiting single ",
"quotation marks, beginning with BIN, any length...'"

114

Developing Embedded SQL Applications

Declaration of large object locator type host variables in REXX

embedded SQL applications
You must declare LOB locator host variables in your application. When a REXX
embedded SQL application encounters these declarations the host variables are
treated as locators for the remainder of the program. Locator values are stored in
REXX variables in an internal format.
The syntax for declaring LOB locator host variables in REXX is:
,


DECLARE  :

variable-name

LANGUAGE TYPE

BLOB
CLOB
DBCLOB

LOCATOR



Example:
CALL SQLEXEC DECLARE :hv1, :hv2 LANGUAGE TYPE CLOB LOCATOR

Data represented by LOB locators returned from the engine can be freed in
REXX/SQL using the FREE LOCATOR statement which has the following format:
Syntax for FREE LOCATOR statement
,


FREE

LOCATOR

 :

variable-name



Example:
CALL SQLEXEC FREE LOCATOR :hv1, :hv2

Declaration of file reference type host variables in REXX

embedded SQL applications
You must declare LOB file reference host variables in your application. When
REXX embedded SQL encounters these declarations, it treats the declared host
variables as LOB file references for the remainder of the program.
The syntax for declaring LOB file reference host variables in REXX is:
,


DECLARE  :

variable-name

LANGUAGE TYPE

BLOB
CLOB
DBCLOB

FILE



Example:
CALL SQLEXEC DECLARE :hv3, :hv4 LANGUAGE TYPE CLOB FILE

File reference variables in REXX contain three fields. For the preceding example
they are:
hv3.FILE_OPTIONS.
Set by the application to indicate how the file will be used.
hv3.DATA_LENGTH.
Set by DB2 to indicate the size of the file.
Chapter 3. Programming

115

hv3.NAME.
Set by the application to the name of the LOB file.
For FILE_OPTIONS, the application sets the following keywords:
Keyword (integer value)
Meaning
READ (2)
File is to be used for input. This is a regular file that can be opened, read
and closed. The length of the data in the file (in bytes) is computed (by the
application requester code) upon opening the file.
CREATE (8)
On output, create a new file. If the file already exists, it is an error. The
length (in bytes) of the file is returned in the DATA_LENGTH field of the file
reference variable structure.
OVERWRITE (16)
On output, the existing file is overwritten if it exists, otherwise a new file
is created. The length (in bytes) of the file is returned in the DATA_LENGTH
field of the file reference variable structure.
APPEND (32)
The output is appended to the file if it exists, otherwise a new file is
created. The length (in bytes) of the data that was added to the file (not the
total file length) is returned in the DATA_LENGTH field of the file reference
variable structure.
Note: A file reference host variable is a compound variable in REXX, thus you
must set values for the NAME, NAME_LENGTH and FILE_OPTIONS fields in addition to
declaring them.

LOB Host Variable Clearing in REXX embedded SQL applications

On Windows operating systems, it might be necessary to explicitly clear REXX
SQL LOB locator and file reference host variable declarations as they remain in
effect after your application program ends. This occurs because the application
process does not exit until the session in which it is run is closed.
If REXX SQL LOB declarations are not cleared, they can interfere with other
applications that are running in the same session after a LOB application has been
executed.
The syntax to clear the declaration is:
CALL SQLEXEC "CLEAR SQL VARIABLE DECLARATIONS"

You should include this statement at the end of LOB applications. Note that you
can include it anywhere as a precautionary measure to clear declarations which
might have been left by previous applications, such as at the beginning of a REXX
SQL application.

Null or truncation indicator variables in REXX embedded SQL

applications
An indicator variable data type in REXX is a number without a decimal point.
The following is an example of an indicator variable in REXX using the
INDICATOR keyword.

116

Developing Embedded SQL Applications

CALL SQLEXEC FETCH C1 INTO :cm INDICATOR :cmind

IF ( cmind < 0 )
SAY Commission is NULL

In the previous example, cmind is examined for a negative value. If it is not

negative, the application can use the returned value of cm. If it is negative, the
fetched value is NULL and cm must not be used. The database manager does not
change the value of the host variable in this case.

Executing XQuery expressions in embedded SQL applications

You can store XML data in your tables and use embedded SQL applications to
access the XML columns by using XQuery expressions.

Before you begin

To access XML data, use XML host variables instead of casting the data to
character or binary data types. If you do not make use of XML host variables, the
best alternative for accessing XML data is with FOR BIT DATA or BLOB data types
to avoid code page conversion.
v Declare XML host variables within your embedded SQL applications.

About this task

v An XML type must be used to retrieve XML values in a static SQL SELECT INTO
statement.
v If a CHAR, VARCHAR, CLOB, or BLOB host variable is used for input where an
XML value is expected, the value will be subject to an XMLPARSE function
operation with default white space (STRIP) handling. Otherwise, an XML host
variable is required.
To issue XQuery expressions in embedded SQL application directly, prepend the
expression with the "XQUERY" keyword. For static SQL use the XMLQUERY
function. When the XMLQUERY function is called, the XQuery expression is not
prefixed by "XQUERY".
These examples return data from the XML documents in table CUSTOMER from
the sample database.
Example 1: Executing XQuery expressions directly in C and C++ dynamic SQL
by prepending the "XQUERY" keyword
In C and C++ applications, XQuery expressions can be issued in the
following way:
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
char stmt[16384];
SQL TYPE IS XML AS BLOB( 10K ) xmlblob;
EXEC SQL END DECLARE SECTION;
sprintf( stmt, "XQUERY (for $a in db2-fn:xmlcolumn("CUSTOMER.INFO")
/*:customerinfo[*:addr/*:city = "Toronto"]/@Cid return data($a))");
EXEC SQL PREPARE s1 FROM :stmt;
EXEC SQL DECLARE c1 CURSOR FOR s1;
EXEC SQL OPEN c1;
while( sqlca.sqlcode == SQL_RC_OK )
{
EXEC SQL FETCH c1 INTO :xmlblob;
/* Display results */
}
EXEC SQL CLOSE c1;
EXEC SQL COMMIT;

Chapter 3. Programming

117

Example 2: Executing XQuery expressions in static SQL using the XMLQUERY

function and XMLEXISTS predicate
SQL statements containing the XMLQUERY function can be prepared
statically, as follows:
EXEC SQL INCLUDE SQLCA;
EXEC SQL BEGIN DECLARE SECTION;
SQL TYPE IS XML AS BLOB( 10K ) xmlblob;
EXEC SQL END DECLARE SECTION;
EXEC SQL DECLARE C1 CURSOR FOR SELECT XMLQUERY(data($INFO/*:customerinfo/@Cid))
FROM customer
WHERE XMLEXISTS($INFO/*:customerinfo[*:addr/*:city = "Toronto"]);
EXEC SQL OPEN c1;
while( sqlca.sqlcode == SQL_RC_OK )
{
EXEC SQL FETCH c1 INTO :xmlblob;
/* Display results */
}
EXEC SQL CLOSE c1;
EXEC SQL COMMIT;

Example 3: Executing XQuery expressions in COBOL embedded SQL

applications
In COBOL applications, XQuery expressions can be issued in the following
way:
EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 stmt pic x(80).
01 xmlBuff USAGE IS SQL TYPE IS XML AS BLOB (10K).
EXEC SQL END DECLARE SECTION END-EXEC.
MOVE "XQUERY (for $a in db2-fn:xmlcolumn("CUSTOMER.INFO")/*:customerinfo
[*:addr/*:city = "Toronto"]/@Cid return data($a)))" TO stmt.
EXEC SQL PREPARE s1 FROM :stmt END-EXEC.
EXEC SQL DECLARE c1 CURSOR FOR s1 END-EXEC.
EXEC SQL OPEN c1 USING :host-var END-EXEC.
*Call the FETCH and UPDATE loop.
Perform Fetch-Loop through End-Fetch-Loop
until SQLCODE does not equal 0.
EXEC SQL CLOSE c1 END-EXEC.
EXEC SQL COMMIT END-EXEC.
Fetch-Loop Section.
EXEC SQL FETCH c1 INTO :xmlBuff END-EXEC.
if SQLCODE not equal 0
go to End-Fetch-Loop.
* Display results
End-Fetch-Loop. exit.

Executing SQL statements in embedded SQL applications

The way you execute SQL statements in embedded SQL applications depends on if
the statement is statically or dynamically executed. However, you must use the
EXEC SQL command regardless of the type of statement that you use.
Static statements are hard-coded into the source code of an embedded SQL
application. Dynamic statements are different from static in that they are compiled
at run time and can be prepared with input parameters. Information that is read
can be stored in a medium called a cursor, which then allows for users to freely
scroll through the data and make suitable updates. Error information from the
SQLCODE, SQLSTATE, and SQLWARN are a useful tool toward assisting in
troubleshooting an application.

Comments in embedded SQL applications

The comments in any application are important for making the application code
understandable.

118

Developing Embedded SQL Applications

Comments in C and C++ embedded SQL applications

When working with C and C++ applications, SQL comments can be inserted
within the EXEC SQL block. For example:
/* Only C or C++ comments allowed here */
EXEC SQL
-- SQL comments or
/* C comments or */
// C++ comments allowed here
DECLARE C1 CURSOR FOR sname;
/* Only C or C++ comments allowed here */

Comments in COBOL embedded SQL applications

When working with COBOL applications, SQL comments can be inserted within
the EXEC SQL block. For example:
*
*
*
*

See COBOL documentation for comment rules

Only COBOL comments are allowed here
EXEC SQL
-- SQL comments or
full-line COBOL comments are allowed here
DECLARE C1 CURSOR FOR sname END-EXEC.
Only COBOL comments are allowed here

Comments in FORTRAN embedded SQL applications

When working with FORTRAN applications, SQL comments can be inserted within
the EXEC SQL block. For example:
C
C
C

Only FORTRAN comments are allowed here

EXEC SQL
+ -- SQL comments, and
full-line FORTRAN comment are allowed here
+ DECLARE C1 CURSOR FOR sname
I=7 ! End of line FORTRAN comments allowed here
Only FORTRAN comments are allowed here

Comments in REXX embedded SQL applications

SQL comments are not supported in REXX applications.

Executing static SQL statements in embedded SQL

applications
You cannot modify static SQL statements at run time. You can use static SQL
statements for tasks such as initialization and cleanup.
SQL statements can be executed statically in a host language using the following
approach:
v C or C++ (tbmod.sqc/tbmod.sqC)
The following three examples are from the tbmod sample. See this sample for a
complete program that shows how to modify table data in C or C++.
The following example shows how to insert table data:
EXEC SQL INSERT INTO staff(id, name, dept, job, salary)
VALUES(380, Pearce, 38, Clerk, 13217.50),
(390, Hachey, 38, Mgr, 21270.00),
(400, Wagland, 38, Clerk, 14575.00);

The following example shows how to update table data:

Chapter 3. Programming

119

EXEC SQL UPDATE staff

SET salary = salary + 10000
WHERE id >= 310 AND dept = 84;

The following example shows how to delete from a table:

EXEC SQL DELETE
FROM staff
WHERE id >= 310 AND salary > 20000 AND job != Sales;

v COBOL (updat.sqb)
The following three examples are from the updat sample. See this sample for a
complete program that shows how to modify table data in COBOL.
The following example shows how to insert table data:
EXEC SQL INSERT INTO staff
VALUES (999, Testing, 99, :job-update, 0, 0, 0)
END-EXEC.

The following example shows how to update table data where job-update is a
reference to a host variable declared in the declaration section of the source
code:
EXEC SQL UPDATE staff
SET job=:job-update
WHERE job=Mgr
END-EXEC.

The following example shows how to delete from a table:

EXEC SQL DELETE
FROM staff
WHERE job=:job-update
END-EXEC.

Retrieving host variable information from the SQLDA structure

in embedded SQL applications
With static SQL, host variables used in embedded SQL statements are known at
application compile time.
With dynamic SQL, the embedded SQL statements and consequently the host
variables are not known until application run time. Therefore, for dynamic SQL
applications, you must preprocess the list of host variables that are used in your
application.
You can use the DESCRIBE statement to obtain host variable information for any
SELECT statement that has been prepared (using PREPARE), and store that
information into the SQL descriptor area (SQLDA).
When the DESCRIBE statement gets executed in your application, the database
manager defines your host variables in an SQLDA. Once the host variables are
defined in the SQLDA, you can use the FETCH statement to assign values to the
host variables, using a cursor.

Declaring the SQLDA structure in a dynamically executed SQL

program
An SQLDA contains a variable number of occurrences of SQLVAR entries, each of
which contains a set of fields that describe one column in a row of data. There are
two types of SQLVAR entries: base SQLVAR entries and secondary SQLVAR
entries.

120

Developing Embedded SQL Applications

About this task

The following diagram describes the structure of the SQLDA.

sqldaid CHAR

sqldabc INTEGER

sqln SMALLINT

sqld SMALLINT

HEADER

sqltype SMALLINT sqllen SMALLINT

SQLVAR
(1 per field)

sqldata POINTER

sqlind POINTER

sqlname VARCHAR (30)

Other SQLVAR Entries

Figure 2. The SQL Descriptor Area (SQLDA)

Because the number of SQLVAR entries required depends on the number of

columns in the result table, an application must be able to allocate an appropriate
number of SQLVAR elements when needed. Use one of the following methods:

Procedure
v Provide the largest SQLDA (that is, the one with the greatest number of
SQLVAR entries) that is needed. The maximum number of columns that can be
returned in a result table is 255. If any of the columns being returned is either a
LOB type or a distinct type, the value in SQLN is doubled, and the number of
SQLVAR entries needed to hold the information is doubled to 510. However, as
most SELECT statements do not even retrieve 255 columns, most of the allocated
space is unused.
v Provide a smaller SQLDA with fewer SQLVAR entries. In this case, if there are
more columns in the result than SQLVAR entries allowed for in the SQLDA, no
descriptions are returned. Instead, the database manager returns the number of
select list items detected in the SELECT statement. The application allocates an
SQLDA with the required number of SQLVAR entries, then uses the DESCRIBE
statement to acquire the column descriptions.
v When any of the columns returned has a LOB or user defined type, provide an
SQLDA with the exact number of SQLVAR entries.

What to do next
For all three methods, the question arises as to how many initial SQLVAR entries
you should allocate. Each SQLVAR element uses up 44 bytes of storage (not
counting storage allocated for the SQLDATA and SQLIND fields). If memory is
plentiful, the first method of providing an SQLDA of maximum size is easier to
implement.
The second method of allocating a smaller SQLDA is only applicable to
programming languages such as C and C++ that support the dynamic allocation of
Chapter 3. Programming

121

memory. For languages such as COBOL and FORTRAN that do not support the
dynamic allocation of memory, use the first method.

Preparing a dynamically executed SQL statement using the

minimum SQLDA structure
Use the information provided here as an example of how to allocate the minimum
SQLDA structure for a statement.

About this task

You can only allocate a smaller SQLDA structure with programming languages,
such as C and C++, that support the dynamic allocation of memory.
Suppose an application declares an SQLDA structure named minsqlda that contains
no SQLVAR entries. The SQLN field of the SQLDA describes the number of
SQLVAR entries that are allocated. In this case, SQLN must be set to 0. Next, to
prepare a statement from the character string dstring and to enter its description
into minsqlda, issue the following SQL statement (assuming C syntax, and
assuming that minsqlda is declared as a pointer to an SQLDA structure):
EXEC SQL
PREPARE STMT INTO :*minsqlda FROM :dstring;

Suppose that the statement contained in dstring is a SELECT statement that

returns 20 columns in each row. After the PREPARE statement (or a DESCRIBE
statement), the SQLD field of the SQLDA contains the number of columns of the
result table for the prepared SELECT statement.
The SQLVAR entries in the SQLDA are set in the following cases:
v SQLN >= SQLD and no column is either a LOB or a distinct type.
The first SQLD SQLVAR entries are set and SQLDOUBLED is set to blank.
v SQLN >= 2*SQLD and at least one column is a LOB or a distinct type.
2* SQLD SQLVAR entries are set and SQLDOUBLED is set to 2.
v SQLD <= SQLN < 2*SQLD and at least one column is a distinct type, but there
are no LOB columns.
The first SQLD SQLVAR entries are set and SQLDOUBLED is set to blank. If the
SQLWARN bind option is YES, a warning SQLCODE +237 (SQLSTATE 01594) is
issued.
The SQLVAR entries in the SQLDA are not set (requiring allocation of additional
space and another DESCRIBE) in the following cases:
v SQLN < SQLD and no column is either a LOB or distinct type.
No SQLVAR entries are set and SQLDOUBLED is set to blank. If the SQLWARN
bind option is YES, a warning SQLCODE +236 (SQLSTATE 01005) is issued.
Allocate SQLD SQLVAR entries for a successful DESCRIBE.
v SQLN < SQLD and at least one column is a distinct type, but there are no LOB
columns.
No SQLVAR entries are set and SQLDOUBLED is set to blank. If the SQLWARN
bind option is YES, a warning SQLCODE +239 (SQLSTATE 01005) is issued.
Allocate 2*SQLD SQLVAR entries for a successful DESCRIBE, including the
names of the distinct types.
v SQLN < 2*SQLD and at least one column is a LOB.

122

Developing Embedded SQL Applications

No SQLVAR entries are set and SQLDOUBLED is set to blank. A warning

SQLCODE +238 (SQLSTATE 01005) is issued (regardless of the setting of the
SQLWARN bind option).
Allocate 2*SQLD SQLVAR entries for a successful DESCRIBE.
The SQLWARN option of the BIND command is used to control whether the
DESCRIBE (or PREPARE...INTO) will return the following warnings:
v SQLCODE +236 (SQLSTATE 01005)
v SQLCODE +237 (SQLSTATE 01594)
v SQLCODE +239 (SQLSTATE 01005).
It is recommended that your application code always consider that these
SQLCODE values could be returned. The warning SQLCODE +238 (SQLSTATE
01005) is always returned when there are LOB columns in the select list and there
are insufficient SQLVAR entries in the SQLDA. This is the only way the application
can know that the number of SQLVAR entries must be doubled because of a LOB
column in the result set.

Allocating an SQLDA structure with sufficient SQLVAR entries

for dynamically executed SQL statements
After you determine the number of columns in the result table, you must allocate
storage for a second full-size SQLDA. The first SQLDA is used for input
parameters and the second full-size SQLDA is used for output parameters.

About this task

Assume that the result table contains 20 columns (none of which are LOB
columns). In this situation, you must allocate a second SQLDA structure, fulsqlda
with at least 20 SQLVAR elements (or 40 elements if the result table contains any
LOBs or distinct types). For the rest of this example, assume that no LOBs or
distinct types are in the result table.
When you calculate the storage requirements for SQLDA structures, include the
following items:

Procedure
v A fixed-length header, 16 bytes in length, containing fields such as SQLN and
SQLD
v A variable-length array of SQLVAR entries, of which each element is 44 bytes in
length on 32-bit platforms, and 56 bytes in length on 64-bit platforms.

What to do next
The number of SQLVAR entries needed for fulsqlda is specified in the SQLD field
of minsqlda. Assume this value is 20. Therefore, the storage allocation required for
fulsqlda is:
16 + (20 * sizeof(struct sqlvar))

This value represents the size of the header plus 20 times the size of each SQLVAR
entry, giving a total of 896 bytes.
You can use the SQLDASIZE macro to avoid doing your own calculations and to
avoid any version-specific dependencies.

Chapter 3. Programming

123

Describing a SELECT statement in a dynamically executed SQL

program
After you allocate sufficient space for the second SQLDA (in this example, called
fulsqlda), you must code the application to describe the SELECT statement.

Procedure
Code your application to perform the following steps:
1. Store the value 20 in the SQLN field of fulsqlda (the assumption in this
example is that the result table contains 20 columns, and none of these columns
are LOB columns).
2. Obtain information about the SELECT statement using the second SQLDA
structure, fulsqlda. Two methods are available:
v Use another PREPARE statement, specifying fulsqlda instead of minsqlda.
v Use the DESCRIBE statement specifying fulsqlda.

What to do next
Using the DESCRIBE statement is preferred because the costs of preparing the
statement a second time are avoided. The DESCRIBE statement reuses information
previously obtained during the prepare operation to fill in the new SQLDA
structure. The following statement can be issued:
EXEC SQL DESCRIBE STMT INTO :fulsqlda

After this statement is executed, each SQLVAR element contains a description of

one column of the result table.

Acquiring storage to hold a row

Before the application can fetch a row of the result table using an SQLDA
structure, the application must first allocate storage for the row.

Procedure
Code your application to do the following tasks:
1. Analyze each SQLVAR description to determine how much space is required
for the value of that column.
Note that for LOB values, when the SELECT is described, the data type given
in the SQLVAR is SQL_TYP_xLOB. This data type corresponds to a plain LOB
host variable, that is, the whole LOB will be stored in memory at one time. This
will work for small LOBs (up to a few MB), but you cannot use this data type
for large LOBs (say 1 GB) because the stack is unable to allocate enough
memory. It will be necessary for your application to change its column
definition in the SQLVAR to be either SQL_TYP_xLOB_LOCATOR or
SQL_TYPE_xLOB_FILE. (Note that changing the SQLTYPE field of the SQLVAR
also necessitates changing the SQLLEN field.) After changing the column
definition in the SQLVAR, your application can then allocate the correct amount
of storage for the new type.
2. Allocate storage for the value of that column.
3. Store the address of the allocated storage in the SQLDATA field of the SQLDA
structure.

124

Developing Embedded SQL Applications

What to do next
These steps are accomplished by analyzing the description of each column and
replacing the content of each SQLDATA field with the address of a storage area
large enough to hold any values from that column. The length attribute is
determined from the SQLLEN field of each SQLVAR entry for data items that are
not of a LOB type. For items with a type of BLOB, CLOB, or DBCLOB, the length
attribute is determined from the SQLLONGLEN field of the secondary SQLVAR
entry.
In addition, if the specified column allows nulls, the application must replace the
content of the SQLIND field with the address of an indicator variable for the
column.

Processing the cursor in a dynamically executed SQL program

After you allocate the SQLDA structure, you can open the cursor associated with
the SELECT statement and fetch rows.

About this task

To process the cursor that is associated with a SELECT statement, first open the
cursor, then fetch rows by specifying the USING DESCRIPTOR clause of the
FETCH statement. For example, a C application can have following lines:
EXEC SQL OPEN pcurs
EMB_SQL_CHECK( "OPEN" ) ;
EXEC SQL FETCH pcurs USING DESCRIPTOR :*sqldaPointer
EMB_SQL_CHECK( "FETCH" ) ;

For a successful FETCH, you could write the application to obtain the data from
the SQLDA and display the column headings. For example:
display_col_titles( sqldaPointer ) ;

After the data is displayed, you should close the cursor and release any
dynamically allocated memory. For example:
EXEC SQL CLOSE pcurs ;
EMB_SQL_CHECK( "CLOSE CURSOR" ) ;

Allocating an SQLDA structure for a dynamically executed SQL

program
Allocate an SQLDA structure for your application so that you can use it to pass
data to and from your application.

About this task

To create an SQLDA structure with C, either embed the INCLUDE SQLDA
statement in the host language or include the SQLDA include file to get the
structure definition. Then, because the size of an SQLDA is not fixed, the
application must declare a pointer to an SQLDA structure and allocate storage for
it. The actual size of the SQLDA structure depends on the number of distinct data
items being passed using the SQLDA.
In the C and C++ programming language, a macro is provided to facilitate SQLDA
allocation. This macro has the following format:
#define SQLDASIZE(n) (offsetof(struct sqlda, sqlvar) \
+ (n) sizeof(struct sqlvar))

Chapter 3. Programming

125

The effect of this macro is to calculate the required storage for an SQLDA with n
SQLVAR elements.
To create an SQLDA structure with COBOL, you can either embed an INCLUDE
SQLDA statement or use the COPY statement. Use the COPY statement when you
want to control the maximum number of SQLVAR entries and hence the amount of
storage that the SQLDA uses. For example, to change the default number of
SQLVAR entries from 1489 to 1, use the following COPY statement:
COPY "sqlda.cbl"
replacing --1489-by --1--.

The FORTRAN language does not directly support self-defining data structures or
dynamic allocation. No SQLDA include file is provided for FORTRAN, because it
is not possible to support the SQLDA as a data structure in FORTRAN. The
precompiler will ignore the INCLUDE SQLDA statement in a FORTRAN program.
However, you can create something similar to a static SQLDA structure in a
FORTRAN program, and use this structure wherever an SQLDA can be used. The
file sqldact.f contains constants that help in declaring an SQLDA structure in
FORTRAN.
Execute calls to SQLGADDR to assign pointer values to the SQLDA elements that
require them.
The following table shows the declaration and use of an SQLDA structure with one
SQLVAR element.
Language
C and C++

Example Source Code

#include
struct sqlda *outda = (struct sqlda *)malloc(SQLDASIZE(1));
/* DECLARE LOCAL VARIABLES FOR HOLDING ACTUAL DATA */
double sal = 0;
short salind = 0;
/* INITIALIZE ONE ELEMENT OF SQLDA */
memcpy( outda->sqldaid,"SQLDA
",sizeof(outda->sqldaid));
outda->sqln = outda->sqld = 1;
outda->sqlvar[0].sqltype = SQL_TYP_NFLOAT;
outda->sqlvar[0].sqllen = sizeof( double );.
outda->sqlvar[0].sqldata = (unsigned char *)&sal;
outda->sqlvar[0].sqlind = (short *)&salind;

126

Developing Embedded SQL Applications

Language
COBOL

Example Source Code

WORKING-STORAGE SECTION.
77 SALARY
PIC S99999V99 COMP-3.
77 SAL-IND
PIC S9(4)
COMP-5.
EXEC SQL INCLUDE SQLDA END-EXEC
* Or code a useful way to save unused SQLVAR entries.
* COPY "sqlda.cbl" REPLACING --1489-- BY --1--.
01 decimal-sqllen pic s9(4) comp-5.
01 decimal-parts redefines decimal-sqllen.
05 precision pic x.
05 scale pic x.
* Initialize one element of output SQLDA
MOVE 1 TO SQLN
MOVE 1 TO SQLD
MOVE SQL-TYP-NDECIMAL TO SQLTYPE(1)
* Length = 7 digits precision and 2 digits scale
MOVE x"07" TO PRECISION.
MOVE x"02" TO SCALE.
MOVE DECIMAL-SQLLEN TO O-SQLLEN(1).
SET SQLDATA(1) TO ADDRESS OF SALARY
SET SQLIND(1) TO ADDRESS OF SAL-IND

Chapter 3. Programming

127

Language

Example Source Code

FORTRAN

include sqldact.f
integer*2 sqlvar1
parameter ( sqlvar1 = sqlda_header_sz + 0*sqlvar_struct_sz )
C

Declare an Output SQLDA -- 1 Variable

character
out_sqlda(sqlda_header_sz + 1*sqlvar_struct_sz)
character*8 out_sqldaid
integer*4
out_sqldabc
integer*2
out_sqln
integer*2
out_sqld

! Header

integer*2
integer*2
integer*4
integer*4
integer*2
character*30

! First Variable

equivalence(
equivalence(
equivalence(
equivalence(
equivalence(
equivalence(
equivalence(
equivalence(
equivalence(
+
equivalence(
+

out_sqltype1
out_sqllen1
out_sqldata1
out_sqlind1
out_sqlnamel1
out_sqlnamec1

out_sqlda(sqlda_sqldaid_ofs), out_sqldaid )
out_sqlda(sqlda_sqldabc_ofs), out_sqldabc )
out_sqlda(sqlda_sqln_ofs), out_sqln
)
out_sqlda(sqlda_sqld_ofs), out_sqld
)
out_sqlda(sqlvar1+sqlvar_type_ofs), out_sqltype1 )
out_sqlda(sqlvar1+sqlvar_len_ofs), out_sqllen1
)
out_sqlda(sqlvar1+sqlvar_data_ofs), out_sqldata1 )
out_sqlda(sqlvar1+sqlvar_ind_ofs), out_sqlind1
)
out_sqlda(sqlvar1+sqlvar_name_length_ofs),
out_sqlnamel1
)
out_sqlda(sqlvar1+sqlvar_name_data_ofs),
out_sqlnamec1
)

Declare Local Variables for Holding Returned Data.

real*8
salary
integer*2
sal_ind

Initialize the Output SQLDA (Header)

out_sqldaid = OUT_SQLDA
out_sqldabc = sqlda_header_sz + 1*sqlvar_struct_sz
out_sqln
= 1
out_sqld
= 1
Initialize VAR1
out_sqltype1 = SQL_TYP_NFLOAT
out_sqllen1 = 8
rc = sqlgaddr( %ref(salary), %ref(out_sqldata1) )
rc = sqlgaddr( %ref(sal_ind), %ref(out_sqlind1) )

Note: This example was written for 32-bit FORTRAN.

In languages not supporting dynamic memory allocation, an SQLDA with the
required number of SQLVAR elements must be explicitly declared in the host
language. Be sure to declare enough SQLVAR elements as determined by the needs
of the application.

Transferring data in a dynamically executed SQL program using

an SQLDA structure
You have greater flexibility when you transfer data using an SQLDA instead of
using lists of host variables. For example, you can use an SQLDA to transfer data
that has no native host language equivalent, such as DECIMAL data in the C
language.

128

Developing Embedded SQL Applications

About this task

Use the following table as a cross-reference listing that shows how the numeric
values and symbolic names are related.
Table 17. DB2 SQLDA SQL Types
SQL Column Type

SQLTYPE numeric value SQLTYPE symbolic name1

DATE

384/385

SQL_TYP_DATE / SQL_TYP_NDATE

TIME

388/389

SQL_TYP_TIME / SQL_TYP_NTIME

TIMESTAMP

392/393

SQL_TYP_STAMP / SQL_TYP_NSTAMP

400/401

SQL_TYP_CGSTR / SQL_TYP_NCGSTR

BLOB

404/405

SQL_TYP_BLOB / SQL_TYP_NBLOB

CLOB

408/409

SQL_TYP_CLOB / SQL_TYP_NCLOB

DBCLOB

412/413

SQL_TYP_DBCLOB / SQL_TYP_NDBCLOB

VARCHAR

448/449

SQL_TYP_VARCHAR / SQL_TYP_NVARCHAR

CHAR

452/453

SQL_TYP_CHAR / SQL_TYP_NCHAR

LONG VARCHAR

456/457

SQL_TYP_LONG / SQL_TYP_NLONG

460/461

SQL_TYP_CSTR / SQL_TYP_NCSTR

VARGRAPHIC

464/465

SQL_TYP_VARGRAPH / SQL_TYP_NVARGRAPH

GRAPHIC

468/469

SQL_TYP_GRAPHIC / SQL_TYP_NGRAPHIC

LONG VARGRAPHIC

472/473

SQL_TYP_LONGRAPH / SQL_TYP_NLONGRAPH

FLOAT

480/481

SQL_TYP_FLOAT / SQL_TYP_NFLOAT

480/481

SQL_TYP_FLOAT / SQL_TYP_NFLOAT

484/485

SQL_TYP_DECIMAL / SQL_TYP_DECIMAL

INTEGER

496/497

SQL_TYP_INTEGER / SQL_TYP_NINTEGER

SMALLINT

500/501

SQL_TYP_SMALL / SQL_TYP_NSMALL

n/a

804/805

SQL_TYP_BLOB_FILE / SQL_TYPE_NBLOB_FILE

n/a

808/809

SQL_TYP_CLOB_FILE / SQL_TYPE_NCLOB_FILE

n/a

812/813

SQL_TYP_DBCLOB_FILE / SQL_TYPE_NDBCLOB_FILE

n/a

960/961

SQL_TYP_BLOB_LOCATOR / SQL_TYP_NBLOB_LOCATOR

n/a

964/965

SQL_TYP_CLOB_LOCATOR / SQL_TYP_NCLOB_LOCATOR

n/a

968/969

SQL_TYP_DBCLOB_LOCATOR / SQL_TYP_NDBCLOB_LOCATOR

XML

988/989

SQL_TYP_XML / SQL_TYP_XML

n/a

n/a

REAL

DECIMAL

Note: These defined types can be found in the sql.h include file located in the include sub-directory of the sqllib
directory. (For example, sqllib/include/sql.h for the C programming language.)
1. For the COBOL programming language, the SQLTYPE name does not use underscore (_) but uses a hyphen (-)
instead.
2. This is a null-terminated graphic string.
3. This is a null-terminated character string.
4. The difference between REAL and DOUBLE in the SQLDA is the length value (4 or 8).
5. Precision is in the first byte. Scale is in the second byte.

Chapter 3. Programming

129

Processing interactive SQL statements in dynamically executed

SQL programs
You can write an application using dynamic SQL to process arbitrary SQL
statements. For example, if an application accepts SQL statements from a user, the
application must be able to issue the statements without any prior knowledge of
the statements.

About this task

Values that are not known until execution time can be represented by parameter
marks, which are denoted by question marks. Parameter marks allow for the
interaction between the user and the application and is similar to host variables for
static SQL statements.
Use the PREPARE and DESCRIBE statements with an SQLDA structure so that the
application can determine the type of SQL statement being issued, and act
accordingly.

Determination of statement type in dynamically executed SQL

programs
When an SQL statement is prepared, you can determine information concerning
the type of statement by examining the SQLDA structure. This information is
placed in the SQLDA structure either at statement preparation time with the INTO
clause, or by issuing a DESCRIBE statement against a previously prepared
statement.
In either case, the database manager places a value in the SQLD field of the
SQLDA structure, indicating the number of columns in the result table generated
by the SQL statement. If the SQLD field contains a zero (0), the statement is not a
SELECT statement. Since the statement is already prepared, it can immediately be
executed using the EXECUTE statement.
If the statement contains parameter markers, the USING clause must be specified.
The USING clause can specify either a list of host variables or an SQLDA structure.
If the SQLD field is greater than zero, the statement is a SELECT statement and
must be processed as described in the following sections.

Processing variable-list SELECT statements in dynamically

executed SQL programs
A varying-list SELECT statement is one in which the number and types of columns
that are to be returned are not known at precompilation time.
In this case, the application does not know in advance the exact host variables that
need to be declared to hold a row of the result table.

Procedure
To process a variable-list SELECT statement, code your application to do the
following steps:
1. Declare an SQLDA.
An SQLDA structure must be used to process varying-list SELECT statements.
2. PREPARE the statement using the INTO clause.
The application then determines whether the SQLDA structure declared has
enough SQLVAR elements. If it does not, the application allocates another

130

Developing Embedded SQL Applications

SQLDA structure with the required number of SQLVAR elements, and issues an
additional DESCRIBE statement using the new SQLDA.
3. Allocate the SQLVAR elements.
Allocate storage for the host variables and indicators needed for each SQLVAR.
This step involves placing the allocated addresses for the data and indicator
variables in each SQLVAR element.
4. Process the SELECT statement.
A cursor is associated with the prepared statement, opened, and rows are
fetched using the properly allocated SQLDA structure.

Saving SQL requests from end users

If the users of your application can issue SQL requests from the application, you
might want to save these requests.

About this task

If your application allows users to save arbitrary SQL statements, you can save
them in a table with a column having a data type of VARCHAR, CLOB,
VARGRAPHIC or DBCLOB. Note that the VARGRAPHIC and DBCLOB data types
are only available in double-byte character set (DBCS) and Extended UNIX Code
(EUC) environments.
You must save the source SQL statements, not the prepared versions. This means
that you must retrieve and then prepare each statement before executing the
version stored in the table. In essence, your application prepares an SQL statement
from a character string and executes this statement dynamically.

Providing variable input to dynamically executed SQL

statements by using parameter markers
In a dynamic SQL statement, parameter markers that are indicated by a question
mark (?) or a colon followed by a name (:name) are substituting host variables.

About this task

A dynamic SQL statement cannot contain host variables because host variable
information (data type and length) is available only during application
precompilation; during execution, host variable information is unavailable. In a
dynamic SQL statement, parameter markers are used instead of host variables. A
parameter marker is indicated by a question mark (?) or a colon followed by a
name (:name) and indicates where to substitute a host variable inside an SQL
statement.
For example, assume that you want to use a dynamic SQL statement to delete data
from a table called TEMPL based on the value of an employee number. You might
specify the DELETE statement as follows, using a parameter marker:
DELETE FROM TEMPL WHERE EMPNO = ?

To execute this statement, specify a host variable or an SQLDA structure for the
USING clause of the EXECUTE statement. The contents of the host variable is used
to specify the value of EMPNO.
The data type and length of the parameter marker depend on the context of the
parameter marker inside the SQL statement. If the data type of a parameter marker
is not obvious from the context of the statement in which it is used, use a CAST
Chapter 3. Programming

131

specification to specify the data type. A parameter marker for which you use a
CAST specification is a typed parameter marker. A typed parameter marker is
treated like a host variable of the data type used in the CAST specification. For
example, the statement SELECT ? FROM SYSCAT.TABLES is invalid because the data
type of the result column is unknown. However, the statement SELECT CAST(? AS
INTEGER) FROM SYSCAT.TABLES is valid because the CAST specification indicates
that the parameter marker represents an INTEGER value; the data type of the
result column is known.
If the SQL statement contains more than one parameter marker, the USING clause
of the EXECUTE statement must specify one of the following types of information:
v A list of host variables, one variable for each parameter marker
v An SQLDA that has one SQLVAR entry for each parameter marker for non-LOB
data types or two SQLVAR entries per parameter marker for LOB data types
The host variable list or SQLVAR entries are matched according to the order of the
parameter markers in the statement, and the data types must be compatible.
Note: Using a parameter marker in a dynamic SQL statement is like using a host
variable in a static SQL statement in that the optimizer does not use distribution
statistics and might not choose the best access plan.
The rules that apply to parameter markers are described in the PREPARE
statement topic.

Example of parameter markers in a dynamically executed SQL

program
In the statement string of a dynamic SQL statement, a parameter marker represents
a value that will be provided by the application program. The value of a parameter
marker is provided on the EXECUTE or OPEN statement that is associated with
the dynamic SQL statement.
The following examples show how to use parameter markers in a dynamic SQL
program:
v C and C++ (dbuse.sqc/dbuse.sqC)
The function DynamicStmtWithMarkersEXECUTEusingHostVars() in the C-language
sample dbuse.sqc shows how to perform a delete using a parameter marker
with a host variable:
EXEC SQL BEGIN DECLARE SECTION;
char hostVarStmt1[50];
short hostVarDeptnumb;
EXEC SQL END DECLARE SECTION;
/* prepare the statement with a parameter marker */
strcpy(hostVarStmt1, "DELETE FROM org WHERE deptnumb = ?");
EXEC SQL PREPARE Stmt1 FROM :hostVarStmt1;
/* execute the statement for hostVarDeptnumb = 15 */
hostVarDeptnumb = 15;
EXEC SQL EXECUTE Stmt1 USING :hostVarDeptnumb;

v COBOL (varinp.sqb)
The following example is from the COBOL sample varinp.sqb, and shows how
to use a parameter marker in search and update conditions:
EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 pname
pic x(10).
01 dept
pic s9(4) comp-5.
01 st
pic x(127).

132

Developing Embedded SQL Applications

01 parm-var
pic x(5).
EXEC SQL END DECLARE SECTION END-EXEC.
-

move "SELECT name, dept FROM staff

"
WHERE job = ? FOR UPDATE OF job" to st.
EXEC SQL PREPARE s1 FROM :st END-EXEC.
EXEC SQL DECLARE c1 CURSOR FOR s1 END-EXEC.
move "Mgr" to parm-var.
EXEC SQL OPEN c1 USING :parm-var END-EXEC
move "Clerk" to parm-var.
move "UPDATE staff SET job = ? WHERE CURRENT OF c1" to st.
EXEC SQL PREPARE s2 from :st END-EXEC.

* call the FETCH and UPDATE loop.

perform Fetch-Loop thru End-Fetch-Loop
until SQLCODE not equal 0.
EXEC SQL CLOSE c1 END-EXEC.

Calling procedures in embedded SQL applications

You can call procedures from embedded SQL applications by formulating and
executing the CALL statement with an appropriate procedure reference and
parameters. You can issue the CALL statement either statically or dynamically
within embedded SQL applications.
However, for each programming language there are different methods to issue this
command. No matter which host language, each host variable used in the
procedure must be declared to match the data type which is required.
Client applications and the calling of routines exchange information with
procedures through parameters and result sets. The parameters for procedures are
defined by the direction the data is traveling (the parameter mode).
There are three types of parameters for procedures:
v IN parameters: data passed to the procedure.
v OUT parameters: data returned by the procedure.
v INOUT parameters: data passed to the procedure that is, during procedure
execution, replaced by data to be returned from the procedure.
The mode of parameters and their data types are defined when a procedure is
registered with the CREATE PROCEDURE statement.

Calling stored procedures in C and C++ embedded SQL

applications
You can use the anonymous blocks or the EXEC SQL CALL statements to call stored
procedures in C and C++ embedded SQL applications.

Calling stored procedures by using the EXEC SQL CALL statement

DB2 supports the use of input, output, and input and output parameters in SQL
procedures. The IN, OUT, and INOUT keywords in the CREATE PROCEDURE
statement indicate the mode or intended use of the parameter. IN and OUT
parameters are passed by value, and INOUT parameters are passed by reference.
When working with C and C++ applications, you can call an INOUT_PARAM
stored procedure by using the following statement:
Chapter 3. Programming

133

EXEC SQL CALL INOUT_PARAM(:inout_median:medianind, :out_sqlcode:codeind,

:out_buffer:bufferind);

In the previous statement inout_median, out_sqlcode, and out_buffer are host variables
and medianind, codeind, and bufferind are null indicator variables.
Note: You can also call stored procedures dynamically by preparing a CALL
statement.

Calling stored procedures by using the anonymous block

In Version 9.7 Fix Pack 6 and later fix packs, C and C++ embedded SQL
applications can call stored procedures by using an anonymous block when the
PRECOMPILE option COMPATIBILITY_MODE is set to ORA.


EXECUTE BEGIN procedure-name

,
(

argument

END; END-EXEC;



argument:

parameter-name =>

expression
DEFAULT
NULL

Parameter description
procedure-name
A name of the procedure, which is described in the catalogue, that you
want to call.
argument description
parameter-name
The name of the parameter that the argument is assigned to. When
you assign an argument to a paramater by name, all the arguments
that follow the (parameter) must be assigned by name.
You can only specify a named argument once (implicitly or
explicitly).
Named arguments are not supported on a call to an uncataloged
procedure.
expression or DEFAULT or NULL
Each specification of expression, the DEFAULT keyword, or the
NULL keyword is an argument of the CALL. The nth unnamed
argument of the CALL statement corresponds to the nth parameter
that is defined in the CREATE PROCEDURE statement for the
procedure.
Named arguments correspond to the same named parameter,
regardless of the order in which arguments are specified.

134

Developing Embedded SQL Applications

The DEFAULT keyword is used in the CREATE PROCEDURE

statement if you have specified it; otherwise the null value is used
as the default.
If the NULL keyword is specified, the null value is passed as the
parameter value.
Each argument of the CALL statement must be compatible with
the corresponding parameter in the procedure definition as follows:
v IN parameter
The argument must be assignable to the parameter.
The assignment of a string argument uses the storage
assignment rules.
v OUT parameter
The argument must be a single variable or parameter marker.
The argument must be assignable to the parameter.
The assignment of a string argument uses the retrieval
assignment rules.
v INOUT parameter
The argument must be a single variable or parameter marker.
The argument must be assignable to the parameter.
The assignment of a string argument uses the storage
assignment rules on invocation and the retrieval assignment
rules on return.

Calling stored procedures from REXX

You can write stored procedures in any language that is supported on a server,
except for REXX on AIX operating systems.
Client applications can be written in REXX on AIX operating systems, but as with
other languages, client applications cannot call a stored procedure written in REXX
on AIX.

Reading and scrolling through result sets in embedded SQL

applications
One of the most common tasks of an embedded SQL application program is to
retrieve data. You can retrieve data by using the select-statement, which is a form of
query that searches for rows of tables in the database that meet specified search
conditions.
If such rows exist, the data is retrieved and put into specified variables in the host
program, where it can be used for whatever it was designed to do.
Note: Embedded SQL applications can call stored procedures with any of the
supported stored procedure implementations and can retrieve output and
input-output parameter values, however embedded SQL applications cannot read
and scroll through result sets returned by stored procedures.
After you have written a select-statement, you code the SQL statements that define
how information will be passed to your application.

Chapter 3. Programming

135

You can think of the result of a select-statement as being a table having rows and
columns, much like a table in the database. If only one row is returned, you can
deliver the results directly into host variables specified by the SELECT INTO
statement.
If more than one row is returned, you must use a cursor to fetch them one at a
time. A cursor is a named control structure used by an application program to
point to a specific row within an ordered set of rows.

Scrolling through previously retrieved data in embedded SQL

applications
When an application retrieves data from the database, the FETCH statement allows
you to scroll forward through the data. There is no equivalent SQL statement that
you can use to scroll backwards through the result set.
You can use the CLI and the DB2 Universal JDBC Driver to run a backward
FETCH through read-only scrollable cursors.

Procedure
For embedded SQL applications, you can use the following techniques to scroll
through data that has been retrieved:
v Keep a copy of the data that has been fetched in the application memory and
scroll through it by some programming technique.
v Use SQL to retrieve the data again, typically by using a second SELECT
statement.

Keeping a copy of fetched data in embedded SQL applications

In some situations, it might be useful to maintain a copy of data that is fetched by
the application.

Procedure
To keep a copy of the data, your application can do the one of the following tasks:
v Save the fetched data in virtual storage.
v Write the data to a temporary file (if the data does not fit in virtual storage).
One effect of this approach is that a user, scrolling backward, always sees exactly
the same data that was fetched, even if the data in the database was changed in
the interim by a transaction.
v Using an isolation level of repeatable read, the data you retrieve from a
transaction can be retrieved again by closing and opening a cursor. Other
applications are prevented from updating the data in your result set. Isolation
levels and locking can affect how users update data.

Retrieving fetched data a second time in embedded SQL

applications
The technique that you use to retrieve data a second time depends on the order in
which you want to see the data again.

Procedure
You can retrieve data a second time by using any of the following methods:
v Retrieve data from the beginning

136

Developing Embedded SQL Applications

To retrieve the data again from the beginning of the result table, close the active
cursor and reopen it. This action positions the cursor at the beginning of the
result table. But, unless the application holds locks on the table, others may have
changed it, so what had been the first row of the result table may no longer be.
v Retrieve data from the middle
To retrieve data a second time from somewhere in the middle of the result table,
issue a second SELECT statement and declare a second cursor on the statement.
For example, suppose the first SELECT statement was:
SELECT * FROM DEPARTMENT
WHERE LOCATION = CALIFORNIA
ORDER BY DEPTNO

Now, suppose that you want to return to the rows that start with DEPTNO =
M95 and fetch sequentially from that point. Code the following statement:
SELECT * FROM DEPARTMENT
WHERE LOCATION = CALIFORNIA
AND DEPTNO >= M95
ORDER BY DEPTNO

This statement positions the cursor where you want it.

v Retrieve data in reverse order
Ascending ordering of rows is the default. If there is only one row for each
value of DEPTNO, then the following statement specifies a unique ascending
ordering of rows:
SELECT * FROM DEPARTMENT
WHERE LOCATION = CALIFORNIA
ORDER BY DEPTNO

To retrieve the same rows in reverse order, specify that the order is descending,
as in the following statement:
SELECT * FROM DEPARTMENT
WHERE LOCATION = CALIFORNIA
ORDER BY DEPTNO DESC

A cursor on the second statement retrieves rows in exactly the opposite order
from a cursor on the first statement. Order of retrieval is guaranteed only if the
first statement specifies a unique ordering sequence.
For retrieving rows in reverse order, it can be useful to have two indexes on the
DEPTNO column, one in ascending order, and the other in descending order.

Row order differences in result tables

The rows of multiple result tables for the same SELECT statement might not be
displayed in the same order. The database manager does not consider the order of
rows as significant unless the SELECT statement uses ORDER BY.
Thus, if there are several rows with the same DEPTNO value, the second SELECT
statement can retrieve them in a different order from the first. The only guarantee
is that they will all be in order by department number, as demanded by the clause
ORDER BY DEPTNO.
The difference in ordering can occur even if you were to issue the same SQL
statement, with the same host variables, a second time. For example, the statistics
in the catalog can be updated between executions, or indexes can be created or
dropped. You can then issue the SELECT statement again.
The ordering is more likely to change if the second SELECT has a predicate that
the first did not have; the database manager can choose to use an index on the
new predicate. For example, it can choose an index on LOCATION for the first
Chapter 3. Programming

137

statement in the example, and an index on DEPTNO for the second. Because rows are
fetched in order by the index key, the second order need not be the same as the
first.
Again, executing two similar SELECT statements can produce a different ordering
of rows, even if no statistics change and no indexes are created or dropped. In the
example, if there are many different values of LOCATION, the database manager can
choose an index on LOCATION for both statements. Yet changing the value of DEPTNO
in the second statement to the following example can cause the database manager
to choose an index on DEPTNO:
SELECT * FROM DEPARTMENT
WHERE LOCATION = CALIFORNIA
AND DEPTNO >= Z98
ORDER BY DEPTNO

Because of the subtle relationships between the form of an SQL statement and the
values in this statement, never assume that two different SQL statements will
return rows in the same order unless the order is uniquely determined by an
ORDER BY clause.

Updating previously retrieved data in embedded SQL

applications
To scroll backward and update data that was retrieved previously, you can use a
combination of the techniques that are used to scroll through previously retrieved
data and to update retrieved data.

Procedure
To update previously retrieved data, you can do one of two things:
v If you have a second cursor on the data to be updated and the SELECT
statement uses none of the restricted elements, you can use a cursor-controlled
UPDATE statement. Name the second cursor in the WHERE CURRENT OF
clause.
v In other cases, use UPDATE with a WHERE clause that names all the values in
the row or specifies the primary key of the table. You can issue one statement
many times with different values of the variables.

Selecting multiple rows using a cursor in embedded SQL

applications
To allow an application to retrieve a set of rows, SQL uses a mechanism called a
cursor.

About this task

To help understand the concept of a cursor, assume that the database manager
builds a result table to hold all the rows retrieved by executing a SELECT
statement. A cursor makes rows from the result table available to an application by
identifying or pointing to a current row of this table. When a cursor is used, an
application can retrieve each row sequentially from the result table until an end of
data condition, that is, the NOT FOUND condition, SQLCODE +100 (SQLSTATE
02000) is reached. The set of rows obtained as a result of executing the SELECT
statement can consist of zero, one, or more rows, depending on the number of
rows that satisfy the search condition.

138

Developing Embedded SQL Applications

Procedure
To
1.
2.
3.

process a cursor:
Specify the cursor using a DECLARE CURSOR statement.
Perform the query and build the result table using the OPEN statement.
Retrieve rows one at a time using the FETCH statement.

4. Process rows with the DELETE or UPDATE statements (if required).

5. Terminate the cursor using the CLOSE statement.

What to do next
An application can use several cursors concurrently. Each cursor requires its own
set of DECLARE CURSOR, OPEN, CLOSE, and FETCH statements.

Updating and deleting retrieved data in statically executed SQL

applications
It is possible to update and delete the row referenced by a cursor. For a row to be
updatable, the query corresponding to the cursor must not be read-only.

About this task

To update with a cursor, use the WHERE CURRENT OF clause in an UPDATE
statement. Use the FOR UPDATE clause to tell the system that you want to update
some columns of the result table. You can specify a column in the FOR UPDATE
without it being in the fullselect; therefore, you can update columns that are not
explicitly retrieved by the cursor. If the FOR UPDATE clause is specified without
column names, all columns of the table or view identified in the first FROM clause
of the outer fullselect are considered to be updatable. Do not name more columns
than you need in the FOR UPDATE clause. In some cases, naming extra columns
in the FOR UPDATE clause can cause DB2 to be less efficient in accessing the data.
Deletion with a cursor is done using the WHERE CURRENT OF clause in a
DELETE statement. In general, the FOR UPDATE clause is not required for
deletion of the current row of a cursor. The only exception occurs when using
dynamic SQL for either the SELECT statement or the DELETE statement in an
application that has been precompiled with LANGLEVEL set to SAA1 and bound
with BLOCKING ALL. In this case, a FOR UPDATE clause is necessary in the
SELECT statement.
The DELETE statement causes the row being referenced by the cursor to be
deleted. The deletion leaves the cursor positioned before the next row, and a
FETCH statement must be issued before additional WHERE CURRENT OF
operations can be performed against the cursor.

Example of a fetch in a statically executed SQL program

A fetch is an SQL action that positions a cursor on the next row of its result table
and assigns the values of that row to host variables.
The following sample selects from a table using a cursor, opens the cursor, and
fetches rows from the table. For each row fetched, the program decides, based on
simple criteria, whether the row must be deleted or updated.
The REXX language does not support static SQL, so a sample is not provided.
v C and C++ (tbmod.sqc/tbmod.sqC)
Chapter 3. Programming

139

The following example selects from a table using a cursor, opens the cursor,
fetches, updates, or delete rows from the table, then closes the cursor.
EXEC SQL DECLARE c1 CURSOR FOR SELECT * FROM staff WHERE id >= 310;
EXEC SQL OPEN c1;
EXEC SQL FETCH c1 INTO :id, :name, :dept, :job:jobInd, :years:yearsInd, :salary,
:comm:commInd;

The sample shows almost all possible cases of table data modification.
v COBOL (openftch.sqb)
The following example is from the sample openftch. This example selects from a
table using a cursor, opens the cursor, and fetches rows from the table.
EXEC SQL DECLARE c1 CURSOR FOR
SELECT name, dept FROM staff
WHERE job=Mgr
FOR UPDATE OF job END-EXEC.
EXEC SQL OPEN c1 END-EXEC
* call the FETCH and UPDATE/DELETE loop.
perform Fetch-Loop thru End-Fetch-Loop
until SQLCODE not equal 0.
EXEC SQL CLOSE c1 END-EXEC.

Error message retrieval in embedded SQL applications

The method that you use to retrieve error information depends on the language
that you used to write the application.
v C, C++, and COBOL applications can use the GET ERROR MESSAGE API to
obtain the corresponding information related to the SQLCA passed in.
C Example: The SqlInfoPrint procedure from UTILAPI.C
/******************************************************************************
** 1.1 - SqlInfoPrint - prints diagnostic information to the screen.
**
******************************************************************************/
int SqlInfoPrint( char * appMsg,
struct sqlca * pSqlca,
int line,
char * file )
{
int rc = 0;
char sqlInfo[1024];
char sqlInfoToken[1024];
char sqlstateMsg[1024];
char errorMsg[1024];
if (pSqlca->sqlcode != 0 && pSqlca->sqlcode != 100)
{ strcpy(sqlInfo, "");
if( pSqlca->sqlcode < 0)
{
sprintf( sqlInfoToken, "\n---- error report ----\n");
strcat( sqlInfo, sqlInfoToken);
}
else
{
sprintf( sqlInfoToken, "\n---- warning report ----\n");
strcat( sqlInfo, sqlInfoToken);
} /* endif */
sprintf( sqlInfoToken, " app. message
strcat( sqlInfo, sqlInfoToken);
sprintf( sqlInfoToken, " line
strcat( sqlInfo, sqlInfoToken);
sprintf( sqlInfoToken, " file
strcat( sqlInfo, sqlInfoToken);
sprintf( sqlInfoToken, " SQLCODE

140

Developing Embedded SQL Applications

= %s\n", appMsg);
= %d\n", line);
= %s\n", file);
= %ld\n",

pSqlca->sqlcode);
strcat( sqlInfo, sqlInfoToken);
/* get error message */
rc = sqlaintp( errorMsg, 1024, 80, pSqlca);
/* return code is the length of the errorMsg string */
if( rc > 0)
{ sprintf( sqlInfoToken, "%s\n", errorMsg);
strcat( sqlInfo, sqlInfoToken);
}
/* get SQLSTATE message */
rc = sqlogstt( sqlstateMsg, 1024, 80, pSqlca->sqlstate);
if (rc == 0)
{ sprintf( sqlInfoToken, "%s\n", sqlstateMsg);
strcat( sqlInfo, sqlInfoToken);
}
if( pSqlca->sqlcode < 0)
{ sprintf( sqlInfoToken, "--- end error report ---\n");
strcat( sqlInfo, sqlInfoToken);
printf("%s", sqlInfo);
return 1;
}
else
{ sprintf( sqlInfoToken, "--- end warning report ---\n");
strcat( sqlInfo, sqlInfoToken);
printf("%s", sqlInfo);
return 0;
} /* endif */
} /* endif */
return 0;
}

C developers can also use an equivalent function, sqlglm(), which has the
signature:
sqlglm(char *message_buffer_ptr, int *buffer_size_ptr, int *msg_size_ptr)
COBOL Example: From CHECKERR.CBL
********************************
* GET ERROR MESSAGE API called *
********************************
call "sqlgintp" using
by value buffer-size
by value line-width
by reference sqlca
by reference error-buffer
returning error-rc.
************************
* GET SQLSTATE MESSAGE *
************************
call "sqlggstt" using
by value buffer-size
by value line-width
by reference sqlstate
by reference state-buffer
returning state-rc.
if error-rc is greater than 0
display error-buffer.
if state-rc is greater than 0
display state-buffer.
if state-rc is less than 0
display "return code from GET SQLSTATE =" state-rc.

Chapter 3. Programming

141

if SQLCODE is less than 0

display "--- end error report ---"
go to End-Prog.
display "--- end error report ---"
display "CONTINUING PROGRAM WITH WARNINGS!".

v REXX applications use the CHECKERR procedure.

/******
CHECKERR - Check SQLCODE *****/
CHECKERR:
arg errloc
if ( SQLCA.SQLCODE = 0 ) then
return 0
else do
say --- error report ---
say ERROR occurred : errloc
say SQLCODE : SQLCA.SQLCODE
/*********************\
* GET ERROR MESSAGE *
\*********************/
call SQLDBS GET MESSAGE INTO :errmsg LINEWIDTH 80
say errmsg
say --- end error report ---
if (SQLCA.SQLCODE < 0 ) then
exit
else do
say WARNING - CONTINUING PROGRAM WITH ERRORS
return 0
end
end
return 0

Error information in the SQLCODE, SQLSTATE, and SQLWARN

fields
Error information is returned in the SQLCODE and SQLSTATE fields of the
SQLCA structure, which is updated after every executable SQL statement and most
database manager API calls. The SQLWARN field contains an array of warning
indicators, even if SQLCODE is zero.
A source file containing executable SQL statements can provide at least one
SQLCA structure with the name sqlca. The SQLCA structure is defined in the
SQLCA include file. Source files without embedded SQL statements, but calling
database manager APIs, can also provide one or more SQLCA structures, but their
names are arbitrary.
If your application is compliant with the FIPS 127-2 standard, you can declare the
SQLSTATE and SQLCODE as host variables for C, C++, COBOL, and FORTRAN
applications, instead of using the SQLCA structure.
An SQLCODE value of 0 means successful execution (with possible SQLWARN
warning conditions). A positive value means that the statement was successfully
executed but with a warning, as with truncation of a host variable. A negative
value means that an error condition occurred.
An additional field, SQLSTATE, contains a standardized error code consistent
across other IBM database products and across SQL92-conformant database
managers. Practically speaking, you should use SQLSTATE values when you are
concerned about portability since SQLSTATE values are common across many
database managers.

142

Developing Embedded SQL Applications

The first element of the SQLWARN array, SQLWARN0, contains a blank if all other
elements are blank. SQLWARN0 contains a W if at least one other element contains
a warning character.
Note: If you want to develop applications that access various IBM RDBMS servers
you should:
v Where possible, have your applications check the SQLSTATE rather than the
SQLCODE.
v If your applications will use DB2 Connect, consider using the mapping facility
provided by DB2 Connect to map SQLCODE conversions between unlike
databases.

Exit list routine considerations

You must not use SQL or DB2 API calls in exit list routines.
Note: You cannot disconnect from a database in an exit routine.

Exception, signal, and interrupt handler considerations

An exception, signal, or interrupt handler is a routine that gains control when an
exception, signal, or interrupt occurs. The type of handler used is determined by
your operating environment.
Windows operating systems
Pressing Ctrl-C or Ctrl-Break generates an interrupt.
UNIX operating systems
Usually, pressing Ctrl-C generates the SIGINT interrupt signal. Note that
keyboards can easily be redefined so that SIGINT can be generated by a
different key sequence on your machine.
Do not put SQL statements in exception, signal, and interrupt handlers. With these
kinds of error conditions, you normally want to do a ROLLBACK to avoid the risk
of inconsistent data. Before issuing a ROLLBACK, call the INTERRUPT API
(sqleintr/sqlgintr). This API interrupts the current SQL query (if the application
is executing one) and lets the ROLLBACK begin immediately.
Refer to your platform documentation for specific details on the various handler
considerations.

Disconnecting from embedded SQL applications

The disconnect statement is the final step you must take when you are working
with a database.

Disconnecting from DB2 databases in C and C++ Embedded SQL

applications
When working with C and C++ applications, a database connection is closed by
issuing the following statement:
EXEC SQL CONNECT RESET;

Starting in DB2 V10.1 Fix Pack 2 and later, if the application is precompiled using
COMPATIBILITY_MODE ORA, then following single statement extends syntaxes for
existing COMMIT and ROLLBACK statements to specify connection reset option:

Chapter 3. Programming

143

EXEC
EXEC
EXEC
EXEC

SQL
SQL
SQL
SQL

ROLLBACK RELEASE;
ROLLBACK WORK RELEASE;
COMMIT RELEASE;
COMMIT WORK RELEASE;

Users can achieve both ROLLBACK or COMMIT along with disconnection in a

single statement.

Disconnecting from DB2 databases in COBOL Embedded SQL

applications
When working with COBOL applications, a database connection is closed by
issuing the following statement:
EXEC SQL CONNECT RESET END-EXEC.

Disconnecting from DB2 databases in REXX Embedded SQL

applications
When working with REXX applications, a database connection is closed by issuing
the following statement:
CALL SQLEXEC CONNECT RESET

When working with FORTRAN applications, a database connection is closed by

issuing the following statement:
EXEC SQL CONNECT RESET

144

Developing Embedded SQL Applications

Chapter 4. Building embedded SQL applications

After you have created the source code for your embedded SQL application, you
must follow additional steps to build the application. You should consider building
64-bit executable files when developing new embedded SQL database applications.
Along with compiling and linking your program, you must precompile and bind
it.
The precompilation process converts embedded SQL statements into DB2 runtime
API calls that a host language compiler can process. By default, a package is
created at precompile time. Optionally, a bind file can be created at precompile
time. The bind file contains information about the SQL statements in the
application program. The bind file can be used later with the BIND command to
create a package for the application.
Binding is the process of creating a package from a bind file and storing it in a
database. The bind file must be bound to each database that needs to be accessed
by the application. If your application accesses more than one database, you must
create a package for each database.
To run applications written in compiled host languages, you must create the
packages needed by the database manager at execution time. The following figure
shows the order of these steps, along with the various modules of a typical
compiled DB2 application.:
1. Create source files that contain programs with embedded SQL statements.
2. Connect to a database, then precompile each source file to convert embedded
SQL source statements into a form the database manager can use.
Since the SQL statements placed in an application are not specific to the host
language, the database manager provides a way to convert the SQL syntax for
processing by the host language. For C, C++, COBOL, or FORTRAN languages,
this conversion is handled by the DB2 precompiler that is invoked using the
PRECOMPILE (or PREP) command. The precompiler converts embedded SQL
statements directly into DB2 run-time services API calls. When the precompiler
processes a source file, it specifically looks for SQL statements and avoids the
non-SQL host language.
3. Compile the modified source files (and other files without SQL statements)
using the host language compiler.
4. Link the object files with the DB2 and host language libraries to produce an
executable program.
Compiling and linking (steps 3 and 4) create the required object modules
5. Bind the bind file to create the package if this was not already done at
precompile time, or if a different database is going to be accessed. Binding
creates the package to be used by the database manager when the program is
run.
6. Run the application. The application accesses the database using the access
plans.

Copyright IBM Corp. 1993, 2013

145

Source Files
With SQL
Statements

Precompiler
(db2 PREP)

Source Files
Without SQL
Statements

BINDFILE
Create a
Bind File

Modified
Source Files

Host Language Compiler

Object
Files

Libraries

PACKAGE
Create a
Package

Host Language Linker

Executable
Program

Bind
File

Database Manager Package

Binder
(db2 BIND)

(Package)

Figure 3. Preparing Programs Written in Compiled Host Languages

Precompilation of embedded SQL applications with the PRECOMPILE

command
After you create the source files for an embedded SQL application, you must
precompile each host language file containing SQL statements with the PREP
command, using the options specific to the host language.
The precompiler converts SQL statements contained in the source file to comments,
and generates the DB2 runtime API calls for those statements.

146

Developing Embedded SQL Applications

You must always precompile a source file against a specific database, even if
eventually you do not use the database with the application. In practice, you can
use a test database for development, and after you fully test the application, you
can bind its bind file to one or more production databases. This practice is known
as deferred binding.
Note: Running an embedded application on an older client version than the client
where precompilation occurred is not supported, regardless of where the
application was compiled. For example, it is not supported to precompile an
embedded application on a DB2 V9.5 client and then attempt to run the
application on a DB2 V9.1 client.
If your application uses a code page that is not the same as your database code
page, you need to consider which code page to use when precompiling.
If your application uses user-defined functions (UDFs) or user-defined distinct
types (UDTs), you might need to use the FUNCPATH parameter when you precompile
your application. This parameter specifies the function path that is used to resolve
UDFs and UDTs for applications containing static SQL. If FUNCPATH is not specified,
the default function path is SYSIBM, SYSFUN, USER, where USER refers to the
current user ID.
Before precompiling an application you must connect to a server, either implicitly
or explicitly. Although you precompile application programs at the client
workstation and the precompiler generates modified source and messages on the
client, the precompiler uses the server connection to perform some of the
validation.
The precompiler also creates the information the database manager needs to
process the SQL statements against a database. This information is stored in a
package, in a bind file, or in both, depending on the precompiler options selected.
A typical example of using the precompiler follows. To precompile a C embedded
SQL source file called filename.sqc, you can issue the following command to
create a C source file with the default name filename.c and a bind file with the
default name filename.bnd:
DB2 PREP filename.sqc BINDFILE

The precompiler generates up to four types of output:

Modified Source
This file is the new version of the original source file after the precompiler
converts the SQL statements into DB2 runtime API calls. It is given the
appropriate host language extension.
Package
If you use the PACKAGE parameter (the default), or do not specify any of the
BINDFILE, SYNTAX, or SQLFLAG parameters, the package is stored in the
connected database. The package contains all the information required to
issue the static SQL statements of a particular source file against this
database only. Unless you specify a different name with the PACKAGE USING
parameter, the precompiler forms the package name from the first 8
characters of the source file name.
If you use the PACKAGE parameter without SQLERROR CONTINUE, the database
used during the precompile process must contain all of the database

Chapter 4. Building

147

objects referenced by the static SQL statements in the source file. For
example, you cannot precompile a SELECT statement unless the table it
references exists in the database.
With the VERSION parameter, the bind file (if the BINDFILE parameter is
used) and the package (either if bound at PREP time or if bound separately)
is designated with a particular version identifier. Many versions of
packages with the same name and creator can exist at once.
Bind File
If you use the BINDFILE parameter, the precompiler creates a bind file (with
extension .bnd) that contains the data required to create a package. This
file can be used later with the BIND command to bind the application to
one or more databases. If you specify BINDFILE and do not specify the
PACKAGE parameter, binding is deferred until you invoke the BIND
command. Note that for the command line processor (CLP), the default for
PREP does not specify the BINDFILE parameter. Thus, if you are using the
CLP and want the binding to be deferred, you need to specify the BINDFILE
parameter.
Specifying SQLERROR CONTINUE creates a package, even if errors occur when
binding SQL statements. Those statements that fail to bind for
authorization or existence reasons can be incrementally bound at execution
time if VALIDATE RUN is also specified. Any attempt to issue them at run
time generates an error.
Message File
If you use the MESSAGES parameter, the precompiler redirects messages to
the indicated file. These messages include warning and error messages that
describe problems encountered during precompilation. If the source file
does not precompile successfully, use the warning and error messages to
determine the problem, correct the source file, and then attempt to
precompile the source file again. If you do not use the MESSAGES parameter,
precompilation messages are written to the standard output.

Precompilation of embedded SQL applications that access

more than one database server
You must write your embedded SQL applications such that the application is able
to distinguish which database server receives each SQL statement.
To precompile an application program that accesses more than one server, you can
do one of the following tasks:
v Split the SQL statements for each database into separate source files. Do not mix
SQL statements for different databases in the same file. Each source file can be
precompiled against the appropriate database. This is the recommended method.
v Code your application using dynamic SQL statements only, and bind against
each database your program will access.
v If all the databases look the same, that is, they have the same definition, you can
group the SQL statements together into one source file.
The same procedures apply if your application will access a host application server
through DB2 Connect. Precompile it against the server to which it will be
connecting, using the PREP options available for that server.

148

Developing Embedded SQL Applications

Embedded SQL application packages and access plans

The precompiler produces a package in the database. The package contains access
plans selected by the DB2 optimizer for the static SQL statements in your
application. You can optionally specify if you also want a bind file generated.
The access plans contain the information required by the database manager to
issue the static SQL statements in the most efficient manner as determined by the
optimizer. For dynamic SQL statements, the optimizer creates access plans when
you run your application.
Packages stored in the database include information needed to issue specific SQL
statements in a single source file. A database application uses one package for
every precompiled source file used to build the application. Each package is a
separate entity, and has no relationship to any other packages used by the same or
other applications. Packages are created by running the precompiler against a
source file with binding enabled, or by running the binder at a later time with one
or more bind files.
The bind file contains the SQL statements and other data required to create a
package. You can use the bind file to re-bind your application later without having
to precompile it first. The re-binding creates packages that are optimized for
current database conditions. You need to re-bind your application if it will access a
different database from the one against which it was precompiled.

Package schema qualification using CURRENT PACKAGE

PATH special register
Package schemas provide a method for logically grouping packages. Different
approaches exist for grouping packages into schemas.
Some implementations use one schema per environment (for example, a
production and a test schema). Other implementations use one schema per
business area (for example, stocktrd and onlinebnk schemas), or one schema per
application (for example, stocktrdAddUser and onlinebnkAddUser). You can also
group packages for general administration purposes, or to provide variations in the
packages (for example, maintaining backup variations of applications, or testing
new variations of applications).
When multiple schemas are used for packages, the database manager must
determine in which schema to look for a package. To accomplish this task, the
database manager uses the value of the CURRENT PACKAGESET special register.
You can set this special register to a single schema name to indicate that any
package to be invoked belongs to that schema. If an application uses packages in
different schemas, a SET CURRENT PACKAGESET statement might have to be
issued before each package is invoked if the schema for the package is different
from that of the previous package.
Note: Only DB2 Version 9.1 for z/OS (DB2 for z/OS) has a CURRENT
PACKAGESET special register, which allows you to explicitly set the value (a
single schema name) with the corresponding SET CURRENT PACKAGESET
statement. Although DB2 for Linux, UNIX, and Windows has a SET CURRENT
PACKAGESET statement, it does not have a CURRENT PACKAGESET special
register. This means that CURRENT PACKAGESET cannot be referenced in other
contexts (such as in a SELECT statement) with DB2 for Linux, UNIX, and
Windows. DB2 for i does not provide support for CURRENT PACKAGESET.
Chapter 4. Building

149

The DB2 database server has more flexibility when it can consider a list of schemas
during package resolution. The list of schemas is similar to the SQL path that is
provided by the CURRENT PATH special register. The schema list is used for
user-defined functions, procedures, methods, and distinct types.
Note: The SQL path is a list of schema names that DB2 should consider when
trying to determine the schema for an unqualified function, procedure, method, or
distinct type name.
If you need to associate multiple variations of a package (that is, multiple sets of
BIND options for a package) with a single compiled program, consider isolating
the path of schemas that are used for SQL objects from the path of schemas that
are used for packages.
The CURRENT PACKAGE PATH special register allows you to specify a list of
package schemas. Other DB2 family products provide similar capability with
special registers such as CURRENT PATH and CURRENT PACKAGESET, which
are pushed and popped for nested procedures and user-defined functions without
corrupting the runtime environment of the invoking application. The CURRENT
PACKAGE PATH special register provides this capability for package schema
resolution.
Many installations use more than one schema for packages. If you do not specify a
list of package schemas, you must issue the SET CURRENT PACKAGESET
statement (which can contain at most one schema name) each time you require a
package from a different schema. If, however, you issue a SET CURRENT
PACKAGE PATH statement at the beginning of the application to specify a list of
schema names, you do not need to issue a SET CURRENT PACKAGESET
statement each time a package in a different schema is needed.
For example, assume that the following packages exist, and, using the following
list, that you want to invoke the first one that exists on the server:
SCHEMA1.PKG1, SCHEMA2.PKG2, SCHEMA3.PKG3, SCHEMA.PKG, and
SCHEMA5.PKG5. Assuming the current support for a SET CURRENT
PACKAGESET statement in DB2 for Linux, UNIX, and Windows (that is, accepting
a single schema name), a SET CURRENT PACKAGESET statement have to be
issued before trying to invoke each package to specify the specific schema. For this
example, five SET CURRENT PACKAGESET statements need to be issued.
However, using the CURRENT PACKAGE PATH special register, a single SET
statement is sufficient. For example:
SET CURRENT PACKAGE PATH = SCHEMA1, SCHEMA2, SCHEMA3, SCHEMA, SCHEMA5;

Note: In DB2 for Linux, UNIX, and Windows, you can set the CURRENT
PACKAGE PATH special register in the db2cli.ini file, by using the
SQLSetConnectAttr API, in the SQLE-CLIENT-INFO structure, and by including
the SET CURRENT PACKAGE PATH statement in embedded SQL programs. Only
DB2 for z/OS, Version 8 or later, supports the SET CURRENT PACKAGE PATH
statement. If you issue this statement against a DB2 for Linux, UNIX, and
Windows server or against DB2 for i, -30005 is returned.
You can use multiple schemas to maintain several variations of a package. These
variations can be a very useful in helping to control changes made in production
environments. You can also use different variations of a package to keep a backup
version of a package, or a test version of a package (for example, to evaluate the

150

Developing Embedded SQL Applications

impact of a new index). A previous version of a package is used in the same way
as a backup application (load module or executable), specifically, to provide the
ability to revert to a previous version.
For example, assume the PROD schema includes the current packages used by the
production applications, and the BACKUP schema stores a backup copy of those
packages. A new version of the application (and thus the packages) are promoted
to production by binding them using the PROD schema. The backup copies of the
packages are created by binding the current version of the applications using the
backup schema (BACKUP). Then, at runtime, you can use the SET CURRENT
PACKAGE PATH statement to specify the order in which the schemas should be
checked for the packages. Assume that a backup copy of the application MYAPPL
has been bound using the BACKUP schema, and the version of the application
currently in production has been bound to the PROD schema creating a package
PROD.MYAPPL. To specify that the variation of the package in the PROD schema
should be used if it is available (otherwise the variation in the BACKUP schema is
used), issue the following SET statement for the special register:
SET CURRENT PACKAGE PATH = PROD, BACKUP;

If you need to revert to the previous version of the package, the production
version of the application can be dropped with the DROP PACKAGE statement,
which causes the old version of the application (load module or executable) that
was bound using the BACKUP schema to be invoked instead (application path
techniques could be used here, specific to each operating system platform).
Note: This example assumes that the only difference between the versions of the
package are in the BIND options that were used to create the packages (that is,
there are no differences in the executable code).
The application does not use the SET CURRENT PACKAGESET statement to select
the schema it wants. Instead, it allows DB2 to pick up the package by checking for
it in the schemas listed in the CURRENT PACKAGE PATH special register.
Note: The DB2 for z/OS precompile process stores a consistency token in the
DBRM (which can be set using the LEVEL option), and during package resolution
a check is made to ensure that the consistency token in the program matches the
package. Similarly, the DB2 for Linux, UNIX, and Windows bind process stores a
timestamp in the bind file. DB2 for Linux, UNIX, and Windows also supports a
LEVEL option.
Another reason for creating several versions of a package in different schemas
could be to cause different BIND options to be in affect. For example, you can use
different qualifiers for unqualified name references in the package.
Applications are often written with unqualified table names. This supports
multiple tables that have identical table names and structures, but different
qualifiers to distinguish different instances. For example, a test system and a
production system might have the same objects created in each, but they might
have different qualifiers (for example, PROD and TEST). Another example is an
application that distributes data into tables across different DB2 systems, with each
table having a different qualifier (for example, EAST, WEST, NORTH, SOUTH;
COMPANYA, COMPANYB; Y1999, Y2000, Y2001). With DB2 for z/OS, you specify
the table qualifier using the QUALIFIER option of the BIND command. When you
use the QUALIFIER option, users do not have to maintain multiple programs, each
of which specifies the fully qualified names that are required to access unqualified
tables. Instead, the correct package can be accessed at runtime by issuing the SET
Chapter 4. Building

151

CURRENT PACKAGESET statement from the application, and specifying a single

schema name. However, if you use SET CURRENT PACKAGESET, multiple
applications will still need to be kept and modified: each one with its own SET
CURRENT PACKAGESET statement to access the required package. If you issue a
SET CURRENT PACKAGE PATH statement instead, all of the schemas could be
listed. At execution time, DB2 could choose the correct package.
Note: DB2 for Linux, UNIX, and Windows also supports a QUALIFIER bind
option. However, the QUALIFIER bind option only affects static SQL or packages
that use the DYNAMICRULES option of the BIND command.

Precompiler generated timestamps

When an application is precompiled with binding enabled, the package and
modified source file are generated with matching timestamps. These timestamps
are individually known as a consistency token.
If multiple versions of a package exist (by using the PRECOMPILE VERSION option),
each version will have an associated timestamp. When the application is run, the
package name, creator and timestamp are sent to the database manager, which
checks for a package whose name, creator and timestamp match that sent by the
application. If such a match does not exist, one of the two following SQL error
codes is returned to the application:
v SQL0818N (timestamp conflict). This error is returned if a single package is
found that matches the name and creator (but not the consistency token), and
the package has a version of "" (an empty string)
v SQL0805N (package not found). This error is returned in all other situations.
Remember that when you bind an application to a database, the first eight
characters of the application name are used as the package name unless you
override the default by using the PACKAGE USING parameter on the PREP command.
As well, the version ID will be "" (an empty string) unless it is specified by the
VERSION parameter of the PREP command. This means that if you precompile and
bind two programs using the same name without changing the version ID, the
second package will replace the package of the first. When you run the first
program, you will get a timestamp or a package not found error because the
timestamp for the modified source file no longer matches that of the package in
the database. The package not found error can also result from the use of the
ACTION REPLACE REPLVER precompile or bind option as in the following example:
1. Precompile and bind the package SCHEMA1.PKG specifying VERSION VER1. Then
generate the associated application A1.
2. Precompile and bind the package SCHEMA1.PKG, specifying VERSION VER2 ACTION
REPLACE REPLVER VER1. Then generate the associated application A2.
The second precompile and bind generates a package SCHEMA1.PKG that has a
VERSION of VER2, and the specification of ACTION REPLACE REPLVER VER1 removes
the SCHEMA1.PKG package that had a VERSION of VER1.
An attempt to run the first application will result in a package mismatch and
will fail.
A similar symptom will occur in the following example:
1. Precompile and bind the package SCHEMA1.PKG, specifying VERSION VER1. Then
generate the associated application A1
2. Precompile and bind the package SCHEMA1.PKG, specifying VERSION VER2. Then
generate the associated application A2

152

Developing Embedded SQL Applications

At this point it is possible to run both applications A1 and A2, which will be
executed from packages SCHEMA1.PKG versions VER1 and VER2. If, for example,
the first package is dropped (using the DROP PACKAGE SCHEMA1.PKG
VERSION VER1 SQL statement), an attempt to run the application A1 will fail
with a package not found error.
When a source file is precompiled but a package is not created, a bind file and
modified source file are generated with matching timestamps. To run the
application, the bind file is bound in a separate BIND step to create a package and
the modified source file is compiled and linked. For an application that requires
multiple source modules, the binding process must be done for each bind file.
In this deferred binding scenario, the application and package timestamps match
because the bind file contains the same timestamp as the one that was stored in
the modified source file during precompilation.

Errors and warnings from precompilation of embedded SQL

applications
Embedded SQL errors at precompile time are detected by the embedded SQL
precompiler. The embedded SQL precompiler detects syntax errors such as missing
semicolons and undeclared host variables in SQL statements. For each of these
errors, an appropriate error message is generated.

Compiling and linking source files containing embedded SQL

You can precompile embedded SQL programs using the PRECOMPILE command. You
must then compile and link the resultant modified source files with the
appropriate host language compiler.

About this task

When precompiling embedded SQL source files, the PRECOMPILE command
generates modified source files with a file extension applicable to the programming
language.
Compile the modified source files (and any additional source files that do not
contain SQL statements) using the appropriate host language compiler. The
language compiler converts each modified source file into an object module.
Refer to the programming documentation for your operating platform for any
exceptions to the default compiler options. Refer to your compiler's documentation
for a complete description of available compiler options.
The host language linker creates an executable application. For example:
v On Windows operating systems, the application can be an executable file or a
dynamic link library (DLL).
v On UNIX and Linux based operating systems, the application can be an
executable load module or a shared library.
Note: Although applications can be DLLs on Windows operating systems, the
DLLs are loaded directly by the application and not by the DB2 database manager.
On Windows operating systems, the database manager loads embedded SQL
stored procedures and user-defined functions as DLLs.
To create the executable file, link the following objects:
Chapter 4. Building

153

v User object modules, generated by the language compiler from the modified
source files and other files not containing SQL statements.
v Host language library APIs, supplied with the language compiler.
v The database manager library containing the database manager APIs for your
operating environment. Refer to the appropriate programming documentation
for your operating platform for the specific name of the database manager
library you need for your database manager APIs.

Binding embedded SQL packages to a database

Binding is the process of creating a package from a bind file and storing it in a
database.

Application, bind file, and package relationships

Database applications use packages for some of the same reasons that applications
are compiled: improved performance and compactness. By precompiling an SQL
statement, the statement is compiled into the package when the application is built,
instead of at run time. Each statement is parsed, and a more efficiently interpreted
operand string is stored in the package. At run time, the code generated by the
precompiler calls run-time services database manager APIs with any variable
information required for input or output data, and the information stored in the
package is executed.
The advantages of precompilation apply only to static SQL statements. SQL
statements that are executed dynamically (using PREPARE and EXECUTE or
EXECUTE IMMEDIATE) are not precompiled; therefore, they must go through the
entire set of processing steps at run time.
With the DB2 bind file description (db2bfd) utility, you can easily display the
contents of a bind file to examine and verify the SQL statements within it. You can
also display the precompile options used to create the bind file using the DB2 bind
file description (db2bfd) utility. This can be useful in problem determination related
to the bind file for your application.
You can set the STATICASDYNAMIC string on the GENERIC parameter of the BIND
command to "yes" to instruct the DB2 database manager to store all statements in
the catalogs and mark them as incremental bind. At run time, when the package is
first loaded, the database manager uses the current session environment (rather
than the package) to set up the section entries and other entities (text is populated
and the package cache is accessed). Thereafter, the statements in the bound file
behave the same as they would if you were using dynamic SQL. For example,
sections will be implicitly recompiled for Database Definition Language
invalidations, special register updates, and so on. The DB2 database manager
provides this feature to facilitate the migration of embedded SQL C applications
from other database systems.

Effect of DYNAMICRULES bind option on dynamic SQL

The PRECOMPILE command and BIND command parameter DYNAMICRULES determines
which rules apply to dynamic SQL at run time.
In particular, the DYNAMICRULES parameter determines what values apply at run
time for the following dynamic SQL attributes:
v The authorization ID that is used during authorization checking.

154

Developing Embedded SQL Applications

v The qualifier that is used for qualification of unqualified objects.

v Whether the package can be used to dynamically prepare the following
statements: GRANT, REVOKE, ALTER, CREATE, DROP, COMMENT ON,
RENAME, SET INTEGRITY, and SET EVENT MONITOR STATE statements.
In addition to the DYNAMICRULES value, the runtime environment of a package
controls how dynamic SQL statements behave at run time. The two possible
runtime environments are:
v The package runs as part of a stand-alone program
v The package runs within a routine context
The combination of the DYNAMICRULES value and the runtime environment
determine the values for the dynamic SQL attributes. That set of attribute values is
called the dynamic SQL statement behavior. The four behaviors are:
Run behavior
DB2 for Linux, UNIX, and Windows uses the authorization ID of the user
(the ID that initially connected to the DB2 database) executing the package
as the value to be used for authorization checking of dynamic SQL
statements and for the initial value used for implicit qualification of
unqualified object references within dynamic SQL statements.
Bind behavior
At run time, DB2 for Linux, UNIX, and Windows uses all the rules that
apply to static SQL for authorization and qualification. That is, take the
authorization ID of the package owner as the value to be used for
authorization checking of dynamic SQL statements and the package default
qualifier for implicit qualification of unqualified object references within
dynamic SQL statements.
Define behavior
Define behavior applies only if the dynamic SQL statement is in a package
that is run within a routine context, and the package was bound with
DYNAMICRULES DEFINEBIND or DYNAMICRULES DEFINERUN. DB2 for Linux,
UNIX, and Windows uses the authorization ID of the routine definer (not
the routine's package binder) as the value to be used for authorization
checking of dynamic SQL statements and for implicit qualification of
unqualified object references within dynamic SQL statements within that
routine.
Invoke behavior
Invoke behavior applies only if the dynamic SQL statement is in a package
that is run within a routine context, and the package was bound with
DYNAMICRULES INVOKEBIND or DYNAMICRULES INVOKERUN. DB2 for Linux,
UNIX, and Windows uses the current statement authorization ID in effect
when the routine is invoked as the value to be used for authorization
checking of dynamic SQL and for implicit qualification of unqualified
object references within dynamic SQL statements within that routine. This
is summarized by the following table:
Invoking Environment

ID Used

Any static SQL

Implicit or explicit value of the OWNER of the

package the SQL invoking the routine came
from.

Used in definition of view or trigger

Definer of the view or trigger.

Chapter 4. Building

155

Invoking Environment

ID Used

Dynamic SQL from a run behavior package

ID used to make the initial connection to the

DB2 database.

Dynamic SQL from a define behavior

package

Definer of the routine that uses the package

that the SQL invoking the routine came
from.

Dynamic SQL from an invoke behavior

package

Current authorization ID invoking the

routine.

The following table shows the combination of the DYNAMICRULES value and the
runtime environment that yields each dynamic SQL behavior.
Table 18. How DYNAMICRULES and the Runtime Environment Determine Dynamic SQL Statement Behavior
DYNAMICRULES Value

Behavior of Dynamic SQL

Statements in a Standalone Program
Environment

Behavior of Dynamic SQL Statements in

a Routine Environment

BIND

Bind behavior

Bind behavior

RUN

Run behavior

Run behavior

DEFINEBIND

Bind behavior

Define behavior

DEFINERUN

Run behavior

Define behavior

INVOKEBIND

Bind behavior

Invoke behavior

INVOKERUN

Run behavior

Invoke behavior

The following table shows the dynamic SQL attribute values for each type of
dynamic SQL behavior.
Table 19. Definitions of Dynamic SQL Statement Behaviors
Dynamic SQL
Attribute

Setting for Dynamic Setting for Dynamic Setting for Dynamic

SQL Attributes:
SQL Attributes: Run SQL Attributes:
Bind Behavior
Behavior
Define Behavior

Setting for Dynamic SQL

Attributes: Invoke
Behavior

Authorization ID

The implicit or
ID of User Executing Routine definer (not
the routine's package
explicit value of the Package
BIND OWNER command
owner)
parameter

Current statement
authorization ID when
routine is invoked.

Default qualifier
for unqualified
objects

The implicit or
explicit value of the
BIND QUALIFIER
command parameter

No
Can execute
GRANT,
REVOKE, ALTER,
CREATE, DROP,
COMMENT ON,
RENAME, SET
INTEGRITY, and
SET EVENT
MONITOR STATE

156

Developing Embedded SQL Applications

CURRENT
SCHEMA Special
Register

Routine definer (not

the routine's package
owner)

Current statement
authorization ID when
routine is invoked.

Yes

No

No

Using special registers to control the statement compilation

environment
For dynamically prepared statements, the special registers can be specified to
define the statement compilation environment.
Following special registers controls the statement compilation environment:
v The CURRENT QUERY OPTIMIZATION special register determines which
optimization class is used.
v The CURRENT PATH special register determines the function path used for
UDF and UDT resolution.
v The CURRENT EXPLAIN SNAPSHOT register determines whether explain
snapshot information is captured.
v The CURRENT EXPLAIN MODE register determines whether explain table
information is captured for any eligible dynamic SQL statement. The default
values for these special registers are the same defaults used for the related bind
options.

Package recreation using the BIND command and an existing

bind file
Binding is the process that creates the package the database manager needs to
access the database when the application is executed.
By default the PRECOMPILE command creates a package. Binding is done implicitly
at precompile time unless the BINDFILE command parameter is specified. The
PACKAGE command parameter allows you to specify a package name for the
package created at precompile time.
A typical example of using the BIND command follows. To bind a bind file named
filename.bnd to the database, you can issue the following command:
BIND filename.bnd

One package is created for each separately precompiled source code module. If an
application has five source files, of which three require precompilation, three
packages or bind files are created. By default, each package is given a name that is
the same as the name of the source module from which the .bnd file originated,
but truncated to 8 characters. To explicitly specify a different package name, you
must use the PACKAGE USING parameter on the PREP command. The version of a
package is given by the VERSION precompile parameter and defaults to the empty
string. If the name and schema of this newly created package is the same as a
package that currently exists in the target database, but the version identifier
differs, a new package is created and the previous package still remains. However
if a package exists that matches the name, schema and the version of the package
being bound, then that package is dropped and replaced with the new package
being bound (specifying ACTION ADD on the bind would prevent that and an error
(SQL0719) would be returned instead).

Rebinding existing packages with the REBIND command

Rebinding is the process of recreating a package for an application program that
was previously bound. You must rebind packages if they were marked invalid or
inoperative or if the database statistics changed since the last binding.

Chapter 4. Building

157

In some situations, however, you might want to rebind packages that are valid. For
example, you might want to take advantage of a newly created index, or use
updated statistics after executing the RUNSTATS command.
Packages can be dependent on certain types of database objects such as tables,
views, aliases, indexes, triggers, referential constraints, and table check constraints.
If a package is dependent on a database object (such as a table, view, trigger, and
so on), and that object is dropped, the package is placed into an invalid state. If the
object that is dropped is a UDF, the package is placed into an inoperative state.
When the package is marked inoperative, the next use of a statement in this
package causes an implicit rebind of the package using non-conservative binding
semantics in order to be able to resolve to SQL objects considering the latest
changes in the database schema that caused that package to become inoperative.
For static DML in packages, the packages can rebind implicitly, or by explicitly
issuing the REBIND command (or corresponding API), or the BIND command (or
corresponding API). The implicit rebind is performed with conservative binding
semantics if the package is marked invalid, but uses non-conservative binding
semantics when the package is marked inoperative.
You must use the BIND command to rebind a package for a program which was
modified to include more, fewer, or changed SQL statements. You must also use
the BIND command if you need to change any bind options from the values with
which the package was originally bound. The REBIND command provides the
option to resolve with conservative binding semantics (RESOLVE CONSERVATIVE) or
to resolve by considering new routines, data types, or global variables (RESOLVE
ANY, which is the default option). The RESOLVE CONSERVATIVE option can be used
only if the package was not marked inoperative by the database manager
(SQLSTATE 51028). You should use REBIND whenever your situation does not
specifically require the use of BIND, as the performance of REBIND is significantly
better than that of BIND.
When multiple versions of the same package name coexist in the catalog, only one
version can be rebound at a time.
In IBM Data Studio Version 3.1 or later, you can use the task assistant for
rebinding packages. Task assistants can guide you through the process of setting
options, reviewing the automatically generated commands to perform the task, and
running these commands. For more details, see Administering databases with task
assistants.

Bind considerations
If your application uses a code page that differs from the database code page, you
must ensure that the code page used by the application is compatible with the
database code page during the bind process.
If your application issues calls to any of the database manager utility APIs, such as
IMPORT or EXPORT, you must bind the supplied utility bind files to the database.
You can use bind options to control certain operations that occur during binding,
as in the following examples:
v The QUERYOPT bind parameter takes advantage of a specific optimization class
when binding.

158

Developing Embedded SQL Applications

v The EXPLSNAP bind parameter stores Explain Snapshot information for eligible
SQL statements in the Explain tables.
v The FUNCPATH bind parameter properly resolves user-defined distinct types and
user-defined functions in static SQL.
If the bind process starts but never returns, it might be that other applications
connected to the database hold locks that you require. In this case, ensure that no
applications are connected to the database. If they are, disconnect all applications
on the server and the bind process will continue.
If your application will access a server using DB2 Connect, you can use the BIND
command parameters available for that server.
Bind files are not compatible with earlier versions of DB2 for Linux, UNIX, and
Windows. In mixed-level environments, DB2 for Linux, UNIX, and Windows can
only use the functions available to the lowest level of the database environment.
For example, if a version 8 client connects to a version 7.2 server, the client will
only be able to use version 7.2 functions. As bind files express the functionality of
the database, they are subject to the mixed-level restriction.
If you need to rebind higher-level bind files on lower-level systems, you can:
v Use a lower level IBM data server client to connect to the higher-level server
and create bind files which can be shipped and bound to the lower-level DB2 for
Linux, UNIX, and Windows environment.
v Use a higher-level IBM data server client in the lower-level production
environment to bind the higher-level bind files that were created in the test
environment. The higher-level client passes only the options that apply to the
lower-level server.

Blocking considerations
When you want to turn blocking off for an embedded SQL application and the
source code is not available, the application must be rebound using the BIND
command and setting the BLOCKING NO clause.
Existing embedded SQL applications must be rebound using the BIND command
and setting the BLOCKING ALL or BLOCKING UNAMBIGUOUS clauses to request blocking
(if they are not already bound in this fashion). Embedded applications will retrieve
the LOB values from the server a row at a time, when a block of rows have been
retrieved from the server

Advantages of deferred binding

Precompiling with binding enabled allows an application to access only the
database used during the precompile process. Precompiling with binding deferred,
however, allows an application to access many databases, because you can bind the
BIND file against each database.
This method of application development is inherently more flexible in that
applications are precompiled only once, but the application can be bound to a
database at any time.
Using the BIND API during execution allows an application to bind itself, perhaps
as part of an installation procedure or before an associated module is executed. For
example, an application can perform several tasks, only one of which requires the
use of SQL statements. You can design the application to bind itself to a database
Chapter 4. Building

159

only when the application calls the task requiring SQL statements, and only if an
associated package does not already exist.
Another advantage of the deferred binding method is that it lets you create
packages without providing source code to end users. You can ship the associated
bind files with the application.

Performance improvements when using REOPT option of the

BIND command
The bind option REOPT can significantly improve the embedded SQL application
performance.

Effects of REOPT on static SQL

The bind option REOPT can make static SQL statements containing host variables,
global variables, or special registers behave like incremental-bind statements. This
means that these statements get compiled at the time of EXECUTE or OPEN
instead of at bind time. During this compilation, the access plan is chosen, based
on the real values of these variables.
With REOPT ONCE, the access plan is cached after the first OPEN or EXECUTE
request and is used for subsequent execution of this statement. With REOPT ALWAYS,
the access plan is regenerated for every OPEN and EXECUTE request, and the
current set of host variable, parameter marker, global variable, and special register
values is used to create this plan.

Effects of REOPT on dynamic SQL

When you specify the option REOPT ALWAYS, the database manager postpones
preparing any statement containing host variables, parameter markers, global
variables, or special registers until it encounters an OPEN or EXECUTE statement;
that is, when the values for these variables become known. At this time, the access
plan is generated using these values. Subsequent OPEN or EXECUTE requests for
the same statement will recompile the statement, reoptimize the query plan using
the current set of values for the variables, and execute the newly generated query
plan. When REOPT ALWAYS is specified, statement concentrator is disabled.
The option REOPT ONCE has a similar effect, with the exception that the plan is only
optimized once using the values of the host variables, parameter markers, global
variables, and special registers. This plan is cached and will be used by subsequent
requests.

Binding applications and utilities (DB2 Connect server)

Application programs developed using embedded SQL must be bound to each
database with which they will operate. For information about the binding
requirements for the IBM data server package, see the topic about DB2 CLI bind
files and package names.
Binding should be performed once per application, for each database. During the
bind process, database access plans are stored for each SQL statement that will be
executed. These access plans are supplied by application developers and are
contained in bind files which are created during precompilation. Binding is a
process of processing these bind files by an IBM mainframe database server.

160

Developing Embedded SQL Applications

Because several of the utilities supplied with DB2 Connect are developed using
embedded SQL, they must be bound to an IBM mainframe database server before
they can be used with that system. If you do not use the DB2 Connect utilities and
interfaces, you do not have to bind them to each of your IBM mainframe database
servers. The lists of bind files required by these utilities are contained in the
following files:
v
v
v
v

ddcsmvs.lst for System z

ddcsvse.lst for VSE
ddcsvm.lst for VM
ddcs400.lst for IBM Power Systems

Binding one of these lists of files to a database will bind each individual utility to
that database.
If a DB2 Connect server product is installed, the DB2 Connect utilities must be
bound to each IBM mainframe database server before they can be used with that
system. Assuming the clients are at the same fix pack level, you need to bind the
utilities only once, regardless of the number of client platforms involved.
For example, if you have 10 Windows clients, and 10 AIX clients connecting to DB2
for z/OS via DB2 Connect Enterprise Edition on a Windows server, perform one of
the following steps:
v Bind ddcsmvs.lst from one of the Windows clients.
v Bind ddcsmvs.lst from one of the AIX clients.
v Bind ddcsmvs.lst from the DB2 Connect server.
This example assumes that:
v All the clients are at the same service level. If they are not then, in addition, you
might need to bind from each client of a particular service level
v The server is at the same service level as the clients. If it is not, then you need to
bind from the server as well.
In addition to DB2 Connect utilities, any other applications that use embedded
SQL must also be bound to each database that you want them to work with. An
application that is not bound will usually produce an SQL0805N error message
when executed. You might want to create an additional bind list file for all of your
applications that need to be bound.
For each IBM mainframe database server that you are binding to, perform the
following steps:
1. Make sure that you have sufficient authority for your IBM mainframe database
server management system:
System z
The authorizations required are:
v SYSADM or
v SYSCTRL or
v BINDADD and CREATE IN COLLECTION NULLID
Note: The BINDADD and the CREATE IN COLLECTION NULLID
privileges provide sufficient authority only when the packages do not
already exist. For example, if you are creating them for the first time.

Chapter 4. Building

161

If the packages already exist, and you are binding them again, then the
authority required to complete the task(s) depends on who did the
original bind.
A) If you did the original bind and you are doing the bind again, then
having any of the previously listed authorities will allow you to
complete the bind.
B) If your original bind was done by someone else and you are doing
the second bind, then you will require either the SYSADM or the
SYSCTRL authorities to complete the bind. Having just the BINDADD
and the CREATE IN COLLECTION NULLID authorities will not allow
you to complete the bind. It is still possible to create a package if you
do not have either SYSADM or SYSCTRL privileges. In this situation
you would need the BIND privilege on each of the existing packages
that you intend to replace.
VSE or VM
The authorization required is DBA authority. If you want to use the
GRANT option on the bind command (to avoid granting access to each
DB2 Connect package individually), the NULLID user ID must have
the authority to grant authority to other users on the following tables:
v system.syscatalog
v system.syscolumns
v system.sysindexes
v system.systabauth
v system.syskeycols
v
v
v
v

system.syssynonyms
system.syskeys
system.syscolauth
system.sysuserauth

On the VSE or VM system, you can issue:

grant select on table to nullid with grant option

IBM Power Systems

*CHANGE authority or higher on the NULLID collection.
2. Issue commands similar to the following commands:
db2 connect to DBALIAS user USERID using PASSWORD
db2 bind [email protected] blocking all
sqlerror continue messages ddcsmvs.msg grant public
db2 connect reset

Where DBALIAS, USERID, and PASSWORD apply to the IBM mainframe

database server, ddcsmvs.lst is the bind list file for z/OS, and path represents
the location of the bind list file.
For example drive:\sqllib\bnd\ applies to all Windows operating systems,
and INSTHOME/sqllib/bnd/ applies to all Linux and UNIX operating systems,
where drive represents the logical drive where DB2 Connect was installed and
INSTHOME represents the home directory of the DB2 Connect instance.
You can use the grant option of the bind command to grant EXECUTE privilege
to PUBLIC or to a specified user name or group ID. If you do not use the grant
option of the bind command, you must GRANT EXECUTE (RUN) individually.
To find out the package names for the bind files, enter the following command:
ddcspkgn @bindfile.lst

162

Developing Embedded SQL Applications

For example:
ddcspkgn @ddcsmvs.lst

might yield the following output:

Bind File
Package Name
------------------------------ -----------------------------f:\sqllib\bnd\db2ajgrt.bnd
SQLAB6D3

To determine these values for DB2 Connect execute the ddcspkgn utility, for
example:
ddcspkgn @ddcsmvs.lst

Optionally, this utility can be used to determine the package name of

individual bind files, for example:
ddcspkgn bindfile.bnd

Note:
a. Using the bind option sqlerror continue is required; however, this option
is automatically specified for you when you bind applications using the
DB2 tools or the Command Line Processor (CLP). Specifying this option
turns bind errors into warnings, so that binding a file containing errors can
still result in the creation of a package. In turn, this allows one bind file to
be used against multiple servers even when a particular server
implementation might flag the SQL syntax of another to be invalid. For this
reason, binding any of the list files ddcsxxx.lst against any particular IBM
mainframe database server should be expected to produce some warnings.
b. If you are connecting to a DB2 database through DB2 Connect, use the bind
list db2ubind.lst and do not specify sqlerror continue, which is only valid
when connecting to a IBM mainframe database server. Also, to connect to a
DB2 database, it is recommended that you use the DB2 clients provided
with DB2 and not DB2 Connect.
3. Use similar statements to bind each application or list of applications.
4. If you have remote clients from a previous release of DB2, you might need to
bind the utilities on these clients to DB2 Connect.

Package storage and maintenance

You can create packages by precompiling and binding an application program. The
package contains an optimized access plan that oversees the execution of all of the
SQL statements found within the application.
The three types of privileges that deal with packages are the CONTROL, EXECUTE, and
BIND privilege and they are used to filter the level of access acceptable. Multiple
versions of the same package can be created by specifying the VERSION option at
compile time. This option helps prevent the mismatched timestamp error and
allows for multiple versions of the application to run simultaneously.

Package versioning
If you need to create multiple versions of an application, you can use the VERSION
parameter in the PRECOMPILE command. This option allows multiple versions of the
same package name (that is, the package name and creator name) to coexist.
For example, assume that you have an application called foo1, which is compiled
from foo1.sqc. You would precompile and bind the package foo1 to the database
and deliver the application to the users. The users could then run the application.
Chapter 4. Building

163

To make subsequent changes to the application, you would update foo1.sqc, then
repeat the process of recompiling, binding, and sending the application to the
users. If the VERSION parameter was not specified for either the first or second
precompilation of foo1.sqc, the first package is replaced by the second package.
Any user who attempts to run the old version of the application will receive the
SQLCODE -818, indicating a mismatched timestamp error.
To avoid the mismatched timestamp error and in order to allow both versions of
the application to run at the same time, use package versioning. As an example,
when you build the first version of foo1, precompile it using the VERSION
parameter, as follows:
DB2 PREP FOO1.SQC VERSION V1.1

This first version of the program may now be run. When you build the new
version of foo1, precompile it with the command:
DB2 PREP FOO1.SQC VERSION V1.2

At this point this new version of the application will also run, even if there still are
instances of the first application still executing. Because the package version for the
first package is V1.1 and the package version for the second is V1.2, no naming
conflict exists: both packages will exist in the database and both versions of the
application can be used.
You can use the ACTION parameter of the PRECOMPILE or BIND commands with the
VERSION parameter of the PRECOMPILE command. You use the ACTION parameter to
control the way in which different versions of packages can be added or replaced.
Package privileges do not have granularity at the version level. That is, a GRANT
or a REVOKE of a package privilege applies to all versions of a package that share
the name and creator. So, if package privileges on package foo1 were granted to a
user or a group after version V1.1 was created, when version V1.2 is distributed
the user or group has the same privileges on version V1.2. This behavior is usually
required because typically the same users and groups have the same privileges on
all versions of a package. If you do not want the same package privileges to apply
to all versions of an application, you should not use the PRECOMPILE VERSION
parameter to accomplish package versioning. Instead, you should use different
package names (either by renaming the updated source file, or by using the
PACKAGE USING parameter to explicitly rename the package).

Resolution of unqualified table names

You can handle unqualified table names in your application by binding user
packages with COLLECTION parameters, or by creating views or aliases.
Use one of the following methods to handle unqualified table names:
v Each user can bind their package with different COLLECTION parameters using
different authorization identifiers by using the following commands:
CONNECT TO db_name USER user_name
BIND file_name COLLECTION schema_name

In this example, db_name is the name of the database, user_name is the name of
the user, and file_name is the name of the application that will be bound. Note
that user_name and schema_name are typically the same value. Then use the SET
CURRENT PACKAGESET statement to specify which package to use, and
therefore, which qualifiers will be used. If COLLECTION is not specified, then the
default qualifier is the authorization identifier that is used when binding the

164

Developing Embedded SQL Applications

package. If COLLECTION is specified, then the schema_name specified is the

qualifier that will be used for unqualified objects.
v Create a public alias to point to the required table.
v Create views for each user with the same name as the table so the unqualified
table names resolve correctly.
v Create an alias for each user to point to the required table.

Building embedded SQL applications using the sample build script

The files used to demonstrate building sample programs are called script files on
UNIX and Linux operating systems, and batch files on Windows operating
systems. These files are collectively called build files and contain the recommended
compile and link commands for supported platform compilers.
Build files are provided by DB2 for host languages pertaining to supported
platforms. The build files are available in the same directory to where the samples
for that language are contained. The following table lists the different types of
build files for building different types of programs. These build files, unless
otherwise indicated, are for supported languages on all supported platforms. The
build files have the .bat (batch) extension on Windows, which is not included in
the table. There is no extension for UNIX platforms.
Table 20. DB2 build files
Build file

Types of programs built

bldapp

Application programs

bldrtn

Routines (stored procedures and UDFs)

bldmc

C/C++ multi-connection applications

bldmt

C/C++ multi-threaded applications

bldcli

CLI client applications for SQL procedures in the sqlpl samples

sub-directory.

Note: By default the bldapp sample scripts for building executables from source
code will build 64-bit executables.
The following table lists the build files by platform and programming language,
and the directories where they are located. In the online documentation, the build
file names are hot-linked to the source files in HTML. The user can also access the
text files in the appropriate samples directories.
Table 21. Build files by language and platform
Platform >
Language
C
samples/c

AIX

HP-UX

Linux

Solaris

Windows

bldapp
bldrtn
bldmt
bldmc

bldapp
bldrtn
bldmt
bldmc

bldapp
bldrtn
bldmt
bldmc

bldapp
bldrtn
bldmt
bldmc

bldapp.bat
bldrtn.bat
bldmt.bat
bldmc.bat

Chapter 4. Building

165

Table 21. Build files by language and platform (continued)

Platform >
Language

AIX

HP-UX

Linux

Solaris

Windows

C++
samples/cpp

bldapp
bldrtn
bldmt
bldmc

bldapp
bldrtn
bldmt
bldmc

bldapp
bldrtn
bldmt
bldmc

bldapp
bldrtn
bldmt
bldmc

bldapp.bat
bldrtn.bat
bldmt.bat
bldmc.bat

n/a

n/a

n/a

IBM COBOL
samples/cobol

bldapp
bldrtn

Micro Focus COBOL

samples/cobol_mf

bldapp
bldrtn

bldapp.bat
bldrtn.bat
bldapp
bldrtn

bldapp
bldrtn

bldapp
bldrtn

bldapp.bat
bldrtn.bat

The build files are used in the documentation for building applications and
routines because they demonstrate very clearly the compile and link options that
DB2 recommends for the supported compilers. There are generally many other
compile and link options available, and users are free to experiment with them. See
your compiler documentation for all the compile and link options provided.
Besides building the sample programs, developers can also build their own
programs with the build files. The sample programs can be used as templates that
can be modified by users to assist in their application development.
Conveniently, the build files are designed to build a source file with any file name
allowed by the compiler. This is unlike the makefiles, where the program names
are hardcoded into the file. The makefiles access the build files for compiling and
linking the programs they make. The build files use the $1 variable on UNIX and
Linux and the %1 variable on Windows operating systems to substitute internally
for the program name. Incremented numbers for these variable names substitute
for other arguments that might be required.
The build files allow for quick and easy experimentation, as each one is suited to a
specific kind of program-building, such as stand-alone applications, routines
(stored procedures and UDFs) or more specialized program types such as
multi-connection or multi-threaded programs. Each type of build file is provided
wherever the specific kind of program it is designed for is supported by the
compiler.
The object and executable files produced by a build file are automatically
overwritten each time a program is built, even if the source file is not modified.
This is not the case when using a makefile. It means a developer can rebuild an
existing program without having to delete previous object and executable files, or
modifying the source.
The build files contain a default setting for the sample database. If the user is
accessing another database, they can simply supply another parameter to override
the default. If they are using the other database consistently, they could hardcode
this database name, replacing sample, within the build file itself.
For embedded SQL programs, except when using the IBM COBOL precompiler on
Windows, the build files call another file, embprep, that contains the precompile

166

Developing Embedded SQL Applications

and bind steps for embedded SQL programs. These steps might require the
optional parameters for user ID and password, depending on where the embedded
SQL program is being built.
Finally, the build files can be modified by the developer for his or her convenience.
Besides changing the database name in the build file (explained previously) the
developer can easily hardcode other parameters within the file, change compile
and link options, or change the default DB2 instance path. The simple,
straightforward, and specific nature of the build files makes tailoring them to your
needs an easy task.

Error-checking utilities
The DB2 Client provides several utility files. The utility files contain functions that
you can use for error checking and printing out error information. Utility files are
provided for each language in the samples directory.
When used with an application program, the error-checking utility files provide
helpful error information, and make debugging a DB2 program much easier. Most
of the error-checking utilities use the DB2 APIs GET SQLSTATE MESSAGE (sqlogstt)
and GETERROR MESSAGE (sqlaintp) to obtain pertinent SQLSTATE and SQLCA
information related to problems encountered in program execution. The CLI utility
file, utilcli.c, does not use these DB2 APIs; instead it uses equivalent CLI
statements. With all the error-checking utilities, descriptive error messages are
printed out to allow the developer to quickly understand the problem. Some DB2
programs, such as routines (stored procedures and user-defined functions), do not
need to use the utilities.
Here are the error-checking utility files used by DB2 supported compilers for the
different programming languages:
Table 22. Error-checking utility files by language
Language

Non-embedded
SQL source file

Non-embedded
SQL header file

Embedded SQL
source file

Embedded SQL
header file

utilapi.c

utilapi.h

utilemb.sqc

utilemb.h

utilapi.C

utilapi.h

utilemb.sqC

utilemb.h

checkerr.cbl

n/a

n/a

n/a

checkerr.cbl

n/a

n/a

n/a

C
samples/c
C++
samples/cpp
IBM COBOL
samples/cobol
Micro Focus COBOL
samples/cobol_mf

In order to use the utility functions, the utility file must first be compiled, and then
its object file linked in during the creation of the target program's executable file.
Both the makefile and build files in the samples directories do this for the
programs that require the error-checking utilities.
The example demonstrates how the error-checking utilities are used in DB2
programs. The utilemb.h header file defines the EMB_SQL_CHECK macro for the
functions SqlInfoPrint() and TransRollback():
Chapter 4. Building

167

/* macro for embedded SQL checking */

#define EMB_SQL_CHECK(MSG_STR)
SqlInfoPrint(MSG_STR, &sqlca, __LINE__, __FILE__);
if (sqlca.sqlcode < 0)
{
TransRollback();
return 1;
}

\
\
\
\
\
\

SqlInfoPrint() checks the SQLCODE and prints out any available information
related to the specific error encountered. It also points to where the error occurred
in the source code. TransRollback() allows the utility file to safely rollback a
transaction where an error has occurred. It uses the embedded SQL statement EXEC
SQL ROLLBACK. The example demonstrates how the C program dbuse calls the utility
functions by using the macro, supplying the value "Delete with host variables
-- Execute" for the MSG_STR parameter of the SqlInfoPrint() function:
EXEC SQL DELETE FROM org
WHERE deptnumb = :hostVar1 AND
division = :hostVar2;
EMB_SQL_CHECK("Delete with host variables -- Execute");

The EMB_SQL_CHECK macro ensures that if the DELETE statement fails, the transaction
will be safely rolled back, and an appropriate error message printed out.
Developers are encouraged to use and expand upon these error-checking utilities
when creating their own DB2 programs.

Building applications and routines written in C and C++

You are provided with build scripts for various operating systems with your DB2
product. You can build embedded SQL applications in C and C++ with these files.
Aside from build scripts that you can use to build applications, there is a specific
bldrtn script provided that you can use to build routines, such as stored
procedures and user defined functions.
For applications and routines written in VisualAge, configuration files are used to
build the applications. The C application samples provided vary from tutorials to
client level or instance level examples, they can be found in the sqllib/samples/c
directory for UNIX and sqllib\samples\c directory for Windows.

Compile and link options for C and C++

AIX C embedded SQL and DB2 API applications compile and link options:
The compile and link options for building C embedded SQL and DB2 API
applications with the IBM C for AIX compiler are available in the bldapp build
script.
Compile and link options for bldapp
Compile Options:
xlc

The IBM XL C/C++ compiler.

$EXTRA_CFLAG
Contains "-q64" for an instance where 64-bit support is enabled; otherwise,
it contains no value.

168

Developing Embedded SQL Applications

-I$DB2PATH/include
Specify the location of the DB2 include files. For example:
$HOME/sqllib/include.
-c

Perform compile only; no link. Compile and link are separate steps.

Link Options:
xlc

Use the compiler as a front end for the linker.

$EXTRA_CFLAG
Contains "-q64" for an instance where 64-bit support is enabled; otherwise,
it contains no value.
-o $1

Specify the executable program.

$1.o

Specify the program object file.

utilemb.o
If an embedded SQL program, include the embedded SQL utility object file
for error checking.
utilapi.o
If not an embedded SQL program, include the DB2 API utility object file
for error checking.
-ldb2

Link to the DB2 library.

-L$DB2PATH/$LIB
Specify the location of the DB2 runtime shared libraries. For example:
$HOME/sqllib/$LIB. If you do not specify the -L option, the compiler
assumes the following path: /usr/lib:/lib.
Refer to your compiler documentation for additional compiler options.
AIX C++ embedded SQL and DB2 administrative API applications compile and
link options:
The compile and link options for building C++ embedded SQL and DB2
administrative API applications with the IBM XL C/C++ for AIX compiler are
available in the bldapp build script.
Compile and link options for bldapp
Compile options:
xlC

The IBM XL C/C++ compiler.

EXTRA_CFLAG
Contains "-q64" for an instance where 64-bit support is enabled; otherwise,
it contains no value.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example:
$HOME/sqllib/include.
-c

Perform compile only; no link. Compile and link are separate steps.

Link options:
xlC

Use the compiler as a front end for the linker.

Chapter 4. Building

169

EXTRA_CFLAG
Contains "-q64" for an instance where 64-bit support is enabled; otherwise,
it contains no value.
-o $1

Specify the executable program.

$1.o

Specify the program object file.

utilapi.o
Include the API utility object file for non-embedded SQL programs.
utilemb.o
Include the embedded SQL utility object file for embedded SQL programs.
-ldb2

Link with the DB2 library.

-L$DB2PATH/$LIB
Specify the location of the DB2 runtime shared libraries. For example:
$HOME/sqllib/$LIB. If you do not specify the -L option, the compiler
assumes the following path /usr/lib:/lib.
Refer to your compiler documentation for additional compiler options.
HP-UX C application compile and link options:
The compile and link options for building C embedded SQL and DB2 API
applications with the HP-UX C compiler are available in the bldapp build script.
Compile and link options for bldapp
Compile options:
cc

The C compiler.

$EXTRA_CFLAG
If the HP-UX platform is IA64 and 64-bit support is enabled, this flag
contains the value +DD64; if 32-bit support is enabled, it contains the value
+DD32.

-Ae

+DD64

Must be used to generate 64-bit code for HP-UX on IA64.

+DD32

Must be used to generate 32-bit code for HP-UX on IA64.

Enables HP ANSI extended mode.

-I$DB2PATH/include
Specifies the location of the DB2 include files.
-c

Perform compile only; no link. Compile and link are separate steps.

Link options:
cc

Use the compiler as a front end to the linker.

$EXTRA_CFLAG
If the HP-UX platform is IA64 and 64-bit support is enabled, this flag
contains the value +DD64; if 32-bit support is enabled, it contains the value
+DD32.

170

+DD64

Must be used to generate 64-bit code for HP-UX on IA64.

+DD32

Must be used to generate 32-bit code for HP-UX on IA64.

-o $1

Specify the executable.

$1.o

Specify the program object file.

Developing Embedded SQL Applications

utilemb.o
If an embedded SQL program, include the embedded SQL utility object file
for error checking.
utilapi.o
If a non-embedded SQL program, include the DB2 API utility object file for
error checking.
$EXTRA_LFLAG
Specify the runtime path. If set, for 32-bit it contains the value
-Wl,+b$HOME/sqllib/lib32, and for 64-bit: -Wl,+b$HOME/sqllib/lib64. If
not set, it contains no value.
-L$DB2PATH/$LIB
Specify the location of the DB2 runtime shared libraries. For 32-bit:
$HOME/sqllib/lib32; for 64-bit: $HOME/sqllib/lib64.
-ldb2

Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

HP-UX C++ application compile and link options:
The compile and link options for building C++ embedded SQL and DB2 API
applications with the HP-UX C++ compiler are available in the bldapp build script.
Compile and link options for bldapp
Compile options:
aCC

The HP aC++ compiler.

$EXTRA_CFLAG
If the HP-UX platform is IA64 and 64-bit support is enabled, this flag
contains the value +DD64; if 32-bit support is enabled, it contains the value
+DD32.

-ext

+DD64

Must be used to generate 64-bit code for HP-UX on IA64.

+DD32

Must be used to generate 32-bit code for HP-UX on IA64.

Allows various C++ extensions including "long long" support.

-I$DB2PATH/include
Specifies the location of the DB2 include files. For example:
$HOME/sqllib/include
-c

Perform compile only; no link. Compile and link are separate steps.

Link options:
aCC

Use the HP aC++ compiler as a front end for the linker.

$EXTRA_CFLAG
If the HP-UX platform is IA64 and 64-bit support is enabled, this flag
contains the value +DD64; if 32-bit support is enabled, it contains the value
+DD32.
+DD64

Must be used to generate 64-bit code for HP-UX on IA64.

+DD32

Must be used to generate 32-bit code for HP-UX on IA64.

-o $1

Specify the executable.

$1.o

Specify the program object file.

Chapter 4. Building

171

utilemb.o
If an embedded SQL program, include the embedded SQL utility object file
for error checking.
utilapi.o
If a non-embedded SQL program, include the DB2 API utility object file for
error checking.
$EXTRA_LFLAG
Specify the runtime path. If set, for 32-bit it contains the value
"-Wl,+b$HOME/sqllib/lib32", and for 64-bit: "-Wl,+b$HOME/sqllib/lib64". If
not set, it contains no value.
-L$DB2PATH/$LIB
Specify the location of the DB2 runtime shared libraries. For 32-bit:
$HOME/sqllib/lib32; for 64-bit: $HOME/sqllib/lib64.
-ldb2

Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

Linux C application compile and link options:
The compile and link options for building C embedded SQL and DB2 API
applications with the Linux C compiler are available in the bldapp build script.
Compile and link options for bldapp
Compile options:
$CC

The gcc or xlc_r compiler.

$EXTRA_C_FLAGS
Contains one of the following flags:
v -m31 on Linux for zSeries only, to build a 32-bit library;
v -m32 on Linux for x86, x64 and POWER, to build a 32-bit library;
v -m64 on Linux for zSeries, POWER, x64, to build a 64-bit library; or
v No value on Linux for IA64, to build a 64-bit library.
-I$DB2PATH/include
Specify the location of the DB2 include files.
-c

Perform compile only; no link. This script file has separate compile and
link steps.

Link options:
$CC

The gcc or xlc_r compiler; use the compiler as a front end for the linker.

$EXTRA_C_FLAGS
Contains one of the following flags:
v -m31 on Linux for zSeries only, to build a 32-bit library;
v -m32 on Linux for x86, x64 and POWER, to build a 32-bit library;
v -m64 on Linux for zSeries, POWER, x64, to build a 64-bit library; or
v No value on Linux for IA64, to build a 64-bit library.

172

-o $1

Specify the executable.

$1.o

Specify the object file.

Developing Embedded SQL Applications

utilemb.o
If an embedded SQL program, include the embedded SQL utility object file
for error checking.
utilapi.o
If a non-embedded SQL program, include the DB2 API utility object file for
error checking.
$EXTRA_LFLAG
For 32-bit it contains the value "-Wl,-rpath,$DB2PATH/lib32", and for
64-bit it contains the value "-Wl,-rpath,$DB2PATH/lib64".
-L$DB2PATH/$LIB
Specify the location of the DB2 static and shared libraries at link-time. For
example, for 32-bit: $HOME/sqllib/lib32, and for 64-bit:
$HOME/sqllib/lib64.
-ldb2

Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

Linux C++ application compile and link options:
The compile and link options for building C++ embedded SQL and DB2 API
applications with the Linux C++ compiler are available in the bldapp build script.
Compile and link options for bldapp
Compile options:
g++

The GNU/Linux C++ compiler.

$EXTRA_C_FLAGS
Contains one of the following flags:
v -m31 on Linux for zSeries only, to build a 32-bit library;
v -m32 on Linux for x86, x64 and POWER, to build a 32-bit library;
v -m64 on Linux for zSeries, POWER, x64, to build a 64-bit library; or
v No value on Linux for IA64, to build a 64-bit library.
-I$DB2PATH/include
Specify the location of the DB2 include files.
-c

Perform compile only; no link. This script file has separate compile and
link steps.

Link options:
g++

Use the compiler as a front end for the linker.

$EXTRA_C_FLAGS
Contains one of the following flags:
v -m31 on Linux for zSeries only, to build a 32-bit library;
v -m32 on Linux for x86, x64 and POWER, to build a 32-bit library;
v -m64 on Linux for zSeries, POWER, x64, to build a 64-bit library; or
v No value on Linux for IA64, to build a 64-bit library.
-o $1

Specify the executable.

$1.o

Include the program object file.

Chapter 4. Building

173

utilemb.o
If an embedded SQL program, include the embedded SQL utility object file
for error checking.
utilapi.o
If a non-embedded SQL program, include the DB2 API utility object file for
error checking.
$EXTRA_LFLAG
For 32-bit it contains the value "-Wl,-rpath,$DB2PATH/lib32", and for
64-bit it contains the value "-Wl,-rpath,$DB2PATH/lib64".
-L$DB2PATH/$LIB
Specify the location of the DB2 static and shared libraries at link-time. For
example, for 32-bit: $HOME/sqllib/lib32, and for 64-bit:
$HOME/sqllib/lib64.
-ldb2

Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

Solaris C application compile and link options:
The compile and link options for building C embedded SQL and DB2 API
applications with the Forte C compiler are available in the bldapp build script.
Compile and link options for bldapp
Compile options:
cc

The C compiler.

-xarch=$CFLAG_ARCH
This option ensures that the compiler will produce valid executables when
linking with libdb2.so. The value for $CFLAG_ARCH is set as follows:
v "v8plusa" for 32-bit applications on Solaris SPARC
v "v9" for 64-bit applications on Solaris SPARC
v "sse2" for 32-bit applications on Solaris x64
v "amd64" for 64-bit applications on Solaris x64
-I$DB2PATH/include
Specify the location of the DB2 include files. For example:
$HOME/sqllib/include
-c

Perform compile only; no link. This script has separate compile and link
steps.

Link options:
cc

Use the compiler as a front end for the linker.

-xarch=$CFLAG_ARCH
This option ensures that the compiler will produce valid executables when
linking with libdb2.so. The value for $CFLAG_ARCH is set to either
"v8plusa" for 32-bit, or "v9" for 64-bit.
-mt

Link in multi-thread support. Needed for linking with libdb2.

Note: If POSIX threads are used, DB2 applications also have to link with
-lpthread, whether or not they are threaded.

174

Developing Embedded SQL Applications

-o $1

Specify the executable.

$1.o

Include the program object file.

utilemb.o
If an embedded SQL program, include the embedded SQL utility object file
for error checking.
utilapi.o
If not an embedded SQL program, include the DB2 API utility object file
for error checking.
-L$DB2PATH/$LIB
Specify the location of the DB2 static and shared libraries at link-time. For
example, for 32-bit: $HOME/sqllib/lib32, and for 64-bit:
$HOME/sqllib/lib64.
$EXTRA_LFLAG
Specify the location of the DB2 shared libraries at run time. For 32-bit it
contains the value "-R$DB2PATH/lib32", and for 64-bit it contains the
value "-R$DB2PATH/lib64".
-ldb2

Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

Solaris C++ application compile and link options:
The compile and link options for building C++ embedded SQL and DB2 API
applications with the Forte C++ compiler are available in the bldapp build script.
Compile and link options for bldapp
Compile options:
CC

The C++ compiler.

-xarch=$CFLAG_ARCH
This option ensures that the compiler will produce valid executables when
linking with libdb2.so. The value for $CFLAG_ARCH is set as follows:
v "v8plusa" for 32-bit applications on Solaris SPARC
v "v9" for 64-bit applications on Solaris SPARC
v "sse2" for 32-bit applications on Solaris x64
v "amd64" for 64-bit applications on Solaris x64
-I$DB2PATH/include
Specify the location of the DB2 include files. For example:
$HOME/sqllib/include
-c

Perform compile only; no link. This script has separate compile and link
steps.

Link options:
CC

Use the compiler as a front end for the linker.

-xarch=$CFLAG_ARCH
This option ensures that the compiler will produce valid executables when
linking with libdb2.so. The value for $CFLAG_ARCH is set to either
"v8plusa" for 32-bit, or "v9" for 64-bit.
-mt

Link in multi-thread support. Needed for linking with libdb2.

Chapter 4. Building

175

Note: If POSIX threads are used, DB2 applications also have to link with
-lpthread, whether or not they are threaded.
-o $1

Specify the executable.

$1.o

Include the program object file.

utilemb.o
If an embedded SQL program, include the embedded SQL utility object file
for error checking.
utilapi.o
If a non-embedded SQL program, include the DB2 API utility object file for
error checking.
-L$DB2PATH/$LIB
Specify the location of the DB2 static and shared libraries at link-time. For
example, for 32-bit: $HOME/sqllib/lib32, and for 64-bit:
$HOME/sqllib/lib64.
$EXTRA_LFLAG
Specify the location of the DB2 shared libraries at run time. For 32-bit it
contains the value "-R$DB2PATH/lib32", and for 64-bit it contains the
value "-R$DB2PATH/lib64".
-ldb2

Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

Windows C and C++ application compile and link options:
The compile and link options for building C and C++ embedded SQL and DB2
API applications on Windows with the Microsoft Visual C++ compiler are available
in the bldapp.bat batch file.
Compile and link options for bldapp
Compile options:
%BLDCOMP%
Variable for the compiler. The default is cl, the Microsoft Visual C++
compiler. It can be also set to icl, the Intel C++ Compiler for 32-bit and
64-bit applications, or ecl, the Intel C++ Compiler for Itanium 64-bit
applications.
-Zi

Enable debugging information

-Od

Disable optimizations. It is easier to use a debugger with optimization off.

-c

Perform compile only; no link. The batch file has separate compile and link
steps.

-W2

Output warning, error, and severe and unrecoverable error messages.

-DWIN32
Compiler option necessary for Windows operating systems.
Link options:
link

Use the linker to link.

-debug Include debugging information.

176

Developing Embedded SQL Applications

-out:%1.exe
Specify a filename
%1.obj Include the object file
utilemb.obj
If an embedded SQL program, include the embedded SQL utility object file
for error checking.
utilapi.obj
If not an embedded SQL program, include the DB2 API utility object file
for error checking.
db2api.lib
Link with the DB2 library.

Building applications in C or C++ using the sample build script

(UNIX)
You are provided with build scripts for compiling and linking embedded SQL and
DB2 administrative API programs in C or C++. The scripts are in the
sqllib/samples/c directory for C applications and the sqllib/samples/cpp
directory for C++ applications. The directories include sample programs that you
can build with these files.

About this task

The build file, bldapp, contains the commands to build a DB2 application program.
The first parameter, $1, specifies the name of your source file. This is the only
required parameter, and the only one needed for DB2 administrative API programs
that do not contain embedded SQL. Building embedded SQL programs requires a
connection to the database so three optional parameters are also provided: the
second parameter, $2, specifies the name of the database to which you want to
connect; the third parameter, $3, specifies the user ID for the database, and $4
specifies the password.
For an embedded SQL program, bldapp passes the parameters to the precompile
and bind script, embprep. If no database name is supplied, the default sample
database is used. The user ID and password parameters are only needed if the
instance where the program is built is different from the instance where the
database is located.
The following examples show you how to build and run DB2 administrative API
and embedded SQL applications.
Building and running DB2 administrative API applications
To build the DB2 administrative API sample program, cli_info, from the
source file cli_info.c for C and cli_info.C for C++, enter:
bldapp cli_info

The result is an executable file, cli_info.

To run the executable file, enter the executable name:
cli_info

Building and running embedded SQL applications

v There are three ways to build the embedded SQL application, tbmod,
from the source file tbmod.sqc for C and tbmod.sqC for C++,:
Chapter 4. Building

177

1. If connecting to the sample database on the same instance, enter:

bldapp tbmod

2. If connecting to another database on the same instance, also enter the

database name:
bldapp tbmod database

3. If connecting to a database on another instance, also enter the user

ID and password of the database instance:
bldapp tbmod database userid password

The result is an executable file,tbmod

v There are three ways to run this embedded SQL application:
1. If accessing the sample database on the same instance, enter the
executable name:
tbmod

2. If accessing another database on the same instance, enter the

executable name and the database name:
tbmod database

3. If accessing a database on another instance, enter the executable

name, database name, and user ID and password of the database
instance:
tbmod database userid password

Building C/C++ applications on Windows

DB2 provides build scripts for compiling and linking DB2 API and embedded SQL
C/C++ programs. These are located in the sqllib\samples\c and
sqllib\samples\cpp directories, along with sample programs that can be built with
these files.

About this task

The batch file, bldapp.bat, contains the commands to build DB2 API and
embedded SQL programs. It takes up to four parameters, represented inside the
batch file by the variables %1, %2, %3, and %4.
The first parameter, %1, specifies the name of your source file. This is the only
required parameter for programs that do not contain embedded SQL. Building
embedded SQL programs requires a connection to the database so three additional
parameters are also provided: the second parameter, %2, specifies the name of the
database to which you want to connect; the third parameter, %3, specifies the user
ID for the database, and %4 specifies the password.
For an embedded SQL program, bldapp passes the parameters to the precompile
and bind file, embprep.bat. If no database name is supplied, the default sample
database is used. The user ID and password parameters are only needed if the
instance where the program is built is different from the instance where the
database is located.

Procedure
v Building and running embedded SQL applications
There are three ways to build the embedded SQL application, tbmod, from the C
source file tbmod.sqc in sqllib\samples\c, or from the C++ source file tbmod.sqx
in sqllib\samples\cpp:
If connecting to the sample database on the same instance, enter:

178

Developing Embedded SQL Applications

bldapp tbmod

If connecting to another database on the same instance, also enter the

database name:
bldapp tbmod database

If connecting to a database on another instance, also enter the user ID and

password of the database instance:
bldapp tbmod database userid password

The result is an executable file tbmod.exe.

There are three ways to run this embedded SQL application:
If accessing the sample database on the same instance, enter the executable
name:
tbmod

If accessing another database on the same instance, enter the executable name
and the database name:
tbmod database

If accessing a database on another instance, enter the executable name,

database name, and user ID and password of the database instance:
tbmod database userid password

v Building and running multi-threaded applications

C/C++ multi-threaded applications on Windows need to be compiled with
either the -MT or -MD options. The -MT option will link using the static library
LIBCMT.LIB, and -MD will link using the dynamic library MSVCRT.LIB. The binary
linked with -MD will be smaller but dependent on MSVCRT.DLL, while the binary
linked with -MT will be larger but will be self-contained with respect to the
runtime.
The batch file bldmt.bat uses the -MT option to build a multi-threaded program.
All other compile and link options are the same as those used by the batch file
bldapp.bat to build regular stand-alone applications.
To build the multi-threaded sample program, dbthrds, from either the
samples\c\dbthrds.sqc or samples\cpp\dbthrds.sqx source file, enter:
bldmt dbthrds

The result is an executable file, dbthrds.exe.

There are three ways to run this multi-threaded application:
If accessing the sample database on the same instance, simply enter the
executable name (without the extension):
dbthrds

If accessing another database on the same instance, enter the executable name
and the database name:
dbthrds database

If accessing a database on another instance, enter the executable name,

database name, and user ID and password of the database instance:
dbthrds database userid password

Example
The following examples show you how to build and run DB2 API and embedded
SQL applications.

Chapter 4. Building

179

To build the DB2 API non-embedded SQL sample program, cli_info, from either
the source file cli_info.c, in sqllib\samples\c, or from the source file
cli_info.cxx, in sqllib\samples\cpp, enter:
bldapp cli_info

The result is an executable file, cli_info.exe. You can run the executable file by
entering the executable name (without the extension) on the command line:
cli_info

Building embedded SQL applications written in VisualAge C++

with configuration files
VisualAge C++ has both an incremental compiler and a batch mode compiler. You
can use the batch mode compiler if you use make files and build files. The
incremental compiler uses configuration files to compile, link, and build
applications.

About this task

See the documentation that comes with VisualAge C++ Version 5.0 to learn more
about the incremental compiler and the batch mode compiler.
DB2 provides configuration files for the different types of DB2 programs you can
build with the VisualAge C++ compiler.
To use a DB2 configuration file, you first set an environment variable to the
program name you want to compile. Then you compile the program with a
command supplied by VisualAge C++.

Building C/C++ multi-connection applications on Windows

You can use the provided build scripts to compile and link C and C++ embedded
SQL and DB2 API programs. The scripts are in the sqllib\samples\c and
sqllib\samples\cpp directories. The directories also contain sample programs that
you can build with these files.
You can find the commands to build a DB2 multi-connection program in the
bldmc.bat batch file. The commands require two databases. The compile and link
options are the same as those used in the bldapp.bat file.

About this task

The first parameter, %1, specifies the name of your source file. The second
parameter, %2, specifies the name of the first database to which you want to
connect. The third parameter, %3, specifies the second database to which you want
to connect. These are all required parameters.
Note: The build script hardcodes default values of "sample" and "sample2" for the
database names (%2 and %3) so if you are using the build script, and accept these
defaults, you only have to specify the program name (the %1 parameter). If you are
using the bldmc.bat script, you must specify all three parameters.
Optional parameters are not required for a local connection, but are required for
connecting to a server from a remote client. These are: %4 and %5 to specify the
user ID and password, for the first database; and %6 and %7 to specify the user ID
and password, for the second database.

180

Developing Embedded SQL Applications

For the multi-connection sample program, dbmcon.exe, you require two databases.
If the sample database is not yet created, you can create it by entering db2sampl on
the command line of a DB2 command window. The second database, here called
sample2, can be created with one of the following commands:
If creating the database locally:
db2 create db sample2

If creating the database remotely:

db2
db2
db2
db2

attach to node_name
create db sample2
detach
catalog db sample2 as sample2 at node node_name

where node_name is the node where the database resides.

Multi-connection also requires that the TCP/IP listener is running.

Procedure
To ensure that the TCP/IP listener is running:
1. Set the environment variable DB2COMM to TCP/IP as follows:
db2set DB2COMM=TCPIP

2. Update the database manager configuration file with the TCP/IP service name
as specified in the services file:
db2 update dbm cfg using SVCENAME TCPIP_service_name

Each instance has a TCP/IP service name listed in the services file. Ask your
system administrator if you cannot locate it or do not have the file permission
to change the services file.
3. Stop and restart the database manager in order for these changes to take effect:
db2stop
db2start

Results
The dbmcon.exe program is created from five files in either the samples\c or
samples\cpp directories:
dbmcon.sqc or dbmcon.sqx
Main source file for connecting to both databases.
dbmcon1.sqc or dbmcon1.sqx
Source file for creating a package bound to the first database.
dbmcon1.h
Header file for dbmcon1.sqc or dbmcon1.sqx included in the main source
file, dbmcon.sqc or dbmcon.sqx, for accessing the SQL statements for
creating and dropping a table bound to the first database.
dbmcon2.sqc or dbmcon2.sqx
Source file for creating a package bound to the second database.
dbmcon2.h
Header file for dbmcon2.sqc or dbmcon2.sqx included in the main source
file, dbmcon.sqc or dbmcon.sqx, for accessing the SQL statements for
creating and dropping a table bound to the second database.
Chapter 4. Building

181

To build the multi-connection sample program, dbmcon.exe, enter:

bldmc dbmcon sample sample2

The result is an executable file, dbmcon.exe.

To run the executable file, enter the executable name, without the extension:
dbmcon

The program demonstrates a one-phase commit to two databases.

Building applications and routines written in COBOL

You are provided with build scripts for various operating systems for your DB2
product. You can build embedded SQL applications written in COBOL with these
files.
Aside from build scripts that you can use to build applications there is a specific
bldrtn script so that you can build routines, such as stored procedures and user
defined functions.
When working with applications written in the Micro Focus COBOL language on
Linux, be sure to configure the compiler to be able to access certain COBOL shared
libraries. IBM COBOL samples are provided and can be found in the
sqllib/samples/cobol directory for UNIX and sqllib\samples\cobol directory for
Windows, for the Micro Focus COBOL samples directories replace the 'cobol' at the
end of the path with 'cobol_mf'.

Compile and link options for COBOL

IBM COBOL for AIX application compile and link options:
The compile and link options for building COBOL embedded SQL and DB2 API
applications with the IBM COBOL for AIX compiler are available in the bldapp
build script.
Compile and link options for bldapp
Compile options:
cob2

The IBM COBOL for AIX compiler.

-qpgmname\(mixed\)
Instructs the compiler to permit CALLs to library entry points with
mixed-case names.
-qlib

Instructs the compiler to process COPY statements.

-I$DB2PATH/include/cobol_a
Specify the location of the DB2 include files. For example:
$HOME/sqllib/include/cobol_a.
-c

Perform compile only; no link. Compile and link are separate steps.

Link options:

182

cob2

Use the compiler as a front end for the linker.

-o $1

Specify the executable program.

$1.o

Specify the program object file.

Developing Embedded SQL Applications

checkerr.o
Include the utility object file for error-checking.
-L$DB2PATH/$LIB
Specify the location of the DB2 runtime shared libraries. For example:
$HOME/sqllib/lib32.
-ldb2

Link with the database manager library.

Refer to your compiler documentation for additional compiler options.

AIX Micro Focus COBOL application compile and link options:
The compile and link options for building COBOL embedded SQL and DB2 API
application with the Micro Focus COBOL for AIX compiler are available in the
bldapp build script.
Note that the DB2 Micro Focus COBOL include files are found by setting up the
COBCPY environment variable, so no -I flag is required in the compile step. Refer
to the bldapp script for an example.
Compile and link options for bldapp
Compile options:
cob

The MicroFocus COBOL compiler.

-c

Perform compile only; no link.

$EXTRA_COBOL_FLAG="-C MFSYNC"
Enables 64-bit support.
-x

When used with -c, produces an object file.

Link Options:
cob

Use the compiler as a front end for the linker.

-x

Produces an executable program.

-o $1

Specify the executable program.

$1.o

Specify the program object file.

-L$DB2PATH/$LIB
Specify the location of the DB2 runtime shared libraries. For example:
$HOME/sqllib/lib32.
-ldb2

Link to the DB2 library.

-ldb2gmf
Link to the DB2 exception-handler library for Micro Focus COBOL.
Refer to your compiler documentation for additional compiler options.
HP-UX Micro Focus COBOL application compile and link options:
The compile and link options for building COBOL embedded SQL and DB2 API
applications with the Micro Focus COBOL compiler for HP-UX are available in the
bldapp build script.

Chapter 4. Building

183

Compile and link options for bldapp

Compile options:
cob

The Micro Focus COBOL compiler.

-cx

Compile to object module.

$EXTRA_COBOL_FLAG
Contains "-C MFSYNC" if the HP-UX platform is IA64 and 64-bit support
is enabled.
Link options:
cob

Use the compiler as a front end for the linker.

-x

Specify an executable program.

$1.o

Include the program object file.

checkerr.o
Include the utility object file for error checking.
-L$DB2PATH/$LIB
Specify the location of the DB2 runtime shared libraries.
-ldb2

Link to the DB2 library.

-ldb2gmf
Link to the DB2 exception-handler library for Micro Focus COBOL.
Refer to your compiler documentation for additional compiler options.
Solaris Micro Focus COBOL application compile and link options:
The compile and link options for building COBOL embedded SQL and DB2 API
applications with the Micro Focus COBOL compiler on Solaris are available in the
bldapp build script.
Compile and link options for bldapp
Compile options:
cob

The Micro Focus COBOL compiler.

$EXTRA_COBOL_FLAG
For 64-bit support, contains the value "-C MFSYNC"; otherwise it contains
no value.
-cx

Compile to object module.

Link options:
cob

Use the compiler as a front end for the linker.

-x

Specify an executable program.

$1.o

Include the program object file.

checkerr.o
Include the utility object file for error-checking.
-L$DB2PATH/$LIB
Specify the location of the DB2 static and shared libraries at link-time. For
example: $HOME/sqllib/lib64.

184

Developing Embedded SQL Applications

-ldb2

Link with the DB2 library.

-ldb2gmf
Link with the DB2 exception-handler library for Micro Focus COBOL.
Refer to your compiler documentation for additional compiler options.
Linux Micro Focus COBOL application compile and link options:
These compile and link options are available for building COBOL embedded SQL
and DB2 API applications with the Micro Focus COBOL compiler on Linux, as
demonstrated in the bldapp build script.
Compile and link options for bldapp
Compile options:
cob

The Micro Focus COBOL compiler.

-cx

Compile to object module.

$EXTRA_COBOL_FLAG
For 64-bit support, contains the value "-C MFSYNC"; otherwise it contains
no value.
Link options:
cob

Use the compiler as a front end for the linker.

-x

Specify an executable program.

-o $1

Include the executable.

$1.o

Include the program object file.

checkerr.o
Include the utility object file for error checking.
-L$DB2PATH/$LIB
Specify the location of the DB2 runtime shared libraries.
-ldb2

Link to the DB2 library.

-ldb2gmf
Link to the DB2 exception-handler library for Micro Focus COBOL.
Refer to your compiler documentation for additional compiler options.
Windows IBM COBOL application compile and link options:
The compile and link options for building COBOL embedded SQL and DB2 API
applications on Windows operating systems with the IBM VisualAge COBOL
compiler are available in the bldapp.bat batch file.
Compile and link options for bldapp
Compile options:
cob2

The IBM VisualAge COBOL compiler.

-qpgmname(mixed)
Instructs the compiler to permit CALLs to library entry points with
mixed-case names.
Chapter 4. Building

185

-c

Perform compile only; no link. Compile and link are separate steps.

-qlib

Instructs the compiler to process COPY statements.

-Ipath Specify the location of the DB2 include files. For example:
-I"%DB2PATH%\include\cobol_a".
%EXTRA_COMPFLAG%
If "set IBMCOB_PRECOMP=true" is uncommented, the IBM COBOL
precompiler is used to precompile the embedded SQL. It is invoked with
one of the following formulations, depending on the input parameters:
-q"SQL(database sample CALL_RESOLUTION DEFERRED)"
precompile using the default sample database, and defer call
resolution.
-q"SQL(database %2 CALL_RESOLUTION DEFERRED)"
precompile using a database specified by the user, and defer call
resolution.
-q"SQL(database %2 user %3 using %4 CALL_RESOLUTION DEFERRED)"
precompile using a database, user ID, and password specified by
the user, and defer call resolution. This is the format for remote
client access.
Link options:
cob2

Use the compiler as a front-end for the linker

%1.obj Include the program object file.

checkerr.obj
Include the error-checking utility object file.
db2api.lib
Link with the DB2 library.
Refer to your compiler documentation for additional compiler options.
Windows Micro Focus COBOL application compile and link options:
The compile and link options for building COBOL embedded SQL and DB2 API
applications on Windows operating systems with the Micro Focus COBOL
compiler are available in the bldapp.bat batch file.
Compile and link options for bldapp
Compile option:
cobol

The Micro Focus COBOL compiler.

Link options:
cbllink
Use the linker to link edit.
-l

Link with the lcobol library.

checkerr.obj
Link with the error-checking utility object file.
db2api.lib
Link with the DB2 API library.

186

Developing Embedded SQL Applications

Refer to your compiler documentation for additional compiler options.

COBOL compiler configurations

Configuring the IBM COBOL compiler on AIX:
Before you develop IBM COBOL applications that contain embedded SQL and DB2
API calls on AIX operating systems, you must configure the IBM COBOL compiler.
About this task
Required steps if you develop applications that contain embedded SQL and DB2
API calls, and you are using the IBM COBOL Set for AIX compiler.
Procedure
v When you precompile your application using the PRECOMPILE command, use the
target ibmcob option.
v Do not use tab characters in your source files.
v You can use the PROCESS and CBL keywords in the first line of your source files
to set compile options.
v If your application contains only embedded SQL, but no DB2 API calls, you do
not need to use the pgmname(mixed) compile option. If you use DB2 API calls,
you must use the pgmname(mixed) compile option.
v If you are using the "System z host data type support" feature of the IBM
COBOL Set for AIX compiler, the DB2 include files for your applications are in
the following directory:
$HOME/sqllib/include/cobol_i

If you are building DB2 sample programs using the script files provided, the
include file path specified in the script files must be changed to point to the
cobol_i directory and not the cobol_a directory.
If you are NOT using the "System z host data type support" feature of the IBM
COBOL Set for AIX compiler, or you are using an earlier version of this
compiler, then the DB2 include files for your applications are in the following
directory:
$HOME/sqllib/include/cobol_a

Specify COPY file names to include the .cbl extension as follows:

COPY "sql.cbl".

Configuring the IBM COBOL compiler on Windows:

When you develop an embedded SQL application with the IBM VisualAge COBOL
compiler on Windows operating system, following db2 prep option and compiler
options must be set.
Procedure
v When you precompile your application with the DB2 precompiler, and use the
command line processor command db2 prep, use the target ibmcob option.
v Do not use tab characters in your source files.
v Use the PROCESS and CBL keywords in your source files to set compile options.
Place the keywords in columns 8 to 72 only.
v If your application contains only embedded SQL, but no DB2 API calls, you do
not need to use the pgmname(mixed) compile option. If you use DB2 API calls,
you must use the pgmname(mixed) compile option.
Chapter 4. Building

187

v If you are using the "System/390 host data type support" feature of the IBM
VisualAge COBOL compiler, the DB2 include files for your applications are in
the following directory:
%DB2PATH%\include\cobol_i

If you are building DB2 sample programs using the batch files provided, the
include file path specified in the batch files must be changed to point to the
cobol_i directory and not the cobol_a directory.
If you are NOT using the "System/390 host data type support" feature of the
IBM VisualAge COBOL compiler, or you are using an earlier version of this
compiler, then the DB2 include files for your applications are in the following
directory:
%DB2PATH%\include\cobol_a

The cobol_a directory is the default.

v Specify COPY file names to include the .cbl extension as follows:
COPY "sql.cbl".

Configuring the Micro Focus COBOL compiler on Windows:

When you develop an embedded SQL application with the Micro Focus COBOL
compiler on Windows operating system, following db2 prep option and
environment settings must be set.
Procedure
v When you precompile your application using the PRECOMPILE command, use the
target mfcob option.
v Ensure that the LIB environment variable points to %DB2PATH%\lib by using the
following command:
set LIB="%DB2PATH%\lib;%LIB%"

v The DB2 COPY files for Micro Focus COBOL reside in %DB2PATH%\include\
cobol_mf. Set the COBCPY environment variable to include the directory as
follows:
set COBCPY="%DB2PATH%\include\cobol_mf;%COBCPY%"

You must ensure that the previously mentioned environment variables are
permanently set in the System settings. This can be checked by going through
the following steps:
1. Open the Control Panel
Select System
Select the Advanced tab
Click Environment Variables
Check the System variables list for the required environment variables. If
not present, add them to the System variables list
Setting them in either the User settings, at a command prompt, or in a script is
insufficient.
2.
3.
4.
5.

What to do next
You must make calls to all DB2 application programming interfaces using calling
convention 74. The DB2 COBOL precompiler automatically inserts a
CALL-CONVENTION clause in a SPECIAL-NAMES paragraph. If the
SPECIAL-NAMES paragraph does not exist, the DB2 COBOL precompiler creates
it, as follows:

188

Developing Embedded SQL Applications

Identification Division
Program-ID. "static".
special-names.
call-convention 74 is DB2API.

Also, the precompiler automatically places the symbol DB2API, which is used to
identify the calling convention, after the "call" keyword whenever a DB2 API is
called. This occurs, for example, whenever the precompiler generates a DB2 API
runtime call from an embedded SQL statement.
If calls to DB2 APIs are made in an application which is not precompiled, you
should manually create a SPECIAL-NAMES paragraph in the application, similar
to that given previously. If you are calling a DB2 API directly, then you will need
to manually add the DB2API symbol after the "call" keyword.
Configuring the Micro Focus COBOL compiler on Linux:
To run Micro Focus COBOL routines, you must ensure that the Linux runtime
linker and DB2 processes can access the dependent COBOL libraries in the
/usr/lib directory.
About this task
Create symbolic links to /usr/lib for the COBOL shared libraries as root. The
simplest way to create symbolic links to /usr/lib is to link all COBOL library files
from $COBDIR/lib to /usr/lib:
ln -s $COBDIR/lib/libcob* /usr/lib

where $COBDIR is where Micro Focus COBOL is installed, usually

/opt/lib/mfcobol.
Here are the commands to link each individual file (assuming Micro Focus COBOL
is installed in /opt/lib/mfcobol):
ln
ln
ln
ln
ln
ln
ln
ln
ln
ln
ln
ln
ln
ln
ln
ln

-s
-s
-s
-s
-s
-s
-s
-s
-s
-s
-s
-s
-s
-s
-s
-s

/opt/lib/mfcobol/lib/libcobrts.so /usr/lib
/opt/lib/mfcobol/lib/libcobrts_t.so /usr/lib
/opt/lib/mfcobol/lib/libcobrts.so.2 /usr/lib
/opt/lib/mfcobol/lib/libcobrts_t.so.2 /usr/lib
/opt/lib/mfcobol/lib/libcobcrtn.so /usr/lib
/opt/lib/mfcobol/lib/libcobcrtn.so.2 /usr/lib
/opt/lib/mfcobol/lib/libcobmisc.so /usr/lib
/opt/lib/mfcobol/lib/libcobmisc_t.so /usr/lib
/opt/lib/mfcobol/lib/libcobmisc.so.2 /usr/lib
/opt/lib/mfcobol/lib/libcobmisc_t.so.2 /usr/lib
/opt/lib/mfcobol/lib/libcobscreen.so /usr/lib
/opt/lib/mfcobol/lib/libcobscreen.so.2 /usr/lib
/opt/lib/mfcobol/lib/libcobtrace.so /usr/lib
/opt/lib/mfcobol/lib/libcobtrace_t.so /usr/lib
/opt/lib/mfcobol/lib/libcobtrace.so.2 /usr/lib
/opt/lib/mfcobol/lib/libcobtrace_t.so.2 /usr/lib

The following procedures need to be done on each DB2 instance:

Procedure
v When you precompile your application using the PRECOMPILE command, use the
target mfcob option.
v You must include the DB2 COBOL COPY file directory in the Micro Focus
COBOL environment variable COBCPY. The COBCPY environment variable

Chapter 4. Building

189

specifies the location of the COPY files. The DB2 COPY files for Micro Focus
COBOL reside in sqllib/include/cobol_mf under the database instance
directory.
To include the directory, enter:
On bash or Korn shell:
export COBCPY=$HOME/sqllib/include/cobol_mf:$COBDIR/cpylib

On C shell:
setenv COBCPY $HOME/sqllib/include/cobol_mf:$COBDIR/cpylib

v Update the environment variable:

On bash or Korn shell:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/sqllib/lib:$COBDIR/lib

On C shell:
setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:$HOME/sqllib/lib:$COBDIR/lib

v Set the DB2 Environment List:

db2set DB2ENVLIST="COBDIR LD_LIBRARY_PATH"

Results
Note: You might want to set COBCPY, COBDIR, and LD_LIBRARY_PATH in the
.bashrc, .kshrc (depending on shell being used), .bash_profile, .profile
(depending on shell being used), or in the .login. .
Configuring the Micro Focus COBOL compiler on AIX:
Before you develop Micro Focus COBOL applications that contain embedded SQL
and DB2 API calls on AIX operating systems, you must configure the Micro Focus
COBOL compiler.
About this task
Follow the listed steps if you develop applications that contain embedded SQL and
DB2 API calls with the Micro Focus COBOL compiler.
Procedure
v When you precompile your application using the PRECOMPILE command, use the
target mfcob option.
v You must include the DB2 COBOL COPY file directory in the Micro Focus
COBOL environment variable COBCPY. The COBCPY environment variable
specifies the location of the COPY files. The DB2 COPY files for Micro Focus
COBOL are in sqllib/include/cobol_mf under the database instance directory.
To include the directory, enter:
On bash or Korn shell:
export COBCPY=$COBCPY:$HOME/sqllib/include/cobol_mf

On C shell:
setenv COBCPY $COBCPY:$HOME/sqllib/include/cobol_mf

Note: You might want to set COBCPY in the .profile or .login file.
Configuring the Micro Focus COBOL compiler on HP-UX:
You must set COBCPY environment variable in your HP-UX instance before you can
compile an embedded SQL application with the Micro Focus COBOL compiler.

190

Developing Embedded SQL Applications

Procedure
v When you precompile your application with the PRECOMPILE command, use the
target mfcob option.
v You must include the DB2 COBOL COPY file directory in the Micro Focus
COBOL environment variable COBCPY. The COBCPY environment variable
specifies the location of COPY files. The DB2 COPY files for Micro Focus
COBOL is in sqllib/include/cobol_mf under the database instance directory.
To include the directory,
On bash or Korn shell, enter:
export COBCPY=$COBCPY:$HOME/sqllib/include/cobol_mf

On C shell, enter:
setenv COBCPY ${COBCPY}:${HOME}/sqllib/include/cobol_mf

Note: You might want to set COBCPY in the .profile or .login file.
Configuring the Micro Focus COBOL compiler on Solaris:
You must set COBCPY environment variable in your Solaris instance before you can
compile an embedded SQL application with the Micro Focus COBOL compiler.
Procedure
v When you precompile your application with the db2 prep command, use the
target mfcob option.
v You must include the DB2 COBOL COPY file directory in the Micro Focus
COBOL environment variable COBCPY. The COBCPY environment variable
specifies the location of COPY files. The DB2 COPY files for Micro Focus
COBOL is insqllib/include/cobol_mf under the database instance directory.
To include the directory, enter:
On bash or Korn shells:
export COBCPY=$COBCPY:$HOME/sqllib/include/cobol_mf

On C shell:
setenv COBCPY $COBCPY:$HOME/sqllib/include/cobol_mf

Note: You might want to set COBCPY in the .profile file.

Building IBM COBOL applications on AIX

You can use the provided build scripts for compiling and linking IBM COBOL
embedded SQL and DB2 administrative API programs. The scripts are in the
sqllib/samples/cobol directory. The directories also contain sample programs that
you can build with these files.
You can find commands to build a DB2 application program in the bldapp build
script.

About this task

The first parameter, $1, specifies the name of your source file. This is the only
required parameter for programs that do not contain embedded SQL. Building
embedded SQL programs requires a connection to the database so three optional
parameters are also provided: the second parameter, $2, specifies the name of the
database to which you want to connect; the third parameter, $3, specifies the user
ID for the database, and $4 specifies the password.

Chapter 4. Building

191

For an embedded SQL program, bldapp passes the parameters to the precompile
and bind script, embprep. If no database name is supplied, the default sample
database is used. The user ID and password parameters are only needed if the
instance where the program is built is different from the instance where the
database is located.
To build the non-embedded SQL sample program client from the source file
client.cbl, enter:
bldapp client

The result is an executable file client. You can run the executable file against the
sample database by entering:
client

Procedure
v There are three ways to build the embedded SQL application, updat, from the
source file updat.sqb:
1. If connecting to the sample database on the same instance, enter:
bldapp updat

2. If connecting to another database on the same instance, also enter the

database name:
bldapp updat database

3. If connecting to a database on another instance, also enter the user ID and

password of the database instance:
bldapp updat database userid password

The result is an executable file, updat.

v There are three ways to run this embedded SQL application:
1. If accessing the sample database on the same instance, enter the executable
name:
updat

2. If accessing another database on the same instance, enter the executable

name and the database name:
updat database

3. If accessing a database on another instance, enter the executable name,

database name, and user ID and password of the database instance:
updat database userid password

Building UNIX Micro Focus COBOL applications

You are provided with build scripts for compiling and linking Micro Focus COBOL
embedded SQL and DB2 administrative API programs. You can find the scripts in
the sqllib/samples/cobol_mf directory. The directory also contains sample
programs that you can build with these files.
You can find the commands to build a DB2 application program in the bldapp
build file.

About this task

The first parameter, $1, specifies the name of your source file. This is the only
required parameter for programs that do not contain embedded SQL. Building
embedded SQL programs requires a connection to the database so three optional
parameters are also provided: the second parameter, $2, specifies the name of the

192

Developing Embedded SQL Applications

database to which you want to connect; the third parameter, $3, specifies the user
ID for the database, and $4 specifies the password.
For an embedded SQL program, bldapp passes the parameters to the precompile
and bind script, embprep. If no database name is supplied, the default sample
database is used. The user ID and password parameters are only needed if the
instance where the program is built is different from the instance where the
database is located.
To build the non-embedded SQL sample program, client, from the source file
client.cbl, enter:
bldapp client

The result is an executable file client. You can run the executable file against the
sample database by entering:
client

Procedure
v There are three ways to build the embedded SQL application, updat, from the
source file updat.sqb:
1. If connecting to the sample database on the same instance, enter:
bldapp updat

2. If connecting to another database on the same instance, also enter the

database name:
bldapp updat database

3. If connecting to a database on another instance, also enter the user ID and

password of the database instance:
bldapp updat database userid password

The result is an executable file, updat.

v There are three ways to run this embedded SQL application:
1. If accessing the sample database on the same instance, enter the executable
name:
updat

2. If accessing another database on the same instance, enter the executable

name and the database name:
updat database

3. If accessing a database on another instance, enter the executable name,

database name, and user ID and password of the database instance:
updat database userid password

Building IBM COBOL applications on Windows

You can use the provided build scripts to compile and link DB2 API and
embedded SQL programs. The scripts are in the sqllib\samples\cobol directory.
The directory also contains sample programs that you can build with these files.

About this task

DB2 supports two precompilers for building IBM COBOL applications on
Windows, the DB2 precompiler and the IBM COBOL precompiler. The default is
the DB2 precompiler. The IBM COBOL precompiler can be selected by
uncommenting the appropriate line in the batch file you are using. Precompilation
with IBM COBOL is done by the compiler itself, using specific precompile options.
Chapter 4. Building

193

The batch file, bldapp.bat, contains the commands to build a DB2 application
program. It takes up to four parameters, represented inside the batch file by the
variables %1, %2, %3, and %4.
The first parameter, %1, specifies the name of your source file. This is the only
required parameter for programs that do not contain embedded SQL. Building
embedded SQL programs requires a connection to the database so three optional
parameters are also provided: the second parameter, %2, specifies the name of the
database to which you want to connect; the third parameter, %3, specifies the user
ID for the database, and %4 specifies the password.
For an embedded SQL program using the default DB2 precompiler, bldapp.bat
passes the parameters to the precompile and bind file, embprep.bat.
For an embedded SQL program using the IBM COBOL precompiler, bldapp.bat
copies the .sqb source file to a .cbl source file. The compiler performs the
precompile on the .cbl source file with specific precompile options.
For either precompiler, if no database name is supplied, the default sample
database is used. The user ID and password parameters are only needed if the
instance where the program is built is different from the instance where the
database is located.
The following examples show you how to build and run DB2 API and embedded
SQL applications.
To build the non-embedded SQL sample program client from the source file
client.cbl, enter:
bldapp client

The result is an executable file client.exe. You can run the executable file against
the sample database by entering the executable name (without the extension):
client

Procedure
v There are three ways to build the embedded SQL application, updat, from the
source file updat.sqb:
1. If connecting to the sample database on the same instance, enter:
bldapp updat

2. If connecting to another database on the same instance, also enter the

database name:
bldapp updat database

3. If connecting to a database on another instance, also enter the user ID and

password of the database instance:
bldapp updat database userid password

The result is an executable file, updat.

v There are three ways to run this embedded SQL application:
1. If accessing the sample database on the same instance, enter the executable
name:
updat

2. If accessing another database on the same instance, enter the executable

name and the database name:
updat database

194

Developing Embedded SQL Applications

3. If accessing a database on another instance, enter the executable name,

database name, and user ID and password of the database instance:
updat database userid password

Building Micro Focus COBOL applications on Windows

You can use build scripts provided with IBM data server client for compiling and
linking DB2 API and embedded SQL programs.
Build scripts are in the sqllib\samples\cobol_mf directory, along with sample
programs that can be built with these build script files.

About this task

The batch file bldapp.bat contains the commands to build a DB2 application
program. It takes up to four parameters, represented inside the batch file by the
variables %1, %2, %3, and %4.
The first parameter, %1, specifies the name of your source file. This is the only
required parameter for programs that do not contain embedded SQL. Building
embedded SQL programs requires a connection to the database so three optional
parameters are also provided: the second parameter, %2, specifies the name of the
database to which you want to connect; the third parameter, %3, specifies the user
ID for the database, and %4 specifies the password.
For an embedded SQL program, bldapp passes the parameters to the precompile
and bind batch file, embprep.bat. If no database name is supplied, the default
sample database is used. The user ID and password parameters are only needed if
the instance where the program is built is different from the instance where the
database is located.
The following examples show you how to build and run DB2 API and embedded
SQL applications.
To build the non-embedded SQL sample program, client, from the source file
client.cbl, enter:
bldapp client

The result is an executable file client.exe. You can run the executable file against
the sample database by entering the executable name (without the extension):
client

Procedure
v There are three ways to build the embedded SQL application, updat, from the
source file updat.sqb:
1. If connecting to the sample database on the same instance, enter:
bldapp updat

2. If connecting to another database on the same instance, also enter the

database name:
bldapp updat database

3. If connecting to a database on another instance, also enter the user ID and

password of the database instance:
bldapp updat database userid password

The result is an executable file, updat.exe.

v There are three ways to run this embedded SQL application:
Chapter 4. Building

195

1. If accessing the sample database on the same instance, enter the executable
name (without the extension):
updat

2. If accessing another database on the same instance, enter the executable

name and the database name:
updat database

3. If accessing a database on another instance, enter the executable name,

database name, and user ID and password of the database instance:
updat database userid password

Building and running embedded SQL applications written in

REXX
REXX applications are not precompiled, compiled, or linked. You can build and
run REXX applications on Windows operating systems, and on the AIX operating
system.

About this task

On Windows operating systems, your application file must have a .CMD extension.
After creation, you can run your application directly from the operating system
command prompt. On AIX, your application file can have any extension.

Procedure
To build and run your REXX applications:
v On Windows operating systems, your application file can have any name. After
creation, you can run your application from the operating system command
prompt by invoking the REXX interpreter as follows:
REXX file_name

v On AIX, you can run your application using either of the following two
methods:
At the shell command prompt, type rexx name where name is the name of
your REXX program.
If the first line of your REXX program contains a "magic number" (#!) and
identifies the directory where the REXX/6000 interpreter resides, you can run
your REXX program by typing its name at the shell command prompt. For
example, if the REXX/6000 interpreter file is in the /usr/bin directory,
include the following line as the very first line of your REXX program:
#! /usr/bin/rexx

Then, make the program executable by typing the following command at the
shell command prompt:
chmod +x name

Run your REXX program by typing its file name at the shell command
prompt.
Note: On AIX, you should set the LIBPATH environment variable to include the
directory where the REXX SQL library, db2rexx is located. For example:
export LIBPATH=/lib:/usr/lib:/$DB2PATH/lib

196

Developing Embedded SQL Applications

Bind files for REXX

Five bind files are provided to support REXX applications. The names of these files
are included in the DB2UBIND.LST file. Each bind file is precompiled using a
different isolation level; therefore, there are five different packages stored in the
database.
The five bind files are:
DB2ARXCS.BND
Supports the cursor stability isolation level.
DB2ARXRR.BND
Supports the repeatable read isolation level.
DB2ARXUR.BND
Supports the uncommitted read isolation level.
DB2ARXRS.BND
Supports the read stability isolation level.
DB2ARXNC.BND
Supports the no commit isolation level. This isolation level is used when
working with some host or System i database servers. On other databases,
it behaves such as the uncommitted read isolation level.
Note: In some cases, it can be necessary to explicitly bind these files to the
database.
When you use the SQLEXEC routine, the package created with cursor stability is
used as a default. If you require one of the other isolation levels, you can change
isolation levels with the SQLDBS CHANGE SQL ISOLATION LEVEL API, before
connecting to the database. This will cause subsequent calls to the SQLEXEC
routine to be associated with the specified isolation level.
Windows-based REXX applications cannot assume that the default isolation level is
in effect unless they know that no other REXX programs in the session have
changed the setting. Before connecting to a database, a REXX application should
explicitly set the isolation level.

Building Object REXX applications on Windows

Object REXX is an object-oriented version of the REXX language. Object-oriented
extensions have been added to classic REXX, but its existing functions and
instructions have not changed.

About this task

The Object REXX interpreter is an enhanced version of its predecessor, with
additional support for:
v Classes, objects, and methods
v Messaging and polymorphism
v Single and multiple inheritance
Object REXX is fully compatible with classic REXX. In this section, whenever REXX
is used, all versions of REXX are inferred, including Object REXX.
You do not precompile or bind REXX programs.
On Windows, REXX programs are not required to start with a comment. However,
for portability reasons you are recommended to start each REXX program with a
comment that begins in the first column of the first line. This will allow the
program to be distinguished from a batch command on other platforms:
Chapter 4. Building

197

/* Any comment will do. */

REXX sample programs can be found in the directory sqllib\samples\rexx.

To run the sample REXX program updat, enter:
rexx updat.cmd

Building embedded SQL applications from the command line

There are different methods that you can use to build embedded SQL applications,
such as by using build scripts or the command line. You can use the command line
if you want to test build options before writing a script to automate the process.
Building embedded SQL applications from the command line involves the
following steps:
1. Precompile the application by issuing the PRECOMPILE command
2. If you created a bind file, bind this file to a database to create an application
package by issuing the BIND command.
3. Compile the modified application source and the source files that do not
contain embedded SQL to create an application object file (a .obj file).
4. Link the application object files with the DB2 and host language libraries to
create an executable program using the link command.

Building embedded SQL applications written in C or C++

(Windows)
After you have written the source file, you have to build your embedded SQL
application.

About this task

Some steps in the build process depend on the compiler that you use. The
examples provided with each step of the procedure show how to build an
application called myapp with a Microsoft Visual Studio 6.0 compiler, which is a C
compiler. You can run each step in the procedure individually or run the steps
together within a batch file from a DB2 Command Window prompt. For an
example of a batch file that can be used to build the embedded SQL sample
applications in the %DB2PATH%\SQLLIB\samples\c\ directory, refer to the
%DB2PATH%\SQLLIB\samples\c\bldapp.bat file. This batch file calls another batch
file, %DB2PATH%\SQLLIB\samples\c\embprep.bat, to precompile the application and
bind the application to a database.
v An active database connection
v An application source code file with the extension .sqc in C or .sqx in C++ and
containing embedded SQL
v A supported C or C++ compiler
v The authorities or privileges required to run the PRECOMPILE command and BIND
command

Procedure
1. Precompile the application by issuing the PRECOMPILE command. For example:
C application: db2 PRECOMPILE myapp.sqc BINDFILE
C++ application: db2 PRECOMPILE myapp.sqx BINDFILE

198

Developing Embedded SQL Applications

The PRECOMPILE command generates a .c or .C file, that contains a modified

form of the source code in a .sqc or .sqC file, and an application package. If
you use the BINDFILE option, the PRECOMPILE command generates a bind file. In
the preceding example, the bind file would be called myapp.bnd.
2. If you created a bind file, bind this file to a database to create an application
package by issuing the BIND command. For example:
db2 bind myapp.bnd

The BIND command associates the application package with and stores the
package within the database.
3. Compile the modified application source and the source files that do not
contain embedded SQL to create an application object file (a .obj file). For
example:
C application: cl -Zi -Od -c -W2 -DWIN32 myapp.c
C++ application: cl -Zi -Od -c -W2 -DWIN32 myapp.cxx

4. Link the application object files with the DB2 and host language libraries to
create an executable program using the link command. For example:
link -debug -out:myapp.exe myapp.obj

Chapter 4. Building

199

200

Developing Embedded SQL Applications

Chapter 5. Deploying and running embedded SQL

applications
Embedded SQL applications are portable and can be placed in remote database
components. You can compile the application in one location and run the package
on a different component.

Use of the db2dsdriver.cfg configuration file by embedded SQL

applications
Embedded SQL applications support use of the db2dsdriver.cfg configuration file
for high availability solutions with supported servers.
You can use the db2dsdriver.cfg configuration file for work load balancing (WLB)
and automatic client reroute (ACR) with supported servers. The WLB and ACR
associated keywords are available for use with the embedded applications.
Table 23. Settings to control workload balancing behavior
Element in the db2dsdriver.cfg
configuration file

Section

Value

connectionLevelLoadBalancing
parameter

<database>

Must be set to true if you want to use transaction-level

workload balancing. The value is true by default.
However, the default is false if the server accessed is DB2
for z/OS .

enableWLB parameter

<wlb>

Specifies whether transaction-level workload balancing is

in effect. The value is false by default.

maxTransportIdleTime

<wlb>

Specifies the maximum elapsed time in number of

seconds before an idle transport is dropped. The default
is 60 seconds. The minimum supported value is 0.

maxTransportWaitTime

<wlb>

Specifies the number of seconds that the client waits for a

transport to become available. The default is 1 second.
The minimum supported value is 0 and -1 is used to
specify unlimited value.

maxTransports

<wlb>

Specifies the maximum number of physical connections

that can be made for each application process that
connects to the DB2 pureScale instance. The default is -1
(unlimited). However, the default is 1000 if the server
accessed is DB2 for z/OS.

maxRefreshInterval

<wlb>

Specifies the maximum elapsed time in number of

seconds before the server list is refreshed. The default is
10 seconds. The minimum supported value is 0.

Table 24. Settings to control automatic client reroute behavior

Element in the <acr> section of the db2dsdriver
configuration file

Value

enableAcr parameter

Specifies whether automatic client reroute is in effect. The

default is true. If the server accessed is DB2 for z/OS, the
enableAcr parameter should be enabled only when the
enableWLB parameter is in effect.

acrRetryInterval parameter

The number of seconds to wait between consecutive

connection retries. The registry variable
DB2_CONNRETRIES_INTERVAL overrides this value. The valid
range is 0 to MAX_INT. The default is no wait (0), if
DB2_CONNRETRIES_INTERVAL is not set. When enabling
automatic client reroute to the DB2 for z/OS data sharing
group, the default value of no wait is recommended.

Copyright IBM Corp. 1993, 2013

201

Table 24. Settings to control automatic client reroute behavior (continued)

Element in the <acr> section of the db2dsdriver
configuration file

Value

maxAcrRetries parameter

The maximum number of connection retries for automatic

client reroute. The registry variable
DB2_MAX_CLIENT_CONNRETRIES overrides this value. If
DB2_MAX_CLIENT_CONNRETRIES is not set, the default is that
the connection is tried again for 10 minutes. A value of 0
means that one attempt at reconnection is made. If the
server accessed isDB2 for z/OS, the maxAcrRetries is
recommended to be set to no higher than 5.

enableAlternateServerListFirstConnect parameter

Specifies whether there is an alternate server list that is

used only if a failure occurs on the first connection to the
data server. The default is false. When the value of
enableAlternateServerListFirstConnect is true,
automatic client reroute with seamless failover is implicitly
enabled, regardless of the other settings that are specified
for automatic client reroute in the db2dsdriver
configuration file. To use this feature, you also require an
<alternateserverlist> element in the db2dsdriver
configuration file. This parameter is not supported against
DB2 for z/OS.

alternateserverlist parameter

Specifies a set of server names and port numbers that

identify alternate servers to which a connection is
attempted if a failure occurs on the first connection to the
database. The alternate server list is not used after the first
connection. In a DB2 pureScale environment, the entries in
the list can be members of a DB2 pureScale instance. In a
non-DB2 pureScale environment, there is an entry for the
primary server and an entry for the high availability
disaster recovery (HADR) standby server. The alternate
server list is not used after the first connection.

The embedded application cannot perform seamless failover. Also, the ability to
resolve the data source name (DSN) with <dsncollection> section entry in the
db2dsdriver.cfg file is only supported with IBM Data Server Driver Package.
In DB2 Version 10 Fix Pack 1 and later fix packs, IBM data server clients supports
the use of the <dsncollection> section entry in the db2dsdriver.cfg file to resolve
DSN entry.
The following steps outline the process involved with database alias resolution:
1. The embedded SQL application requests to CONNECT to the database alias.
2. The embedded SQL application looks up the catalog database directory to see if
the specified database alias name exists.
v If information is found, the embedded application uses the database name,
host name, and port number information from the catalog. Proceed to step 4.
v If information is not found, the <dsncollection> sections in the
db2dsriver.cfg file is used to resolve the database alias name to the database
name, host name, and port number information.
3. The application looks for database alias information in the db2dsriver.cfg file:
v If database alias information is not found, a database connection error is
returned to the embedded SQL application.
v If database alias information is found, the database name, host name, port
number, and data server driver parameters that are specified in the <dsn>
section are used.
4. Using the database name, host name, and port number, the <databases> section
for matching entry is searched.

202

Developing Embedded SQL Applications

5. If a matching entry for the database name, host name, and port number is
found in the <databases> section, the parameters specified under the matching
<database> section is applied to the connection.
6. The database connection is attempted with information that is specified in the
catalog and db2dsdriver.cfg file.
In DB2 Version 10 Fix Pack 1 and later fix packs, embedded SQL application can
use following timeout values in the db2dsdriver.cfg file:
v MemberConnectTimeout
v
v
v
v

ReceiveTimeout
TcpipConnectTimeout
keepAliveTimeOut
ConnectionTimeout

Any unrecognized data server keywords are ignored silently by the embedded
SQL application.

Restrictions on linking to libdb2.so

On some Linux distributions, the libc development rpm comes with the
/usr/lib/libdb2.so or /usr/lib64/libdb2.so library. These libraries are used for
Sleepycat Software's Berkeley DB implementation and is not associated with IBM
DB2 database systems.
If you do not plan to use Berkeley DB, you can rename or delete these library files
permanently on your systems.
If you do want to use Berkeley DB, you can rename the folder containing these
library files and modify the environment variable to point to the new folder.

Chapter 5. Deploying and running

203

204

Developing Embedded SQL Applications

Chapter 6. Enabling compatibility features for migration

The DB2 database manager provides features that facilitate the migration of
embedded SQL C applications from other database systems.
You can enable these compatibility features by setting the precompiler option
COMPATIBILITY_MODE to ORA. For example, the following command enables
the compatibility features when you compile the file named tbsel.sqc:
$ db2 PRECOMPILE tbsel.sqc BINDFILE COMPATIBILITY_MODE ORA

When compatibility mode is switched on, the following features are supported:
v C-array host variables for use with FETCH INTO statements
v INDICATOR variable arrays for use with FETCH INTO statements
v New CONNECT statement syntax
v Using double quotation marks to specify file names with the INCLUDE
statement
v Simple type definition for the VARCHAR type
Starting in DB2 V10.1 Fix Pack 2 and later, when compatibility mode is switched
on, the following features are supported:
v Structure type and structure array indicators for an associated structure of
non-array or array host variables
v Suppression of unspecified indicator variable error if you do not specify the
NULL indicator in an application when it is needed, through setting the
UNSAFENULL parameter of the PRECOMPILE command to YES
v EXEC SQL ROLLBACK and EXEC SQL COMMIT statements with the RELEASE
option
Additionally, the following features are supported for embedded SQL C and
embedded SQL C++ applications even if you do not issue the PRECOMPILE
command with the COMPATIBILITY_MODE parameter set to ORA:
v Use of the STATICASDYNAMIC string for the GENERIC parameter of the BIND
command, to provide true dynamic SQL behavior for the package bound in a
session
v Use of a string literal with the PREPARE statement
v Use of the BREAK action with the WHENEVER statement

C-array host variables

By using C-array host variables, you can declare a cursor and do a bulk fetch into
the array variable until the end of the row is reached.
Array variables used in the same fetch need to have an equal number of elements,
otherwise the smallest number of elements declared for an array variable is used
and a warning is displayed. The size of the array variable can vary from 2 to 32K.
In one FETCH, the maximum number of records that can be retrieved is the
maximum number of elements declared for the array variables. If more rows are
available after the first fetch, you can repeat the FETCH statement to obtain the
next set of rows. The cumulative sum of the total number of rows fetched is stored
in sqlca.sqlerrd[2].
Copyright IBM Corp. 1993, 2013

205

In the following example, two array host variables are declared, empno and
lastname. Each can hold up to 100 elements. Because there is only one FETCH
statement, this example retrieves 100 rows, or less.
EXEC SQL BEGIN DECLARE SECTION;
char
empno[100][8];
char
lastname[100][15];
EXEC SQL END DECLARE SECTION;
EXEC SQL DECLARE empcr CURSOR FOR
SELECT empno, lastname FROM employee;
EXEC SQL OPEN empcr;
EXEC SQL WHENEVER NOT FOUND GOTO end_fetch;
while (1) {
EXEC SQL FETCH empcr INTO :empno :lastname;
...
...
}
end_fetch:
EXEC SQL CLOSE empcr;

/* bulk fetch
*/
/* 100 or less rows */

Starting in DB2 V10.1 Fix Pack 2, embedded SQL C/C++ applications support host
variables as a structure array during a fetch operation. The array size is
determined by the structure array that you define in the DECLARE SECTION
statement.
In the following example, a structure array of host variables is used for a FETCH
statement:
EXEC SQL BEGIN DECLARE SECTION;
struct MyStruct
{
int c1;
char c2[11];
} MyStructVar[3];
EXEC SQL END DECLARE SECTION;
...
// MyStrutVar is a structure array for host variables
EXEC SQL FETCH cur INTO :MyStructVar;

Note: Support is enabled only for PRECOMPILE option with COMPATIBILITY_MODE set
to ORA. A single FETCH operation does not support multiple structures or a
combination of structures and host variable arrays.
Embedded SQL C/C++ will create a compiler error if a structure array is defined
within the another structure array (for example, nested structure arrays).
Specific array element cannot be specified in the FETCH statement. Unexpected
token error may be returned.

INDICATOR variable arrays

In FETCH statements, you can use indicator variable arrays to determine whether
any elements of array variables are NULL. If an indicator variable contains a value
less than zero, this identifies the corresponding array value as NULL.
You can use the keyword INDICATOR to identify an indicator variable, as shown
in the example.

206

Developing Embedded SQL Applications

In the following example, the indicator variable array called bonus_ind is declared.
It can have up to 100 elements, the same amount as declared for the array variable,
bonus. When the data is being fetched, if the value of bonus is NULL, the value in
bonus_ind will be negative.
EXEC SQL BEGIN DECLARE SECTION;
char
empno[100][8];
char
lastname[100][15];
short edlevel[100];
double bonus[100];
short bonus_ind[100];
EXEC SQL END DECLARE SECTION;
EXEC SQL DECLARE empcr CURSOR FOR
SELECT empno, lastname, edlevel, bonus
FROM employee
WHERE workdept = D21;
EXEC SQL OPEN empcr;
EXEC SQL WHENEVER NOT FOUND GOTO end_fetch;
while (1) {
EXEC SQL FETCH empcr INTO :empno :lastname :edlevel,
:bonus INDICATOR :bonus_ind
...
...
}
end_fetch:
EXEC SQL CLOSE empcr;

Instead of being identified by the INDICATOR keyword, an indicator variable can

immediately following its corresponding host variable, as shown in the following
example:
EXEC SQL FETCH empcr INTO :empno :lastname :edlevel, :bonus:bonus_ind

If the number of elements for an indicator array variable does not match the
number of elements of the corresponding host array variable, an error is returned.
Starting in DB2 V10.1 Fix Pack 2 and later, application can now check
sqlca.sqlerrd[2] to get cumulative sum of number of rows populated successfully
till the last FETCH in non-arrays host variables. This enhancement is available
even if COMPATIBILITY_MODE ORA is not set during PRECOMPILE.
// declaring structure array of size 3 for indicator
EXEC SQL BEGIN DECLARE SECTION;
...
struct MyStructInd
{
short c1_ind;
short c2_ind;
} MyStructVarInd[3];
EXEC SQL END DECLARE SECTION;
...
// using structure array host variables & indicators structure type
// array while executing FETCH statement
// 'MyStructVar' is structure array for host variables
// 'MyStructVarInd' is structure array for indicators
EXEC SQL FETCH cur INTO :MyStructVar :MyStructVarInd;

Chapter 6. Enabling compatibility features for migration

207

Note: The array size of the structure that you use for indicator variables must be
equal to or greater than the array size of the structure that you use for host
variables. All members in the structure array that you use for indicator variables
must use the short data type. The number of members in the structures that you
use for host variables and corresponding indicators must be equal. The PRECOMPILE
command returns an error if any of the conditions are not satisfied.

New CONNECT statement syntax

The CONNECT statement now allows the following additional syntax:
EXEC SQL CONNECT [ username IDENTIFIED BY password ][ USING

dbname ] ;

The parameters are described in the following table:

Parameter

Description

username

Either a host variable or a string specifying

the database user name

password

Either a host variable or a string specifying

the password

dbname

Either a host variable or a string specifying

the database name

New UNSAFENULL PRECOMPILE option with functionality

Starting in DB2 V10.1 Fix Pack 2, you can set the UNSAFENULL parameter of the
PRECOMPILE command to YES to suppress the unspecified indicator variable error
while migrating to the DB2 product. This error is generated if the NULL value
exists but the application has not specified the NULL indicator.
# Suppress SQL0305N error.
db2 prep test.sqc COMPATIBILITY_MODE ORA UNSAFENULL YES
# Default behavior if null value is retrieved, SQL0305N error
db2 prep test.sqc COMPATIBILITY_MODE ORA UNSAFENULL NO
db2 prep test.sqc COMPATIBILITY_MODE ORA
db2 prep test.sqc
# Below both PRECOMPILE option give error as COMPATIBILITY_MODE ORA is not set.
db2 prep test.sqc UNSAFENULL YES
db2 prep test.sqc UNSAFENULL NO

Note: Even if you do not set the COMPATIBILITY_MODE parameter to ORA while
precompiling, an application can check the sqlca.sqlerrd[2] structure to get the
cumulative sum of the number of rows that were successfully populated till the
last fetch in non-array host variables.

Double quotation marks to specify include file names

You can use double quotation marks to specify include file names in the INCLUDE
directives (when COMPATIBILITY MODE is not set to ORA, only single quotation mark
are allowed). For example:
EXEC SQL INCLUDE "abc.h";

Simple type definition for the VARCHAR type

The following declaration of the VARCHAR type is supported. The precompiler
expands it into the equivalent C struct type:

208

Developing Embedded SQL Applications

EXEC SQL BEGIN DECLARE SECTION;

VARCHAR var_name [n+1];
EXEC SQL END DECLARE SECTION;

The STATICASDYNAMIC string for the GENERIC option on the

BIND command
If you set the STATICASDYNAMIC string for the GENERIC option of the BIND
command to "yes", the DB2 database manager simply stores all statements in the
catalogs and marks them as incremental bind. At run time, when the package is
first loaded, the database manager uses the current session environment (rather
than the package) to set up the section entries and other entities (text is populated
and the package cache is accessed).
Thereafter, the statements in the bound file behave the same as they would if you
were using dynamic SQL. For example, sections will be implicitly recompiled for
Database Definition Language invalidations, special register updates, and so on.
The new syntax is defined as follows:
DB2 BIND filename GENERIC STATICASDYNAMIC [YES|NO]

Using string literals with the PREPARE statement

The PREPARE statement is used by application programs to dynamically prepare
an SQL statement for execution. The PREPARE statement creates an executable
SQL statement from a character string form of the statement, called a statement
string.
For embedded C and embedded C++ applications, in addition to being able to
prepare statements from a host variable or from an expression, the statement string
can be a string literal.
For example: EXEC SQL PREPARE stmt_name FROM select empid from employee ;

The BREAK action in the WHENEVER statement

The WHENEVER statement specifies the action to be taken when a specified
exception condition occurs. For embedded C and embedded C++ applications, the
additional action, BREAK, is supported. This action causes current processing to
stop, for example, causes exit from a WHILE loop.
The following example causes the statements that follow to break out of a loop, if
an error or warning occurs or if no data is found:
EXEC SQL WHENEVER SQLERROR BREAK;
EXEC SQL WHENEVER SQLWARNING BREAK;
EXEC SQL WHENEVER NOT FOUND BREAK;

Support for RELEASE option in ROLLBACK statement and

COMMIT statement
Starting in DB2 V10.1 Fix Pack 2 and later, the ROLLBACK statement and
COMMIT statement can now specify connection reset option. Whenever a new
RELEASE option is used, users needed to reestablish the connection before doing
any activity with the same connection.
The following example will reset connection for ROLLBACK option:

Chapter 6. Enabling compatibility features for migration

209

EXEC SQL ROLLBACK RELEASE;

EXEC SQL ROLLBACK WORK RELEASE;

The following example will reset connection for COMMIT option:

EXEC SQL COMMIT RELEASE;
EXEC SQL COMMIT WORK RELEASE;

Note: The PRECOMPILE command issues SQL statement is not supported error if
you use the new syntax without setting the COMPATIBILITY_MODE parameter to ORA.

210

Developing Embedded SQL Applications

Appendix A. Overview of the DB2 technical information

DB2 technical information is available in multiple formats that can be accessed in
multiple ways.
DB2 technical information is available through the following tools and methods:
v DB2 Information Center
Topics (Task, concept and reference topics)
Sample programs
Tutorials
v DB2 books
PDF files (downloadable)
PDF files (from the DB2 PDF DVD)
printed books
v Command-line help
Command help
Message help
Note: The DB2 Information Center topics are updated more frequently than either
the PDF or the hardcopy books. To get the most current information, install the
documentation updates as they become available, or refer to the DB2 Information
Center at ibm.com.
You can access additional DB2 technical information such as technotes, white
papers, and IBM Redbooks publications online at ibm.com. Access the DB2
Information Management software library site at http://www.ibm.com/software/
data/sw-library/.

Documentation feedback
We value your feedback on the DB2 documentation. If you have suggestions for
how to improve the DB2 documentation, send an email to [email protected].
The DB2 documentation team reads all of your feedback, but cannot respond to
you directly. Provide specific examples wherever possible so that we can better
understand your concerns. If you are providing feedback on a specific topic or
help file, include the topic title and URL.
Do not use this email address to contact DB2 Customer Support. If you have a DB2
technical issue that the documentation does not resolve, contact your local IBM
service center for assistance.

DB2 technical library in hardcopy or PDF format

The following tables describe the DB2 library available from the IBM Publications
Center at www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss.
English and translated DB2 Version 10.1 manuals in PDF format can be
downloaded from www.ibm.com/support/docview.wss?rs=71&uid=swg27009474.
Although the tables identify books available in print, the books might not be
available in your country or region.
Copyright IBM Corp. 1993, 2013

211

The form number increases each time a manual is updated. Ensure that you are
reading the most recent version of the manuals, as listed below.
Note: The DB2 Information Center is updated more frequently than either the PDF
or the hard-copy books.
Table 25. DB2 technical information

212

Name

Form Number

Available in print

Availability date

Administrative API
Reference

SC27-5506-00

Yes

July 28, 2013

Administrative Routines
and Views

SC27-5507-00

No

July 28, 2013

Call Level Interface

Guide and Reference
Volume 1

SC27-5511-00

Yes

July 28, 2013

Call Level Interface

Guide and Reference
Volume 2

SC27-5512-00

Yes

July 28, 2013

Command Reference

SC27-5508-00

Yes

July 28, 2013

Database Administration SC27-4546-00

Concepts and
Configuration Reference

Yes

July 28, 2013

Data Movement Utilities SC27-5528-00

Guide and Reference

Yes

July 28, 2013

Database Monitoring
Guide and Reference

SC27-4547-00

Yes

July 28, 2013

Data Recovery and High

Availability Guide and
Reference

SC27-5529-00

Yes

July 28, 2013

Database Security Guide

SC27-5530-00

Yes

July 28, 2013

DB2 Workload
Management Guide and
Reference

SC27-5520-00

Yes

July 28, 2013

Developing ADO.NET
and OLE DB
Applications

SC27-4549-00

Yes

July 28, 2013

Developing Embedded
SQL Applications

SC27-4550-00

Yes

July 28, 2013

Developing Java
Applications

SC27-5503-00

Yes

July 28, 2013

Developing Perl, PHP,

Python, and Ruby on
Rails Applications

SC27-5504-00

No

July 28, 2013

Developing RDF
Applications for IBM
Data Servers

SC27-5505-00

Yes

July 28, 2013

Developing User-defined
Routines (SQL and
External)

SC27-5501-00

Yes

July 28, 2013

Getting Started with

Database Application
Development

GI13-2084-00

Yes

July 28, 2013

Developing Embedded SQL Applications

Table 25. DB2 technical information (continued)

Name

Form Number

Available in print

Availability date

Getting Started with

GI13-2085-00
DB2 Installation and
Administration on Linux
and Windows

Yes

July 28, 2013

Globalization Guide

SC27-5531-00

Yes

July 28, 2013

Installing DB2 Servers

GC27-5514-00

Yes

July 28, 2013

Installing IBM Data

Server Clients

GC27-5515-00

No

July 28, 2013

Message Reference
Volume 1

SC27-5523-00

No

July 28, 2013

Message Reference
Volume 2

SC27-5524-00

No

July 28, 2013

Net Search Extender

Administration and
User's Guide

SC27-5526-00

No

July 28, 2013

Partitioning and
Clustering Guide

SC27-5532-00

Yes

July 28, 2013

pureXML Guide

SC27-5521-00

Yes

July 28, 2013

Spatial Extender User's

Guide and Reference

SC27-5525-00

No

July 28, 2013

SQL Procedural
Languages: Application
Enablement and Support

SC27-5502-00

Yes

July 28, 2013

SQL Reference Volume 1 SC27-5509-00

Yes

July 28, 2013

SQL Reference Volume 2 SC27-5510-00

Yes

July 28, 2013

Text Search Guide

SC27-5527-00

Yes

July 28, 2013

Troubleshooting and
Tuning Database
Performance

SC27-4548-00

Yes

July 28, 2013

Upgrading to DB2
Version 10.5

SC27-5513-00

Yes

July 28, 2013

What's New for DB2

Version 10.5

SC27-5519-00

Yes

July 28, 2013

XQuery Reference

SC27-5522-00

No

July 28, 2013

Table 26. DB2 Connect-specific technical information

Name

Form Number

Available in print

Availability date

DB2 Connect Installing SC27-5516-00

and Configuring DB2
Connect Personal Edition

Yes

July 28, 2013

DB2 Connect Installing

and Configuring DB2
Connect Servers

SC27-5517-00

Yes

July 28, 2013

DB2 Connect User's

Guide

SC27-5518-00

Yes

July 28, 2013

Appendix A. Overview of the DB2 technical information

213

Displaying SQL state help from the command line processor

DB2 products return an SQLSTATE value for conditions that can be the result of an
SQL statement. SQLSTATE help explains the meanings of SQL states and SQL state
class codes.

Procedure
To start SQL state help, open the command line processor and enter:
? sqlstate or ? class code

where sqlstate represents a valid five-digit SQL state and class code represents the
first two digits of the SQL state.
For example, ? 08003 displays help for the 08003 SQL state, and ? 08 displays help
for the 08 class code.

Accessing different versions of the DB2 Information Center

Documentation for other versions of DB2 products is found in separate information
centers on ibm.com.

About this task

For DB2 Version 10.1 topics, the DB2 Information Center URL is
http://pic.dhe.ibm.com/infocenter/db2luw/v10r1.
For DB2 Version 9.8 topics, the DB2 Information Center URL is http://
pic.dhe.ibm.com/infocenter/db2luw/v9r8/.
For DB2 Version 9.7 topics, the DB2 Information Center URL is http://
pic.dhe.ibm.com/infocenter/db2luw/v9r7/.
For DB2 Version 9.5 topics, the DB2 Information Center URL is http://
publib.boulder.ibm.com/infocenter/db2luw/v9r5.

Terms and conditions

Permissions for the use of these publications are granted subject to the following
terms and conditions.
Applicability: These terms and conditions are in addition to any terms of use for
the IBM website.
Personal use: You may reproduce these publications for your personal,
noncommercial use provided that all proprietary notices are preserved. You may
not distribute, display or make derivative work of these publications, or any
portion thereof, without the express consent of IBM.
Commercial use: You may reproduce, distribute and display these publications
solely within your enterprise provided that all proprietary notices are preserved.
You may not make derivative works of these publications, or reproduce, distribute
or display these publications or any portion thereof outside your enterprise,
without the express consent of IBM.

214

Developing Embedded SQL Applications

Rights: Except as expressly granted in this permission, no other permissions,

licenses or rights are granted, either express or implied, to the publications or any
information, data, software or other intellectual property contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its
discretion, the use of the publications is detrimental to its interest or, as
determined by IBM, the previous instructions are not being properly followed.
You may not download, export or re-export this information except in full
compliance with all applicable laws and regulations, including all United States
export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE
PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING
BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
IBM Trademarks: IBM, the IBM logo, and ibm.com are trademarks or registered
trademarks of International Business Machines Corp., registered in many
jurisdictions worldwide. Other product and service names might be trademarks of
IBM or other companies. A current list of IBM trademarks is available on the Web
at www.ibm.com/legal/copytrade.shtml

Appendix A. Overview of the DB2 technical information

215

216

Developing Embedded SQL Applications

Appendix B. Notices
This information was developed for products and services offered in the U.S.A.
Information about non-IBM products is based on information available at the time
of first publication of this document and is subject to change.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information about 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 grant 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 character set (DBCS) information,
contact the IBM Intellectual Property Department in your country or send
inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country/region 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,
changes, or both in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to websites not owned by IBM are provided for
convenience only and do not in any manner serve as an endorsement of those
Copyright IBM Corp. 1993, 2013

217

websites. The materials at those websites are not part of the materials for this IBM
product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information that has been exchanged, should contact:
IBM Canada Limited
U59/3600
3600 Steeles Avenue East
Markham, Ontario L3R 9Z7
CANADA
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.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems, and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements, or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility, or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information may contain 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

218

Developing Embedded SQL Applications

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. The sample
programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work must
include a copyright notice as follows:
(your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. Copyright IBM Corp. _enter the year or years_. All rights
reserved.

Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the web at Copyright and
trademark information at www.ibm.com/legal/copytrade.shtml.
The following terms are trademarks or registered trademarks of other companies
v Linux is a registered trademark of Linus Torvalds in the United States, other
countries, or both.
v Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle, its affiliates, or both.
v UNIX is a registered trademark of The Open Group in the United States and
other countries.
v Intel, Intel logo, Intel Inside, Intel Inside logo, Celeron, Intel SpeedStep, Itanium,
and Pentium are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
v Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of
others.

Appendix B. Notices

219

220

Developing Embedded SQL Applications

Index
Special characters
.NET
batch files

165

Numerics
32-bit platforms
64-bit platforms

16
16

A
AIX
C applications
compiler and link options 168
C++ applications
compiler and link options 169
IBM COBOL applications
building 191
compiler and link options 182
Micro Focus COBOL applications
compiler and link options 183
application design
COBOL
include files 31
Japanese and traditional Chinese EUC
considerations 101
data passing 129
declaring sufficient SQLVAR entities 121
describing SELECT statement 124
executing statements without variables 13
NULL values 59
package versions with same name 163
parameter markers 131
retrieving data a second time 136
REXX 113
saving user requests 131
scrolling through previously retrieved data 136
SQLDA structure guidelines 125
variable-list SELECT statement processing 130
application development
COBOL example 94
embedded SQL overview 1
exit list routines 143
applications
binding 160
building embedded SQL 16, 198
embedded SQL 16, 198
arrays
host variables 67, 205
asynchronous events 20
authorities
binding 160

B
batch files
building embedded SQL applications
BIGINT data type
COBOL 46
Copyright IBM Corp. 1993, 2013

BIGINT data type (continued)

conversion to C/C++ 39
FORTRAN 49
BINARY data type
COBOL 94
embedded SQL 86
binary host variables 85
binary large objects (BLOBs)
COBOL 46
FORTRAN 49
REXX 51
bind API
deferred binding 159
BIND command
embedded SQL applications 198
package re-creation
re-creating 157
bind files
backward compatibility 158
embedded SQL applications 145, 149
REXX 197
bind list
DB2 Connect 160
bind options
overview 157, 158
BINDADD authority
DB2 Connect 160
binding
applications 160
authority 160
bind file description utility (db2bfd) 154
deferring 159
dynamic statements 157
DYNAMICRULES bind option 154
embedded SQL packages 158
overview 157
packages
DB2 Connect 160
embedded SQL 145
utilities
DB2 Connect 160
BLOB data type
COBOL 46
conversion to C/C++ 39
FORTRAN 49
REXX 51
blob_file C/C++ type 39
BLOB_FILE FORTRAN data type 49
blob_locator C/C++ type 39
BLOB_LOCATOR FORTRAN data type 49
BLOB-FILE COBOL type 46
BLOB-LOCATOR COBOL type 46
blocking
cursors 159
build scripts
C and C++ applications and routines 168
COBOL applications and routines 182
embedded SQL applications 165

165

221

C
C language
application template 26
applications
building (UNIX) 177
building (Windows) 178
compiler options (AIX) 168
compiler options (HP-UX) 170
compiler options (Linux) 172
compiler options (Solaris) 174
compiler options (Windows) 176
batch files 198
build files 165
development environment 26
error-checking utility files 167
multiconnection applications
building on Windows 180
multithreaded applications
Windows 178
C/C++ language
applications
building (Windows) 178
compiler options (AIX) 169
compiler options (HP-UX) 171
compiler options (Linux) 173
compiler options (Solaris) 175
compiler options (Windows) 176
executing static SQL statements 119
input files 25
multiple thread database access 20
output files 25
build files 165
Chinese (Traditional) EUC considerations
class data members 84
comments 119
connecting to databases 37
data types
functions 44
methods 44
overview 39
stored procedures 44
supported 39
declaring graphic host variables 74
disconnecting from databases 143
embedded SQL statements 2
error-checking utility files 167
file reference declarations 83
FOR BIT DATA 88
graphic host variables 74, 77, 78
host structure support 89
host variables
declaring 65
initializing 88
naming 64
purpose 63
include files 29
indicator tables 91
Japanese EUC considerations 87
LOB data declarations 80
LOB locator declarations 82
member operator restrictions 87
multiconnection applications
building (Windows) 180
multithreaded applications
Windows 178
null-terminated strings 92
numeric host variables 71

222

87

Developing Embedded SQL Applications

C/C++ language (continued)

pointers to data types 83
programming considerations 17
qualification operator restrictions 87
restrictions
#ifdefs 88
SQLCODE variables 67
sqldbchar data type 75
SQLSTATE variables 67
stored procedures 133
VisualAge configuration files (AIX) 180
wchar_t data type 75
WCHARTYPE precompiler option 75
C# .NET
batch files 165
char C/C++ data type 39
CHAR data type
COBOL 46
conversion to C/C++ 39
FORTRAN 49
REXX 51
character host variables
C/C++ fixed and null-terminated 72
FORTRAN 106
character sets
multibyte in FORTRAN 110
CHARACTER*n FORTRAN data type 49
Chinese (Traditional) code sets
C/C++ 87
COBOL 101
FORTRAN 110
class data members 84
CLOB data type
C/C++ 39, 88
COBOL 46
FORTRAN 49
REXX 51
clob_file C/C++ data type 39
CLOB_FILE FORTRAN data type 49
clob_locator C/C++ data type 39
CLOB_LOCATOR FORTRAN data type 49
CLOB-FILE COBOL type 46
CLOB-LOCATOR COBOL type 46
COBOL language
AIX
IBM compiler 187
Micro Focus compiler 190
applications
host variables 93
input files 25
output files 25
static SQL statements 119
build files 165
Chinese (Traditional) EUC 101
comments 119
connecting to databases 37
data types
BINARY 94
COMP 94
COMP-4 94
supported SQL data types in COBOL embedded SQL
applications 46
disconnecting from databases 143
embedded SQL statements 5
error-checking utility files 167
FOR BIT DATA 101
host structures 102

COBOL language (continued)

host variables
declaring 94
declaring file reference 100
declaring fixed-length character 96
declaring graphic 97
declaring numeric 95
naming 93
IBM COBOL applications
building (AIX) 191
building (Windows) 193
compiler options (AIX) 182
compiler options (Windows) 185
IBM COBOL compiler
Windows 187
include files 31
indicator tables 104
Japanese EUC 101
LOB data declarations 98
LOB locator declarations 100
Micro Focus applications
building (UNIX) 192
building (Windows) 195
compiler options (AIX) 183
compiler options (HP-UX) 184
compiler options (Linux) 185
compiler options (Solaris) 184
compiler options (Windows) 186
Micro Focus compiler
HP-UX 191
Linux 189
Solaris 191
Windows 188
REDEFINES 100
restrictions 18
SQLCODE variables 95
SQLSTATE variables 95
code pages
binding 158
collating sequences
include files
C/C++ 29
COBOL 31
FORTRAN 34
COLLECTION parameters 164
columns
data types
creating (C/C++) 39
creating (COBOL) 46
creating (FORTRAN) 49
SQL 56
null values
null-indicator variables 59
comments
SQL
C and C++ applications 2
COBOL applications 5
FORTRAN applications 4
REXX applications 6
COMP data types 94
COMP-1 data types 46
COMP-3 data types 46
COMP-4 data types 94
COMP-5 data types 46
compilers
build files 165
embedded SQL applications 8

compilers (continued)
IBM COBOL
AIX 187
Windows 187
Micro Focus COBOL
AIX 190
HP-UX 191
Solaris 191
Windows 188
compiling
embedded SQL applications 153
completion codes
SQL statements 36
configuration files
VisualAge 168
VisualAge C++ (AIX) 180
consistency
tokens 152
contexts
application dependencies between 23
database dependencies between 23
setting between threads 20
setting in multithreaded DB2 applications
details 20
CREATE IN COLLECTION NULLID authority 160
CREATE PROCEDURE statement
embedded SQL applications 133
critical sections
multithreaded embedded SQL applications 23
CURRENT EXPLAIN MODE special register
dynamic SQL statements 157
CURRENT PATH special register
bound dynamic SQL 157
CURRENT QUERY OPTIMIZATION special register
bound dynamic SQL 157
cursors
embedded SQL applications 135, 138
multiple in application 138
names
REXX 6
processing
SQLDA structure 125
summary 138
rows
deleting 139
retrieving 138
updating 139
sample program 139

D
data
deleting
statically executed SQL applications 139
fetched 136
retrieving
second time 136, 137
scrolling through previously retrieved 136
updating
previously retrieved data 138
statically executed SQL applications 139
Data Manipulation Language (DML)
dynamic SQL performance 13
data retrieval
static SQL 135
data structures
user-defined with multiple threads 22
Index

223

data types
BINARY 94
C
embedded SQL applications 39,
C++
embedded SQL applications 39,
class data members in C/C++ 84
CLOB 88
COBOL 46
compatibility issues 56
conversion
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
DECIMAL
FORTRAN 49
embedded SQL applications
C/C++ 39, 84, 88
mappings 56
FOR BIT DATA
C/C++ 88
COBOL 101
FORTRAN 49
graphic types 75
host variables 56, 84
mappings
embedded SQL applications 38,
pointers in C/C++ 83
VARCHAR
C/C++ 88
databases
accessing
multiple threads 20
contexts 20
DATE data type
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
DB2 Information Center
versions 214
DB2ARXCS.BND REXX bind file 197
db2bfd command
overview 154
db2dclgn command
declaring host variables 56
DBCLOB data type
COBOL 46
REXX 51
dbclob_file C/C++ data type 39
dbclob_locator C/C++ data type 39
DBCLOB-FILE COBOL data type 46
DBCLOB-LOCATOR COBOL data type
ddcs400.lst file 160
ddcsmvs.lst file 160
ddcsvm.lst file 160
ddcsvse.lst file 160
DDL
statements
dynamic SQL performance 13
deadlocks
multithreaded applications 23
DECIMAL data type
conversion
C/C++ 39
COBOL 46

224

84, 88
84, 88

56

46

Developing Embedded SQL Applications

DECIMAL data type (continued)

conversion (continued)
FORTRAN 49
REXX 51
declare sections
C and C++ embedded SQL applications 65
COBOL embedded SQL applications 94
FORTRAN embedded SQL applications 105
DECLARE statements
C/C++ declare section 65, 66
COBOL declare section 94
FORTRAN declare section 105
statement rules 53
DESCRIBE statement
processing arbitrary statements 130
documentation
overview 211
PDF files 211
printed 211
terms and conditions of use 214
DOUBLE data type
C/C++ programs 39
dynamic SQL
arbitrary statements
determining type 130
processing 130
binding 157
cursors
processing 125
deleting rows 139
DESCRIBE statement
overview 13, 120
DYNAMICRULES effects 154
embedded SQL comparison 13
EXECUTE IMMEDIATE statement
overview 13
EXECUTE statement
overview 13
limitations 13
overview 13
parameter markers 131
performance
static SQL comparison 13
PREPARE statement
overview 13
SQLDA
declaring 121
static SQL comparison 13
support statements 13
DYNAMICRULES precompile/bind option
effects on dynamic SQL 154

E
embedded SQL applications
access plans 160
authorization 11
C/C++
include files 29
restrictions 17
statements 2
COBOL
include files 31
statements 5
compiling 8, 201
db2dsdriver.cfg file 201
declare section 2

embedded SQL applications (continued)

deploying 201
designing 25
development environment 8
dynamic statement execution 12, 118
errors 153
FORTRAN
include files 34
restrictions 18
statements 4
host variables
overview 53
referencing 62
include files
C/C++ 29
COBOL 31
FORTRAN 34
overview 29
operating systems supported 8
overview 1
packages 163
performance
BIND command REOPT option 160
overview 15
precompiling
applications accessing multiple servers 148
errors 153
warnings 153
programming 25
restrictions
C/C++ 17
FORTRAN 18
overview 17
REXX 18
REXX
restrictions 18
statements 6
SQLCA structure 2
statements
C/C++ 2
COBOL 5
FORTRAN 4
REXX 6
static statement execution 12, 118
warnings 153
XML values 59
error messages
handling 36
SQLCA structure 142
SQLCODE field 142
SQLSTATE field 142
SQLWARN field 142
warning condition flag 142
errors
checking using utility files 167
embedded SQL applications
C/C++ include files 29
COBOL include files 31
FORTRAN include files 34
SQLCA structure fields 61
SQLCA structures 36
examples
class data members in SQL statements 84
parameter markers in dynamic SQL program 132
REXX program 113
SQL declare section template 66

exception handlers
overview 143
EXEC SQL INCLUDE SQLCA statement
EXECUTE IMMEDIATE statement
overview 13
EXECUTE statement
overview 13
exit list routines 143
explain snapshots
binding 158
Extended UNIX Code (EUC)
Chinese (Traditional)
C/C++ applications 87
COBOL applications 101
FORTRAN applications 110
Japanese
C/C++ applications 87
COBOL applications 101
FORTRAN applications 110

22

F
FETCH statement
host variables 120
repeated data access 136
SQLDA structure 124
file reference declarations in REXX 115
files
reference declarations in C/C++ 83
FIPS 127-2 standard
declaring SQLSTATE and SQLCODE as host variables
flagger utility for precompiling 147
FLOAT data type
C/C++ conversion 39
COBOL 46
FORTRAN 49
REXX 51
FOR BIT DATA data type 88
FOR UPDATE clause
details 139
FORTRAN language
applications
host variables 104
input files 25
output files 25
Chinese (Traditional) code set 110
comments 119
connecting to databases 37
data types 49
embedding SQL statements 4
file reference declarations 109
host variables
declaring 105
naming 104
referencing 4
include files 34
indicator variables 110
Japanese code set 110
LOB data declarations 108
LOB locator declarations 109
multibyte character sets 110
numeric host variables 106
programming 18
restrictions 104
SQL declare section example 105
SQLCODE variables 105
SQLSTATE variables 105
Index

142

225

G
get error message API
error message retrieval 140
predefined REXX variables 111
graphic data
host variables
C/C++ embedded SQL applications 78
COBOL embedded SQL applications 97
VARGRAPHIC 77
GRAPHIC data type
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
selecting 75

H
help
SQL statements 214
host structure support
C/C++ 89
COBOL 102
host variables
C-array 67
C/C++ applications 63
character data declarations
COBOL 96
FORTRAN 106
class data members 84
COBOL applications 46
declaring
C/C++ 65
COBOL 94
db2dclgn declaration generator 56
embedded SQL application overview
FORTRAN 105
variable list statement 130
dynamic SQL 13
embedded SQL applications
C/C++ 80
COBOL 98
FORTRAN 108
overview 53
REXX 114
enabling compatibility features 205
file reference declarations
C/C++ 83
COBOL 100
FORTRAN 109
REXX 115
REXX (clearing) 116
FORTRAN applications 4
graphic data
C/C++ 74, 75
COBOL 97
FORTRAN 110
host language statements 53
initializing in C/C++ 88
LOB data declarations
C/C++ 80
COBOL 98
FORTRAN 108
REXX 114
LOB file reference declarations 116

226

host variables (continued)

LOB locator declarations
C/C++ 82
COBOL 100
FORTRAN 109
REXX 115
REXX (clearing) 116
naming
C/C++ 64
COBOL 93
FORTRAN 104
REXX 111
null-terminated strings 92
pointers in C/C++ 83
referencing from SQL 62
REXX applications 111
SQL statements 53
static SQL 53
truncation 59
WCHARTYPE precompiler option 75
HP-UX
compiler options
C applications 170
C++ applications 171
Micro Focus COBOL applications 184
link options
C applications 170
C++ applications 171
Micro Focus COBOL applications 184

I
55

Developing Embedded SQL Applications

include files
C/C++ embedded SQL applications 29
COBOL embedded SQL applications 31
FORTRAN embedded SQL applications 34
locating in COBOL applications 5
overview 29
INCLUDE SQLCA statement
declaring SQLCA structure 36
INCLUDE SQLDA statement
creating SQLDA structure 125
INCLUDE statement
BIND command
STATICASDYNAMIC option 205
CONNECT statement 205
double quotation marks 205
indicator tables
C/C++ 91
COBOL 104
indicator variables
C 67
compatibility features 205
FORTRAN 110
identifying null SQL values 59
REXX 116
INTEGER data type
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
INTEGER*2 FORTRAN data type 49
INTEGER*4 FORTRAN data type 49
interrupt handlers
overview 143
isolation levels
repeatable read (RR) 136

J
Japanese Extended UNIX Code (EUC) code page
C/C++ embedded SQL applications 87
COBOL embedded SQL applications 101
FORTRAN embedded SQL applications 110

L
LANGLEVEL precompile option
MIA 39
SAA1 39
SQL92E 67, 95, 105
large objects (LOBs)
C/C++ declarations 80
locators
declarations in C/C++ 82
latches 20
libdb2.so libraries
restrictions 203
link options
C applications 170
linking
details 153
Linux
C
applications 172
C++
applications 173
libraries
libaio.so.2 203
Micro Focus COBOL
applications 185
configuring compilers 189
LOB data type
data declarations in C/C++ 80
long C/C++ data type 39
long int C/C++ data type 39
long long C/C++ data type 39
long long int C/C++ data type 39
LONG VARCHAR data type
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
LONG VARGRAPHIC data type
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51

N
notices 217
NULL
SQL value
indicator variables 59
null-terminated character form
null-terminator 39
NULLID 160
NUMERIC data type
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
numeric host variables
C/C++ 71
COBOL 95
FORTRAN 106

39

O
Object REXX for Windows applications
building 197
optimizer
dynamic SQL 13
static SQL 13

M
macro expansion
C/C++ language 88
member operators
C/C++ restriction 87
MIA LANGLEVEL precompile option
multi-threaded applications
building
C++ (Windows) 178
files 165
multibyte code pages
Chinese (Traditional) code sets
C/C++ 87
COBOL 101
FORTRAN 110

multibyte code pages (continued)

Japanese code sets
C/C++ 87
COBOL 101
FORTRAN 110
multiconnection applications
build files 165
building Windows C/C++ 180

39

packages
creating
BIND command and existing bind file
embedded SQL applications 149
host database servers 160
inoperative 158
invalid state 158
privileges
overview 163
REXX application support 197
schemas 149
System i database servers 160
time stamp errors 152
versions
privileges 163
same name 163
parameter markers
dynamic SQL
determining statement type 130
example 132
variable input 131
examples 132
typed 131
performance
dynamic SQL 13
FOR UPDATE clause 139
PICTURE (PIC) clause in COBOL types 46

157

Index

227

precompilation
accessing host application servers through DB2
Connect 147
accessing multiple servers 147
C/C++ 87
consistency tokens 152
dynamic SQL statements 13
embedded SQL applications 147
flagger utility 147
FORTRAN 18
time stamps 152
PRECOMPILE command
embedded SQL applications
accessing multiple database servers 148
building from command line 198
C/C++ 198
overview 145
PREPARE statement
arbitrary statement processing 130
overview 13
preprocessor functions
SQL precompiler 88
procedures
CALL statement 133
parameters
types 133

Q
qualification operator in C/C++ 87
queryopt precompile/bind option
code page considerations 158

R
REAL SQL data type
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
REAL*2 FORTRAN SQL data type 49
REAL*4 FORTRAN SQL data type 49
REAL*8 FORTRAN SQL data type 49
REBIND command
rebinding 158
rebinding
process 158
REBIND command 158
REDEFINES clause
COBOL 100
repeatable read (RR)
re-retrieving data 136
result codes 36
RESULT REXX predefined variable 111
return codes
declaring SQLCA 36
REXX language
APIs
SQLDB2 18
SQLDBS 18
SQLEXEC 18
applications
embedded SQL (building) 196
embedded SQL (running) 196
host variables 110
bind files 197

228

Developing Embedded SQL Applications

REXX language (continued)

comments 119
connecting to databases 37
cursor identifiers 6
data types 51
disconnecting from databases 143
embedded SQL statements 6, 119, 196
host variables
naming 111
referencing 111
indicator variables 116
initializing variables 135
LOB file reference declarations 115
LOB host variables 114, 116
LOB locator declarations 115
predefined variables 111
registering routines 113
restrictions 18, 110
running applications 196
SQLDB2 API 113
SQLDBS API 113
SQLEXEC API 113
stored procedures
overview 135
Windows applications 197
routines
build files 165
rows
retrieving
multiple 138
using SQLDA 124
second retrieval
methods 136
row order 137
RUNSTATS command
statistics collection 15
runtime services
multiple threads effect on latches 20

S
SAA1 LANGLEVEL precompile option 39
samples
IBM COBOL 182
SELECT statement
declaring SQLDA 121
describing after allocating SQLDA 124
EXECUTE statement 13
retrieving
data a second time 136
multiple rows 138
updating retrieved data 138
variable-list 130
semaphores 23
serialization
data structures 22
SQL statement execution 20
SET CURRENT PACKAGESET statement 149, 164
short data type
C/C++ 39
short int data type 39
signal handlers
overview 143
SMALLINT data type
C/C++ 39
COBOL 46
FORTRAN 49

SMALLINT data type (continued)

REXX 51
Solaris operating systems
C applications 174
C++ applications 175
Micro Focus COBOL applications 184
special registers
CURRENT EXPLAIN MODE 157
CURRENT EXPLAIN SNAPSHOT 157
CURRENT PATH 157
CURRENT QUERY OPTIMIZATION 157
SQL
authorization for embedded SQL 11
include files
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
SQL data types
embedded SQL applications
C/C++ 39
COBOL 46
FORTRAN 49
overview 56
REXX 51
SQL statements
C/C++ syntax 2
COBOL syntax 5
dynamic 1, 11
embedded 1, 11
exception handlers 143
FORTRAN syntax 4
help
displaying 214
INCLUDE 36
interrupt handlers 143
preparing using minimum SQLDA structure 122
REXX syntax 6
saving end user requests 131
serializing execution 20
signal handlers 143
static 1, 11
SQL_WCHART_CONVERT preprocessor macro 75
SQL1252A include file
COBOL applications 31
FORTRAN applications 34
SQL1252B include file
COBOL applications 31
FORTRAN applications 34
SQLADEF include file 29
SQLAPREP include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
SQLCA structure
declaring 36
include files
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
multithreading 22
overview 142
predefined variable 111
SQLCODE field 142
SQLSTATE field 142
SQLWARN1 field 59
warnings 59

SQLCA_92 include file

COBOL applications 31
FORTRAN applications 34
SQLCA_CN include file 34
SQLCA_CS include file 34
SQLCHAR structure
passing data with 129
SQLCLI include file 29
SQLCLI1 include file 29
SQLCODE
overview 36, 142
SQLCODES include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
SQLDA
creating 125
declaring 121
declaring sufficient SQLVAR entities 123
determining statement type 130
include files
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
multithreading 22
passing data 129
prepared statements 13
preparing statements using minimum structure
SQLDACT include file 34
SQLDB2 API
registering for REXX 113
sqldbchar data type
C/C++ embedded SQL applications 75
equivalent column type 39
SQLDBS API 113
SQLE819A include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
SQLE819B include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
SQLE850A include file
COBOL applications 31
FORTRAN applications 34
SQLE850B include file
COBOL applications 31
FORTRAN applications 34
SQLE859A include file 29
SQLE859B include file 29
SQLE932A include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
SQLE932B include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
sqleAttachToCtx API
multiple contexts 20
SQLEAU include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
sqleBeginCtx API
multiple contexts 20

122

Index

229

sqleDetachFromCtx API
multiple contexts 20
sqleEndCtx API
multiple contexts 20
sqleGetCurrentCtx API
multiple contexts 20
sqleInterruptCtx API
multiple contexts 20
SQLENV include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
sqleSetTypeCtx API
multiple contexts 20
SQLETSD include file 31
SQLException
embedded SQL applications 140
SQLEXEC REXX API
processing SQL statements 6
registering 113
restrictions 18
SQLEXT include file 29
sqlint64 C/C++ data type 39
SQLISL predefined variable 111
SQLJACB include file 29
SQLMON include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
SQLMONCT include file 31
SQLMSG predefined variable 111
SQLRDAT predefined variable 111
SQLRIDA predefined variable 111
SQLRODA predefined variable 111
SQLSTATE
include files
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
overview 142
SQLSYSTM include file 29
SQLUDF include file
C/C++ applications 29
SQLUTBCQ include file 31
SQLUTBSQ include file 31
SQLUTIL include file
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34
SQLUV include file 29
SQLUVEND include file 29
SQLVAR entities
declaring sufficient number 121, 123
SQLWARN
overview 142
SQLXA include file 29
static SQL
comparison to dynamic SQL 13
host variables 53, 55
retrieving data 135
storage
allocating to hold rows 124
declaring sufficient SQLVAR entities 121
stored procedures
REXX applications 135
success codes 36

230

Developing Embedded SQL Applications

symbols
C/C++ language restrictions

88

T
tables
fetching rows 139
names
resolving unqualified 164
resolving unqualified names 164
terms and conditions
publications 214
threads
multiple
embedded SQL applications 20, 23
recommendations 22
UNIX applications 22
TIME data types
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
time stamps
precompiler-generated 152
TIMESTAMP data type
C/C++ 39
COBOL 46
FORTRAN 49
REXX 51
truncation
host variables 59
indicator variables 59
typed parameter markers 131

U
UNIX
C applications
building 177
Micro Focus COBOL applications
USAGE clause in COBOL types 46
utilities
binding 160
ddcspkgn 160
utility APIs
include files
C/C++ applications 29
COBOL applications 31
FORTRAN applications 34

V
VARBINARY data type
embedded SQL applications 86
host variables 85
VARCHAR data type
C/C++
details 39
FOR BIT DATA substitute 88
COBOL 46
conversion to C/C++ 39
FORTRAN 49
REXX 51
VARGRAPHIC data type
C/C++ conversion 39
COBOL 46

192

VARGRAPHIC data type (continued)

FORTRAN 49
REXX 51
variables
REXX 111
SQLCODE 67, 95, 105
SQLSTATE 67, 95, 105
Visual Basic .NET
batch files 165

W
warnings
truncation 59
wchar_t data type
C/C++ embedded SQL applications 75
WCHARTYPE precompiler option
data types available with NOCONVERT and CONVERT
options 39
details 75
Windows
C/C++ applications
building 178
compiler options 176
link options 176
COBOL applications
building 193
compiler options 185
link options 185
Micro Focus COBOL applications
building 195
compiler options 186
link options 186

X
XML
C/C++ applications
executing XQuery expressions 117
COBOL applications 117
declarations
embedded SQL applications 57
XMLQUERY function 19
XQuery expressions 19, 117
XML data retrieval
C applications 62
COBOL applications 62
XML data type
host variables in embedded SQL applications 57
identifying in SQLDA 59
XML encoding
overview 57
XQuery statements
declaring host variables in embedded SQL applications

57

Index

231

232

Developing Embedded SQL Applications




Printed in USA

SC27-4550-00

IBM DB2 10.5 for Linux, UNIX, and Windows

Spine information:

Developing Embedded SQL Applications