![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-23-320.jpg)
![#include <stdio.h> 1
#include <stdlib.h>
#include <string.h>
#include <sqlenv.h>
#include <sqlutil.h>
EXEC SQL BEGIN DECLARE SECTION; 2
short id;
char name[10];
short dept;
double salary;
char hostVarStmtDyn[50];
EXEC SQL END DECLARE SECTION;
int main()
{
int rc = 0; 3
EXEC SQL INCLUDE SQLCA; 4
/* connect to the database */
printf("n Connecting to database...");
EXEC SQL CONNECT TO "sample"; 5
if (SQLCODE <0) 6
{
printf("nConnect Error: SQLCODE =
goto connect_reset;
}
else
{
printf("n Connected to database.n");
}
/* 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 310n");
printf("n ID Name DEPT Salaryn");
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) 6
{
printf("Prepare Error: SQLCODE =
}
else
{
EXEC SQL EXECUTE StmtDyn USING :dept; 8
}
if (SQLCODE <0) 6
{
printf("Execute Error: SQLCODE =
Chapter 3. Programming 27](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-33-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-43-320.jpg)
![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 SQL Column Type Description
SMALLINT
(500 or 501)
short
short int
sqlint16
16-bit signed integer
INTEGER
(496 or 497)
int
long
long int
sqlint322
32-bit signed integer
BIGINT
(492 or 493)
long long
long
__int64
sqlint643
64-bit signed integer
REAL5
(480 or 481)
float Single-precision floating point
DOUBLE6
(480 or 481)
double Double-precision floating point
DECIMAL(p,s)
(484 or 485)
No exact equivalent; use double Packed decimal
(Consider using the CHAR and DECIMAL
functions to manipulate packed decimal
fields as character data.)
CHAR(1)
(452 or 453)
char Single character
CHAR(n)
(452 or 453)
No exact equivalent; use
char[n+1] where n is large enough
to hold the data
1<=n<=254
Fixed-length character string
Chapter 3. Programming 39](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-45-320.jpg)
![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]
}
1<=n<=32 672
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:
struct tag {
short int;
char[n]
}
Alternatively, use char[n+1] where
n is large enough to hold the data
1<=n<=32 672
Null-terminated variable-length character
string
Note: Assigned an SQL type of 460/461.
LONG VARCHAR8
(456 or 457)
struct tag {
short int;
char[n]
}
32 673<=n<=32 700
Non null-terminated varying character string
with 2-byte string length indicator
CLOB(n)
(408 or 409)
sql type is
clob(n)
1<=n<=2 147 483 647
Non null-terminated varying character string
with 4-byte string length indicator
CLOB locator variable7
(964 or 965)
sql type is
clob_locator
Identifies CLOB entities residing on the
server
CLOB file reference variable7
(920 or 921)
sql type is
clob_file
Descriptor for file containing CLOB data
BLOB(n)
(404 or 405)
sql type is
blob(n)
1<=n<=2 147 483 647
Non null-terminated varying binary string
with 4-byte string length indicator
BLOB locator variable7
(960 or 961)
sql type is
blob_locator
Identifies BLOB entities on the server
BLOB file reference variable7
(916 or 917)
sql type is
blob_file
Descriptor for the file containing BLOB data
DATE
(384 or 385)
Null-terminated character form Allow at least 11 characters to accommodate
the null-terminator
VARCHAR structured form Allow at least 10 characters
TIME
(388 or 389)
Null-terminated character form Allow at least 9 characters to accommodate
the null-terminator
VARCHAR structured form Allow at least 8 characters
40 Developing Embedded SQL Applications](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-46-320.jpg)
![Table 2. SQL Data Types Mapped to C and C++ Declarations (continued)
SQL Column Type1
C and C++ Data Type SQL Column Type Description
TIMESTAMP(p)
4
(392 or 393)
Null-terminated character form Allow 20- 33 characters to accommodate for
the null-terminator
VARCHAR structured form Allow 19-32 characters.
XML8
(988 or 989)
struct {
sqluint32 length;
char data[n];
}
1<=n<=2 147 483 647
SQLUDF_CLOB
XML value
BINARY unsigned char myBinField[4];
1<= n <=255
Binary data
VARBINARY struct
myVarBinField_t
{sqluint16 length;char data[12];}
myVarBinField;
1<= n <=32704
Varbinary data
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
GRAPHIC(1)
(468 or 469)
sqldbchar Single double-byte character
GRAPHIC(n)
(468 or 469)
No exact equivalent; use
sqldbchar[n+1] where n is large
enough to hold the data
1<=n<=127
Fixed-length double-byte character string
VARGRAPHIC(n)
(464 or 465)
struct tag {
short int;
sqldbchar[n]
}
1<=n<=16 336
Non null-terminated varying double-byte
character string with 2-byte string length
indicator
Alternatively use sqldbchar[n+1]
where n is large enough to hold
the data
1<=n<=16 336
Null-terminated variable-length double-byte
character string
Note: Assigned an SQL type of 400/401.
Chapter 3. Programming 41](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-47-320.jpg)
![Table 3. SQL Data Types Mapped to C and C++ Declarations (continued)
SQL Column Type1
C and C++ Data Type SQL Column Type Description
LONG VARGRAPHIC8
(472 or 473)
struct tag {
short int;
sqldbchar[n]
}
16 337<=n<=16 350
Non null-terminated varying double-byte
character string with 2-byte string length
indicator
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
GRAPHIC(1)
(468 or 469)
wchar_t v Single wide character (for C-type)
v Single double-byte character (for column
type)
GRAPHIC(n)
(468 or 469)
No exact equivalent; use wchar_t
[n+1] where n is large enough to
hold the data
1<=n<=127
Fixed-length double-byte character string
VARGRAPHIC(n)
(464 or 465)
struct tag {
short int;
wchar_t [n]
}
1<=n<=16 336
Non null-terminated varying double-byte
character string with 2-byte string length
indicator
Alternately use char[n+1] where n
is large enough to hold the data
1<=n<=16 336
Null-terminated variable-length double-byte
character string
Note: Assigned an SQL type of 400/401.
LONG VARGRAPHIC8
(472 or 473)
struct tag {
short int;
wchar_t [n]
}
16 337<=n<=16 350
Non null-terminated varying double-byte
character string with 2-byte string length
indicator
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)
1<=n<=1 073 741 823
Non null-terminated varying double-byte
character string with 4-byte string length
indicator
42 Developing Embedded SQL Applications](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-48-320.jpg)
![Table 5. SQL Data Types Mapped to C and C++ Declarations (continued)
SQL Column Type1
C and C++ Data Type SQL Column Type Description
DBCLOB locator variable7
(968 or 969)
sql type is
dbclob_locator
Identifies DBCLOB entities residing on the
server
DBCLOB file reference
variable7
(924 or 925)
sql type is
dbclob_file
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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-49-320.jpg)
![– 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
SMALLINT
(500 or 501)
short 16-bit signed integer
INTEGER
(496 or 497)
sqlint32 32-bit signed integer
BIGINT
(492 or 493)
sqlint64 64-bit signed integer
REAL
(480 or 481)
float Single-precision floating point
DOUBLE
(480 or 481)
double Double-precision floating point
DECIMAL(p,s)
(484 or 485)
Not supported
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)
(452 or 453)
char[n+1] where n is large enough
to hold the data
1<=n<=254
Fixed-length, null-terminated character string
CHAR(n) FOR BIT DATA
(452 or 453)
char[n+1] where n is large enough
to hold the data
1<=n<=254
Fixed-length character string
VARCHAR(n)
(448 or 449) (460 or 461)
char[n+1] where n is large enough
to hold the data
1<=n<=32 672
Null-terminated varying length string
44 Developing Embedded SQL Applications](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-50-320.jpg)
![Table 6. SQL Data Types Mapped to C and C++ Declarations (continued)
SQL Column Type1
C and C++ Data Type SQL Column Type Description
VARCHAR(n) FOR BIT DATA
(448 or 449)
struct {
sqluint16 length;
char[n]
}
1<=n<=32 672
Not null-terminated varying length character
string
LONG VARCHAR2
(456 or 457)
struct {
sqluint16 length;
char[n]
}
32 673<=n<=32 700
Not null-terminated varying length character
string
CLOB(n)
(408 or 409)
struct {
sqluint32 length;
char data[n];
}
1<=n<=2 147 483 647
Not null-terminated varying length character
string with 4-byte string length indicator
BLOB(n)
(404 or 405)
struct {
sqluint32 length;
char data[n];
}
1<=n<=2 147 483 647
Not null-terminated varying binary string
with 4-byte string length indicator
DATE
(384 or 385)
char[11] Null-terminated character form
TIME
(388 or 389)
char[9] Null-terminated character form
TIMESTAMP(p)
(392 or 393)
char[p+21] where p is large
enough to hold the data
0<=p<=12
Null-terminated character form
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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-51-320.jpg)
![Table 7. SQL Data Types Mapped to C and C++ Declarations
SQL Column Type1
C and C++ Data Type SQL Column Type Description
GRAPHIC(n)
(468 or 469)
sqldbchar[n+1] where n is large
enough to hold the data
1<=n<=127
Fixed-length, null-terminated double-byte
character string
VARGRAPHIC(n)
(400 or 401)
sqldbchar[n+1] where n is large
enough to hold the data
1<=n<=16 336
Not null-terminated, variable-length
double-byte character string
LONG VARGRAPHIC2
(472 or 473)
struct {
sqluint16 length;
sqldbchar[n]
}
16 337<=n<=16 350
Not null-terminated, variable-length
double-byte character string
DBCLOB(n)
(412 or 413)
struct {
sqluint32 length;
sqldbchar data[n];
}
1<=n<=1 073 741 823
Not null-terminated varying length character
string with 4-byte string length indicator
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
SMALLINT
(500 or 501)
01 name PIC S9(4) COMP-5. 16-bit signed integer
46 Developing Embedded SQL Applications](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-52-320.jpg)
![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 EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 age PIC S9(4) COMP-5 VALUE 26.
01 DEPT PIC S9(9) COMP-5 VALUE 38.
01 salary PIC S9(6)V9(3) COMP-3.
01 CH PIC X(1).
01 name1 PIC X(8).
01 NAME2 PIC X(8).
01 nul-ind PIC S9(4) COMP-5.
EXEC SQL END DECLARE SECTION END-EXEC.
FORTRAN 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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-61-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-62-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-66-320.jpg)
![...
}
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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-71-320.jpg)
![The following example is a sample SQL declare section with host variables
declared for supported SQL data types:
EXEC SQL BEGIN DECLARE SECTION;
.
.
.
short age = 26; /* SQL type 500 */
short year; /* SQL type 500 */
sqlint32 salary; /* SQL type 496 */
sqlint32 deptno; /* SQL type 496 */
float bonus; /* SQL type 480 */
double wage; /* SQL type 480 */
char mi; /* SQL type 452 */
char name[6]; /* SQL type 460 */
struct {
short len;
char data[24];
} address; /* SQL type 448 */
struct {
short len;
char data[32695];
} voice; /* SQL type 456 */
sql type is clob(1m)
chapter; /* SQL type 408 */
sql type is clob_locator
chapter_locator; /* SQL type 964 */
sql type is clob_file
chapter_file_ref; /* SQL type 920 */
sql type is blob(1m)
video; /* SQL type 404 */
sql type is blob_locator
video_locator; /* SQL type 960 */
sql type is blob_file
video_file_ref; /* SQL type 916 */
sql type is dbclob(1m)
tokyo_phone_dir; /* SQL type 412 */
sql type is dbclob_locator
tokyo_phone_dir_lctr; /* SQL type 968 */
sql type is dbclob_file
tokyo_phone_dir_flref; /* SQL type 924 */
sql type is varbinary(12)
myVarBinField; /* SQL type 908 */
sql type is binary(4)
myBinField; /* SQL type 912 */
struct {
short len;
sqldbchar data[100];
} vargraphic1; /* SQL type 464 */
/* Precompiled with
WCHARTYPE NOCONVERT option */
struct {
short len;
wchar_t data[100];
} vargraphic2; /* SQL type 464 */
/* Precompiled with
WCHARTYPE CONVERT option */
struct {
short len;
sqldbchar data[10000];
} long_vargraphic1; /* SQL type 472 */
/* Precompiled with
WCHARTYPE NOCONVERT option */
struct {
short len;
wchar_t data[10000];
66 Developing Embedded SQL Applications](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-72-320.jpg)
![} long_vargraphic2; /* SQL type 472 */
/* Precompiled with
WCHARTYPE CONVERT option */
sqldbchar graphic1[100]; /* SQL type 468 */
/* Precompiled with
WCHARTYPE NOCONVERT option */
wchar_t graphic2[100]; /* SQL type 468 */
/* Precompiled with
WCHARTYPE CONVERT option */
char date[11]; /* SQL type 384 */
char time[9]; /* SQL type 388 */
char timestamp[27]; /* SQL type 392 */
short wage_ind; /* 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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-73-320.jpg)
![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; /* bulk fetch */
... /* 100 or less rows */
...
}
end_fetch:
EXEC SQL CLOSE empcr;
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 TABLE tn1 (c1 NUMBER, c2 VARCHAR2(10));
INSERT INTO TN1 VALUES (1, ’TEMP DATA1’);
INSERT INTO TN1 VALUES (2, NULL);
INSERT 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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-74-320.jpg)
![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 : %dn", 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 = %dn", 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 %sn", c1[i], MyStructVar[i].c2);
}
}
else{
...
}
printf ( " Total # of rows fetched : %dn", sqlca.sqlerrd[2];
Chapter 3. Programming 69](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-75-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-76-320.jpg)
![{
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++.
auto
extern
static
register
const
volatile
(1)
float
(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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-77-320.jpg)
![CHAR
(1)
varname
*
& const
volatile
C String
(2)
varname [ length ]
( varname )
*
& const
volatile
Notes:
1 CHAR (SQLTYPE 452), length 1
2 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
auto
extern
static
register
const
volatile
struct
tag
(1)
{ short var1 ; char var2 [ length ] ; }
int unsigned
,
varname
Values
*
& const
volatile
;
Values
= { value-1 , value-2 }
Chapter 3. Programming 73](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-79-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-80-320.jpg)
![auto
extern
static
register
const
volatile
struct
tag
(1) (2)
{ short var-1 ; sqldbchar var-2 [ length ] ; }
int wchar_t
,
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++.
2 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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-84-320.jpg)
![auto
extern
static
register
const
volatile
(1)
sqldbchar
wchar_t
,
CHAR
C string = value
;
CHAR
(2)
varname
*
& const
volatile
C string
(3)
varname [ length ]
( varname )
*
& 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++.
2 GRAPHIC (SQLTYPE 468), length 1
3 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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-85-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-87-320.jpg)
![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:
auto
extern
static
register
const
volatile
SQL TYPE IS BLOB_LOCATOR
CLOB_LOCATOR
DBCLOB_LOCATOR
,
Variable
;
Variable
* variable-name
& const = init-value
volatile
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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-88-320.jpg)
![The syntax for declaring file reference host variables in C or C++ is:
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];
Syntax for file reference host variables in C or C++
auto
extern
static
register
const
volatile
SQL TYPE IS
XML AS
BLOB_FILE
CLOB_FILE
DBCLOB_FILE
,
Variable
;
Variable
* variable-name
& const = init-value
volatile
Figure 1. Syntax Diagram
Chapter 3. Programming 83](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-89-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-90-320.jpg)
![SQL TYPE IS BINARY length
VARBINARY
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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-92-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-93-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-95-320.jpg)
![{
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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-96-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-97-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-98-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-123-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-124-320.jpg)
![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 Example Source Code
C and C++ #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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-132-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-138-320.jpg)
![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 = %sn", appMsg);
strcat( sqlInfo, sqlInfoToken);
sprintf( sqlInfoToken, " line = %dn", line);
strcat( sqlInfo, sqlInfoToken);
sprintf( sqlInfoToken, " file = %sn", file);
strcat( sqlInfo, sqlInfoToken);
sprintf( sqlInfoToken, " SQLCODE = %ldn",
140 Developing Embedded SQL Applications](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-146-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-211-320.jpg)
![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; /* bulk fetch */
... /* 100 or less rows */
...
}
end_fetch:
EXEC SQL CLOSE empcr;
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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-212-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-213-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-214-320.jpg)
![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](https://image.slidesharecdn.com/ibmdb210-161212075637/85/Ibm-db2-10-5-for-linux-unix-and-windows-developing-embedded-sql-applications-215-320.jpg)
More Related Content
Viewers also liked (14)
Similar to Ibm db2 10.5 for linux, unix, and windows developing embedded sql applications (20)
More from bupbechanhgmail (17)
Recently uploaded (20)
Ibm db2 10.5 for linux, unix, and windows developing embedded sql applications
- 1. IBM DB2 10.5 for Linux, UNIX, and Windows Developing Embedded SQL Applications SC27-4550-00
- 3. IBM DB2 10.5 for Linux, UNIX, and Windows Developing Embedded SQL Applications SC27-4550-00
- 4. 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.
- 5. Contents Chapter 1. Introduction to embedded SQL . . . . . . . . . . . . . . . . 1 Embedding SQL statements in a host language . . . 2 Embedded SQL statements in C and C++ applications. . . . . . . . . . . . . . 2 Embedded SQL statements in FORTRAN applications. . . . . . . . . . . . . . 4 Embedded SQL statements in COBOL applications 5 Embedded SQL statements in REXX applications 6 Supported development software for embedded SQL applications. . . . . . . . . . . . . . . 8 Setting up the embedded SQL development environment . . . . . . . . . . . . . . 8 Chapter 2. Designing embedded SQL applications . . . . . . . . . . . . 11 Authorization Considerations for Embedded SQL . 11 Static and dynamic SQL statement execution in embedded SQL applications . . . . . . . . . 12 Embedded SQL dynamic statements . . . . . 12 Determining when to execute SQL statements statically or dynamically in embedded SQL applications . . . . . . . . . . . . . 13 Performance of embedded SQL applications . . . 15 32-bit and 64-bit support for embedded SQL applications . . . . . . . . . . . . . . 16 Restrictions on embedded SQL applications . . . 17 Restrictions on character sets using C and C++ to program embedded SQL applications. . . . . 17 Restrictions on using COBOL to program embedded SQL applications . . . . . . . . 18 Restrictions on using FORTRAN to program embedded SQL applications . . . . . . . . 18 Restrictions on using REXX to program embedded SQL applications . . . . . . . . 18 Recommendations for developing embedded SQL applications with XML and XQuery . . . . . 19 Concurrent transactions and multi-threaded database access in embedded SQL applications . . 19 Recommendations for using multiple threads . . 22 Code page and country or region code considerations for multi-threaded UNIX applications . . . . . . . . . . . . . 22 Troubleshooting multi-threaded embedded SQL applications . . . . . . . . . . . . . 23 Chapter 3. Programming embedded SQL applications . . . . . . . . . . 25 Embedded SQL source files . . . . . . . . . 25 Embedded SQL application template in C . . . . 26 Include files and definitions required for embedded SQL applications . . . . . . . . . . . . 29 Include files for C and C++ embedded SQL applications . . . . . . . . . . . . . 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 © Copyright IBM Corp. 1993, 2013 iii
- 6. 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 . . . . . . . . 146 Precompilation of embedded SQL applications that access more than one database server. . . 148 Embedded SQL application packages and access plans . . . . . . . . . . . . . . . 149 Package schema qualification using CURRENT PACKAGE PATH special register . . . . . . 149 Precompiler generated timestamps . . . . . 152 Errors and warnings from precompilation of embedded SQL applications . . . . . . . 153 Compiling and linking source files containing embedded SQL. . . . . . . . . . . . . 153 Binding embedded SQL packages to a database 154 Effect of DYNAMICRULES bind option on dynamic SQL . . . . . . . . . . . . 154 Using special registers to control the statement compilation environment . . . . . . . . 157 Package recreation using the BIND command and an existing bind file. . . . . . . . . 157 Rebinding existing packages with the REBIND command . . . . . . . . . . . . . 157 Bind considerations . . . . . . . . . . 158 Blocking considerations . . . . . . . . . 159 Advantages of deferred binding . . . . . . 159 Performance improvements when using REOPT option of the BIND command . . . . . . . 160 Binding applications and utilities (DB2 Connect server). . . . . . . . . . . . . . . . 160 Package storage and maintenance . . . . . . 163 Package versioning . . . . . . . . . . 163 Resolution of unqualified table names . . . . 164 Building embedded SQL applications using the sample build script . . . . . . . . . . . 165 Error-checking utilities . . . . . . . . . 167 Building applications and routines written in C and C++ . . . . . . . . . . . . . . 168 Building applications and routines written in COBOL . . . . . . . . . . . . . . 182 Building and running embedded SQL applications written in REXX . . . . . . . 196 Building embedded SQL applications from the command line . . . . . . . . . . . . . 198 Building embedded SQL applications written in C or C++ (Windows) . . . . . . . . . . 198 Chapter 5. Deploying and running embedded SQL applications . . . . . 201 Use of the db2dsdriver.cfg configuration file by embedded SQL applications . . . . . . . . 201 Restrictions on linking to libdb2.so . . . . . . 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 Appendix B. Notices . . . . . . . . 217 Index . . . . . . . . . . . . . . . 221 iv Developing Embedded SQL Applications
- 7. 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%SQLLIBsamples 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 1
- 8. 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: 2 Developing Embedded SQL Applications
- 9. 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 3
- 10. 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. 4 Developing Embedded SQL Applications
- 11. 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 5
- 12. – Comments are not allowed between EXEC and SQL. – Comments are not allowed in dynamically executed statements. v SQL statements follow the same line continuation rules as the COBOL language. However, do not split the EXEC SQL statement initializer between lines. v 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. v 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. v SQL arithmetic operators must be delimited by blanks. 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 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’ 6 Developing Embedded SQL Applications
- 13. 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 7
- 14. 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 8 Developing Embedded SQL Applications
- 15. 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 9
- 16. 10 Developing Embedded SQL Applications
- 17. 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
- 18. 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 WHERE dept = ?"); EXEC SQL PREPARE StmtDyn FROM :hostVarStmtDyn; EXEC SQL EXECUTE StmtDyn USING :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
- 19. 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
- 20. 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
- 21. 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
- 22. 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 Linux on x64 v Linux on POWER® v Linux on System z® v Windows on x64 (when using the Windows for x64 install image) 16 Developing Embedded SQL Applications
- 23. 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
- 24. 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
- 25. 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
- 26. 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
- 27. v sqleBeginCtx - Create and attach to an application context v sqleDetachFromCtx - Detach from context v sqleEndCtx - Detach and destory application context v sqleGetCurrentCtx - Get current context v 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 sqlabndx - Bind v sqlaprep - Precompile Program v sqluexpr - Export v 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
- 28. 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
- 29. 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
- 30. 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
- 31. 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
- 32. 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
- 33. #include <stdio.h> 1 #include <stdlib.h> #include <string.h> #include <sqlenv.h> #include <sqlutil.h> EXEC SQL BEGIN DECLARE SECTION; 2 short id; char name[10]; short dept; double salary; char hostVarStmtDyn[50]; EXEC SQL END DECLARE SECTION; int main() { int rc = 0; 3 EXEC SQL INCLUDE SQLCA; 4 /* connect to the database */ printf("n Connecting to database..."); EXEC SQL CONNECT TO "sample"; 5 if (SQLCODE <0) 6 { printf("nConnect Error: SQLCODE = goto connect_reset; } else { printf("n Connected to database.n"); } /* 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 310n"); printf("n ID Name DEPT Salaryn"); 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) 6 { printf("Prepare Error: SQLCODE = } else { EXEC SQL EXECUTE StmtDyn USING :dept; 8 } if (SQLCODE <0) 6 { printf("Execute Error: SQLCODE = Chapter 3. Programming 27
- 34. } /* 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) 6 { printf("Declare Error: SQLCODE = } EXEC SQL OPEN posCur1; EXEC SQL FETCH posCur1 INTO :id, :name, :dept, :salary ; 9 if (SQLCODE <0) 6 { printf("Fetch Error: SQLCODE = } else { printf(" Executing an dynamic SQL statement, updating the n salary value for the id equal to 310n"); printf("n ID Name DEPT Salaryn"); printf(" } EXEC SQL CLOSE posCur1; /* Commit the transaction */ printf("n Commit the transaction.n"); EXEC SQL COMMIT; 10 if (SQLCODE <0) 6 { printf("Error: SQLCODE = } /* Disconnect from the database */ connect_reset : EXEC SQL CONNECT RESET; 11 if (SQLCODE <0) 6 { printf("Connection Error: SQLCODE = } return 0; } /* end main */ Notes to Sample program: template.sqc: Note Description 1 Include files: This directive includes a file into your source application. 2 Declaration section: Declaration of host variables that will be used to hold values referenced in the SQL statements of the C application. 3 Local variable declaration: This block declares the local variables to be used in the application. These are not host variables. 4 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. 5 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. 6 Error handling: Checks to see if an error occurred. 7 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. 28 Developing Embedded SQL Applications
- 35. Note Description 8 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. 9 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. 10 Commit the transaction: The COMMIT statement finalizes the database changes that were made within a unit of work. 11 And finally, the database connection must be dropped. 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
- 36. 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
- 37. 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
- 38. 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
- 39. 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
- 40. 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 ’paypayroll.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
- 41. 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
- 42. 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
- 43. 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
- 44. 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
- 45. 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 SQL Column Type Description SMALLINT (500 or 501) short short int sqlint16 16-bit signed integer INTEGER (496 or 497) int long long int sqlint322 32-bit signed integer BIGINT (492 or 493) long long long __int64 sqlint643 64-bit signed integer REAL5 (480 or 481) float Single-precision floating point DOUBLE6 (480 or 481) double Double-precision floating point DECIMAL(p,s) (484 or 485) No exact equivalent; use double Packed decimal (Consider using the CHAR and DECIMAL functions to manipulate packed decimal fields as character data.) CHAR(1) (452 or 453) char Single character CHAR(n) (452 or 453) No exact equivalent; use char[n+1] where n is large enough to hold the data 1<=n<=254 Fixed-length character string Chapter 3. Programming 39
- 46. 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] } 1<=n<=32 672 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: struct tag { short int; char[n] } Alternatively, use char[n+1] where n is large enough to hold the data 1<=n<=32 672 Null-terminated variable-length character string Note: Assigned an SQL type of 460/461. LONG VARCHAR8 (456 or 457) struct tag { short int; char[n] } 32 673<=n<=32 700 Non null-terminated varying character string with 2-byte string length indicator CLOB(n) (408 or 409) sql type is clob(n) 1<=n<=2 147 483 647 Non null-terminated varying character string with 4-byte string length indicator CLOB locator variable7 (964 or 965) sql type is clob_locator Identifies CLOB entities residing on the server CLOB file reference variable7 (920 or 921) sql type is clob_file Descriptor for file containing CLOB data BLOB(n) (404 or 405) sql type is blob(n) 1<=n<=2 147 483 647 Non null-terminated varying binary string with 4-byte string length indicator BLOB locator variable7 (960 or 961) sql type is blob_locator Identifies BLOB entities on the server BLOB file reference variable7 (916 or 917) sql type is blob_file Descriptor for the file containing BLOB data DATE (384 or 385) Null-terminated character form Allow at least 11 characters to accommodate the null-terminator VARCHAR structured form Allow at least 10 characters TIME (388 or 389) Null-terminated character form Allow at least 9 characters to accommodate the null-terminator VARCHAR structured form Allow at least 8 characters 40 Developing Embedded SQL Applications
- 47. Table 2. SQL Data Types Mapped to C and C++ Declarations (continued) SQL Column Type1 C and C++ Data Type SQL Column Type Description TIMESTAMP(p) 4 (392 or 393) Null-terminated character form Allow 20- 33 characters to accommodate for the null-terminator VARCHAR structured form Allow 19-32 characters. XML8 (988 or 989) struct { sqluint32 length; char data[n]; } 1<=n<=2 147 483 647 SQLUDF_CLOB XML value BINARY unsigned char myBinField[4]; 1<= n <=255 Binary data VARBINARY struct myVarBinField_t {sqluint16 length;char data[12];} myVarBinField; 1<= n <=32704 Varbinary data 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 GRAPHIC(1) (468 or 469) sqldbchar Single double-byte character GRAPHIC(n) (468 or 469) No exact equivalent; use sqldbchar[n+1] where n is large enough to hold the data 1<=n<=127 Fixed-length double-byte character string VARGRAPHIC(n) (464 or 465) struct tag { short int; sqldbchar[n] } 1<=n<=16 336 Non null-terminated varying double-byte character string with 2-byte string length indicator Alternatively use sqldbchar[n+1] where n is large enough to hold the data 1<=n<=16 336 Null-terminated variable-length double-byte character string Note: Assigned an SQL type of 400/401. Chapter 3. Programming 41
- 48. Table 3. SQL Data Types Mapped to C and C++ Declarations (continued) SQL Column Type1 C and C++ Data Type SQL Column Type Description LONG VARGRAPHIC8 (472 or 473) struct tag { short int; sqldbchar[n] } 16 337<=n<=16 350 Non null-terminated varying double-byte character string with 2-byte string length indicator 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 GRAPHIC(1) (468 or 469) wchar_t v Single wide character (for C-type) v Single double-byte character (for column type) GRAPHIC(n) (468 or 469) No exact equivalent; use wchar_t [n+1] where n is large enough to hold the data 1<=n<=127 Fixed-length double-byte character string VARGRAPHIC(n) (464 or 465) struct tag { short int; wchar_t [n] } 1<=n<=16 336 Non null-terminated varying double-byte character string with 2-byte string length indicator Alternately use char[n+1] where n is large enough to hold the data 1<=n<=16 336 Null-terminated variable-length double-byte character string Note: Assigned an SQL type of 400/401. LONG VARGRAPHIC8 (472 or 473) struct tag { short int; wchar_t [n] } 16 337<=n<=16 350 Non null-terminated varying double-byte character string with 2-byte string length indicator 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) 1<=n<=1 073 741 823 Non null-terminated varying double-byte character string with 4-byte string length indicator 42 Developing Embedded SQL Applications
- 49. Table 5. SQL Data Types Mapped to C and C++ Declarations (continued) SQL Column Type1 C and C++ Data Type SQL Column Type Description DBCLOB locator variable7 (968 or 969) sql type is dbclob_locator Identifies DBCLOB entities residing on the server DBCLOB file reference variable7 (924 or 925) sql type is dbclob_file 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
- 50. – 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 SMALLINT (500 or 501) short 16-bit signed integer INTEGER (496 or 497) sqlint32 32-bit signed integer BIGINT (492 or 493) sqlint64 64-bit signed integer REAL (480 or 481) float Single-precision floating point DOUBLE (480 or 481) double Double-precision floating point DECIMAL(p,s) (484 or 485) Not supported 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) (452 or 453) char[n+1] where n is large enough to hold the data 1<=n<=254 Fixed-length, null-terminated character string CHAR(n) FOR BIT DATA (452 or 453) char[n+1] where n is large enough to hold the data 1<=n<=254 Fixed-length character string VARCHAR(n) (448 or 449) (460 or 461) char[n+1] where n is large enough to hold the data 1<=n<=32 672 Null-terminated varying length string 44 Developing Embedded SQL Applications
- 51. Table 6. SQL Data Types Mapped to C and C++ Declarations (continued) SQL Column Type1 C and C++ Data Type SQL Column Type Description VARCHAR(n) FOR BIT DATA (448 or 449) struct { sqluint16 length; char[n] } 1<=n<=32 672 Not null-terminated varying length character string LONG VARCHAR2 (456 or 457) struct { sqluint16 length; char[n] } 32 673<=n<=32 700 Not null-terminated varying length character string CLOB(n) (408 or 409) struct { sqluint32 length; char data[n]; } 1<=n<=2 147 483 647 Not null-terminated varying length character string with 4-byte string length indicator BLOB(n) (404 or 405) struct { sqluint32 length; char data[n]; } 1<=n<=2 147 483 647 Not null-terminated varying binary string with 4-byte string length indicator DATE (384 or 385) char[11] Null-terminated character form TIME (388 or 389) char[9] Null-terminated character form TIMESTAMP(p) (392 or 393) char[p+21] where p is large enough to hold the data 0<=p<=12 Null-terminated character form 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
- 52. Table 7. SQL Data Types Mapped to C and C++ Declarations SQL Column Type1 C and C++ Data Type SQL Column Type Description GRAPHIC(n) (468 or 469) sqldbchar[n+1] where n is large enough to hold the data 1<=n<=127 Fixed-length, null-terminated double-byte character string VARGRAPHIC(n) (400 or 401) sqldbchar[n+1] where n is large enough to hold the data 1<=n<=16 336 Not null-terminated, variable-length double-byte character string LONG VARGRAPHIC2 (472 or 473) struct { sqluint16 length; sqldbchar[n] } 16 337<=n<=16 350 Not null-terminated, variable-length double-byte character string DBCLOB(n) (412 or 413) struct { sqluint32 length; sqldbchar data[n]; } 1<=n<=1 073 741 823 Not null-terminated varying length character string with 4-byte string length indicator 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 SMALLINT (500 or 501) 01 name PIC S9(4) COMP-5. 16-bit signed integer 46 Developing Embedded SQL Applications
- 53. Table 8. SQL Data Types Mapped to COBOL Declarations (continued) SQL Column Type1 COBOL Data Type SQL Column Type Description INTEGER (496 or 497) 01 name PIC S9(9) COMP-5. 32-bit signed integer BIGINT (492 or 493) 01 name PIC S9(18) COMP-5. 64-bit signed integer DECIMAL(p,s) (484 or 485) 01 name PIC S9(m)V9(n) COMP-3. Packed decimal REAL2 (480 or 481) 01 name USAGE IS COMP-1. Single-precision floating point DOUBLE3 (480 or 481) 01 name USAGE IS COMP-2. Double-precision floating point CHAR(n) (452 or 453) 01 name PIC X(n). Fixed-length character string VARCHAR(n) (448 or 449) 01 name. 49 length PIC S9(4) COMP-5. 49 name PIC X(n). 1<=n<=32 672 Variable-length character string LONG VARCHAR6 (456 or 457) 01 name. 49 length PIC S9(4) COMP-5. 49 data PIC X(n). 32 673<=n<=32 700 Long variable-length character string CLOB(n) (408 or 409) 01 MY-CLOB USAGE IS SQL TYPE IS CLOB(n). 1<=n<=2 147 483 647 Large object variable-length character string CLOB locator variable4 (964 or 965) 01 MY-CLOB-LOCATOR USAGE IS SQL TYPE IS CLOB-LOCATOR. Identifies CLOB entities residing on the server CLOB file reference variable4 (920 or 921) 01 MY-CLOB-FILE USAGE IS SQL TYPE IS CLOB-FILE. Descriptor for file containing CLOB data BLOB(n) (404 or 405) 01 MY-BLOB USAGE IS SQL TYPE IS BLOB(n). 1<=n<=2 147 483 647 Large object variable-length binary string 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
- 54. Table 8. SQL Data Types Mapped to COBOL Declarations (continued) SQL Column Type1 COBOL Data Type SQL Column Type Description BLOB file reference variable4 (916 or 917) 01 MY-BLOB-FILE USAGE IS SQL TYPE IS BLOB-FILE. Descriptor for file containing BLOB data DATE (384 or 385) 01 identifier PIC X(10). 10-byte character string TIME (388 or 389) 01 identifier PIC X(8). 8-byte character string TIMESTAMP(p) (392 or 393) 01 identifier PIC X(p+20). 0<=p<=12 19 to 32 byte character string A 19 byte character string can be used, when p is 0. XML5 (988 or 989) 01 name USAGE IS SQL TYPE IS XML AS CLOB (size). 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 SQL Column Type Description GRAPHIC(n) (468 or 469) 01 name PIC G(n) DISPLAY-1. Fixed-length double-byte character string VARGRAPHIC(n) (464 or 465) 01 name. 49 length PIC S9(4) COMP-5. 49 name PIC G(n) DISPLAY-1. 1<=n<=16 336 Variable length double-byte character string with 2-byte string length indicator LONG VARGRAPHIC6 (472 or 473) 01 name. 49 length PIC S9(4) COMP-5. 49 name PIC G(n) DISPLAY-1. 16 337<=n<=16 350 Variable length double-byte character string with 2-byte string length indicator DBCLOB(n) (412 or 413) 01 MY-DBCLOB USAGE IS SQL TYPE IS DBCLOB(n). 1<=n<=1 073 741 823 Large object variable-length double-byte character string with 4-byte string length indicator DBCLOB locator variable4 (968 or 969) 01 MY-DBCLOB-LOCATOR USAGE IS SQL TYPE IS DBCLOB-LOCATOR. Identifies DBCLOB entities residing on the server DBCLOB file reference variable4 (924 or 925) 01 MY-DBCLOB-FILE USAGE IS SQL TYPE IS DBCLOB-FILE. Descriptor for file containing DBCLOB data 48 Developing Embedded SQL Applications
- 55. Table 9. SQL Data Types Mapped to COBOL Declarations (continued) SQL Column Type1 COBOL Data Type SQL Column Type Description 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 identifier PIC S9(3)V COMP-3 01 identifier PIC SV9(3) COMP-3 01 identifier PIC S9V COMP-3 01 identifier PIC 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
- 56. Table 10. SQL Data Types Mapped to FORTRAN Declarations SQL Column Type1 FORTRAN Data Type SQL Column Type Description SMALLINT (500 or 501) INTEGER*2 16-bit, signed integer INTEGER (496 or 497) INTEGER*4 32-bit, signed integer REAL2 (480 or 481) REAL*4 Single precision floating point DOUBLE3 (480 or 481) REAL*8 Double precision floating point DECIMAL(p,s) (484 or 485) No exact equivalent; use REAL*8 Packed decimal CHAR(n) (452 or 453) CHARACTER*n Fixed-length character string of length n where n is from 1 to 254 VARCHAR(n) (448 or 449) SQL TYPE IS VARCHAR(n) where n is from 1 to 32 672 Variable-length character string LONG VARCHAR5 (456 or 457) SQL TYPE IS VARCHAR(n) where n is from 32 673 to 32 700 Long variable-length character string CLOB(n) (408 or 409) SQL TYPE IS CLOB (n) where n is from 1 to 2 147 483 647 Large object variable-length character string CLOB locator variable4 (964 or 965) SQL TYPE IS CLOB_LOCATOR Identifies CLOB entities residing on the server CLOB file reference variable4 (920 or 921) SQL TYPE IS CLOB_FILE Descriptor for file containing CLOB data BLOB(n) (404 or 405) SQL TYPE IS BLOB(n) where n is from 1 to 2 147 483 647 Large object variable-length binary string BLOB locator variable4 (960 or 961) SQL TYPE IS BLOB_LOCATOR Identifies BLOB entities on the server BLOB file reference variable4 (916 or 917) SQL TYPE IS BLOB_FILE Descriptor for the file containing BLOB data DATE (384 or 385) CHARACTER*10 10-byte character string TIME (388 or 389) CHARACTER*8 8-byte character string 50 Developing Embedded SQL Applications
- 57. Table 10. SQL Data Types Mapped to FORTRAN Declarations (continued) SQL Column Type1 FORTRAN Data Type SQL Column Type Description TIMESTAMP(p) (392 or 393) CHARACTER*19 to CHARACTER*32 19 to 32 byte character string XML (988 or 989) 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 REXX Data Type SQL Column Type Description SMALLINT (500 or 501) A number without a decimal point ranging from -32 768 to 32 767 16-bit signed integer INTEGER (496 or 497) A number without a decimal point ranging from -2 147 483 648 to 2 147 483 647 32-bit signed integer REAL2 (480 or 481) A number in scientific notation ranging from -3.40282346 x 1038 to 3.40282346 x 1038 Single-precision floating point DOUBLE3 (480 or 481) A number in scientific notation ranging from -1.79769313 x 10308 to 1.79769313 x 10308 Double-precision floating point Chapter 3. Programming 51
- 58. Table 11. SQL Column Types Mapped to REXX Declarations (continued) SQL Column Type1 REXX Data Type SQL Column Type Description DECIMAL(p,s) (484 or 485) A number with a decimal point Packed decimal CHAR(n) (452 or 453) A string with a leading and trailing quotation mark ('), which has length n after removing the two quotation marks A string of length n with any non-numeric characters, other than leading and trailing blanks or the E in scientific notation Fixed-length character string of length n where n is from 1 to 254 VARCHAR(n) (448 or 449) Equivalent to CHAR(n) Variable-length character string of length n, where n ranges from 1 to 4000 LONG VARCHAR5 (456 or 457) Equivalent to CHAR(n) Variable-length character string of length n, where n ranges from 1 to 32 700 CLOB(n) (408 or 409) Equivalent to CHAR(n) Large object variable-length character string of length n, where n ranges from 1 to 2 147 483 647 CLOB locator variable4 (964 or 965) DECLARE :var_name LANGUAGE TYPE CLOB LOCATOR Identifies CLOB entities residing on the server CLOB file reference variable4 (920 or 921) DECLARE :var_name LANGUAGE TYPE CLOB FILE Descriptor for file containing CLOB data BLOB(n) (404 or 405) A string with a leading and trailing apostrophe, preceded by BIN, containing n characters after removing the preceding BIN and the two apostrophes. Large object variable-length binary string of length n, where n ranges from 1 to 2 147 483 647 BLOB locator variable4 (960 or 961) DECLARE :var_name LANGUAGE TYPE BLOB LOCATOR Identifies BLOB entities on the server BLOB file reference variable4 (916 or 917) DECLARE :var_name LANGUAGE TYPE BLOB FILE Descriptor for the file containing BLOB data DATE (384 or 385) Equivalent to CHAR(10) 10-byte character string TIME (388 or 389) Equivalent to CHAR(8) 8-byte character string TIMESTAMP (392 or 393) Equivalent to CHAR(26) 26-byte character string XML (988 or 989) 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. 52 Developing Embedded SQL Applications
- 59. 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 SQL Column Type Description GRAPHIC(n) (468 or 469) A string with a leading and trailing apostrophe preceded by a G or N, containing n DBCS characters after removing the preceding character and the two apostrophes Fixed-length graphic string of length n, where n is from 1 to 127 VARGRAPHIC(n) (464 or 465) Equivalent to GRAPHIC(n) Variable-length graphic string of length n, where n ranges from 1 to 2000 LONG VARGRAPHIC5 (472 or 473) Equivalent to GRAPHIC(n) Long variable-length graphic string of length n, where n ranges from 1 to 16 350 DBCLOB(n) (412 or 413) Equivalent to GRAPHIC(n) Large object variable-length graphic string of length n, where n ranges from 1 to 1 073 741 823 DBCLOB locator variable4 (968 or 969) DECLARE :var_name LANGUAGE TYPE DBCLOB LOCATOR Identifies DBCLOB entities residing on the server DBCLOB file reference variable4 (924 or 925) DECLARE :var_name LANGUAGE TYPE DBCLOB FILE Descriptor for file containing DBCLOB data 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
- 60. 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
- 61. 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 EXEC SQL BEGIN DECLARE SECTION END-EXEC. 01 age PIC S9(4) COMP-5 VALUE 26. 01 DEPT PIC S9(9) COMP-5 VALUE 38. 01 salary PIC S9(6)V9(3) COMP-3. 01 CH PIC X(1). 01 name1 PIC X(8). 01 NAME2 PIC X(8). 01 nul-ind PIC S9(4) COMP-5. EXEC SQL END DECLARE SECTION END-EXEC. FORTRAN 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
- 62. 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
- 63. 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
- 64. 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
- 65. 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 X’0000’ v The third and fourth bytes of sqlname.data must be X’0000’ v The fifth byte of sqlname.data must be X’01’ (referred to as the XML subtype indicator only when the first two conditions are met) v The remaining bytes must be X’000000’ 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
- 66. 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
- 67. 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 NULLn" ); 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
- 68. 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 = %fn", 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
- 69. // 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
- 70. 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
- 71. ... } 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
- 72. The following example is a sample SQL declare section with host variables declared for supported SQL data types: EXEC SQL BEGIN DECLARE SECTION; . . . short age = 26; /* SQL type 500 */ short year; /* SQL type 500 */ sqlint32 salary; /* SQL type 496 */ sqlint32 deptno; /* SQL type 496 */ float bonus; /* SQL type 480 */ double wage; /* SQL type 480 */ char mi; /* SQL type 452 */ char name[6]; /* SQL type 460 */ struct { short len; char data[24]; } address; /* SQL type 448 */ struct { short len; char data[32695]; } voice; /* SQL type 456 */ sql type is clob(1m) chapter; /* SQL type 408 */ sql type is clob_locator chapter_locator; /* SQL type 964 */ sql type is clob_file chapter_file_ref; /* SQL type 920 */ sql type is blob(1m) video; /* SQL type 404 */ sql type is blob_locator video_locator; /* SQL type 960 */ sql type is blob_file video_file_ref; /* SQL type 916 */ sql type is dbclob(1m) tokyo_phone_dir; /* SQL type 412 */ sql type is dbclob_locator tokyo_phone_dir_lctr; /* SQL type 968 */ sql type is dbclob_file tokyo_phone_dir_flref; /* SQL type 924 */ sql type is varbinary(12) myVarBinField; /* SQL type 908 */ sql type is binary(4) myBinField; /* SQL type 912 */ struct { short len; sqldbchar data[100]; } vargraphic1; /* SQL type 464 */ /* Precompiled with WCHARTYPE NOCONVERT option */ struct { short len; wchar_t data[100]; } vargraphic2; /* SQL type 464 */ /* Precompiled with WCHARTYPE CONVERT option */ struct { short len; sqldbchar data[10000]; } long_vargraphic1; /* SQL type 472 */ /* Precompiled with WCHARTYPE NOCONVERT option */ struct { short len; wchar_t data[10000]; 66 Developing Embedded SQL Applications
- 73. } long_vargraphic2; /* SQL type 472 */ /* Precompiled with WCHARTYPE CONVERT option */ sqldbchar graphic1[100]; /* SQL type 468 */ /* Precompiled with WCHARTYPE NOCONVERT option */ wchar_t graphic2[100]; /* SQL type 468 */ /* Precompiled with WCHARTYPE CONVERT option */ char date[11]; /* SQL type 384 */ char time[9]; /* SQL type 388 */ char timestamp[27]; /* SQL type 392 */ short wage_ind; /* 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
- 74. 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; /* bulk fetch */ ... /* 100 or less rows */ ... } end_fetch: EXEC SQL CLOSE empcr; 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 TABLE tn1 (c1 NUMBER, c2 VARCHAR2(10)); INSERT INTO TN1 VALUES (1, ’TEMP DATA1’); INSERT INTO TN1 VALUES (2, NULL); INSERT 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
- 75. 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 : %dn", 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 = %dn", 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 %sn", c1[i], MyStructVar[i].c2); } } else{ ... } printf ( " Total # of rows fetched : %dn", sqlca.sqlerrd[2]; Chapter 3. Programming 69
- 76. 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
- 77. { 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++. auto extern static register const volatile (1) float (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
- 78. BIGINT (SQLTYPE 492) sqlint64 __int64 long long int (5) long int Notes: 1 REAL (SQLTYPE 480), length 4 2 DOUBLE (SQLTYPE 480), length 8 3 SMALLINT (SQLTYPE 500) 4 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. 5 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 auto extern static register const volatile char unsigned , CHAR C String = value ; 72 Developing Embedded SQL Applications
- 79. CHAR (1) varname * & const volatile C String (2) varname [ length ] ( varname ) * & const volatile Notes: 1 CHAR (SQLTYPE 452), length 1 2 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 auto extern static register const volatile struct tag (1) { short var1 ; char var2 [ length ] ; } int unsigned , varname Values * & const volatile ; Values = { value-1 , value-2 } Chapter 3. Programming 73
- 80. 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
- 81. 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
- 82. 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
- 83. 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
- 84. auto extern static register const volatile struct tag (1) (2) { short var-1 ; sqldbchar var-2 [ length ] ; } int wchar_t , 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++. 2 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
- 85. auto extern static register const volatile (1) sqldbchar wchar_t , CHAR C string = value ; CHAR (2) varname * & const volatile C string (3) varname [ length ] ( varname ) * & 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++. 2 GRAPHIC (SQLTYPE 468), length 1 3 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
- 86. 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: auto extern static register const volatile SQL TYPE IS 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
- 87. 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
- 88. 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: auto extern static register const volatile SQL TYPE IS BLOB_LOCATOR CLOB_LOCATOR DBCLOB_LOCATOR , Variable ; Variable * variable-name & const = init-value volatile 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
- 89. The syntax for declaring file reference host variables in C or C++ is: 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]; Syntax for file reference host variables in C or C++ auto extern static register const volatile SQL TYPE IS XML AS BLOB_FILE CLOB_FILE DBCLOB_FILE , Variable ; Variable * variable-name & const = init-value volatile Figure 1. Syntax Diagram Chapter 3. Programming 83
- 90. 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
- 91. 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
- 92. SQL TYPE IS BINARY length VARBINARY 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
- 93. 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
- 94. 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
- 95. 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
- 96. { 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
- 97. 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
- 98. 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
- 99. 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
- 100. 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 SQL BEGIN DECLARE SECTION END-EXEC. * 01 age PIC S9(4) COMP-5. /* SQL type 500 */ 01 divis PIC S9(9) COMP-5. /* SQL type 496 */ 01 salary PIC S9(6)V9(3) COMP-3. /* SQL type 484 */ 01 bonus USAGE IS COMP-1. /* SQL type 480 */ 01 wage USAGE IS COMP-2. /* SQL type 480 */ 01 nm PIC X(5). /* SQL type 452 */ 01 varchar. 49 leng PIC S9(4) COMP-5. /* SQL type 448 */ 49 strg PIC X(14). /* SQL type 448 */ 01 longvchar. 49 len PIC S9(4) COMP-5. /* SQL type 456 */ 49 str PIC X(6027). /* SQL type 456 */ 01 MY-CLOB USAGE IS SQL TYPE IS CLOB(1M). /* SQL type 408 */ 01 MY-CLOB-LOCATOR USAGE IS SQL TYPE IS CLOB-LOCATOR. /* SQL type 964 */ 01 MY-CLOB-FILE USAGE IS SQL TYPE IS CLOB-FILE. /* SQL type 920 */ 01 MY-BLOB USAGE IS SQL TYPE IS BLOB(1M). /* SQL type 404 */ 01 MY-BLOB-LOCATOR USAGE IS SQL TYPE IS BLOB-LOCATOR. /* SQL type 960 */ 01 MY-BLOB-FILE USAGE IS SQL TYPE IS BLOB-FILE. /* SQL type 916 */ 01 MY-DBCLOB USAGE IS SQL TYPE IS DBCLOB(1M). /* SQL type 412 */ 01 MY-DBCLOB-LOCATOR USAGE IS SQL TYPE IS DBCLOB-LOCATOR. /* SQL type 968 */ 01 MY-DBCLOB-FILE USAGE IS SQL TYPE IS DBCLOB-FILE. /* SQL type 924 */ 01 MY-PICTURE PIC G(16000) USAGE IS DISPLAY-1. /* SQL type 464 */ 01 dt PIC X(10). /* SQL type 384 */ 01 tm PIC X(8). /* SQL type 388 */ 01 tmstmp PIC X(26). /* SQL type 392 */ 01 wage-ind PIC S9(4) COMP-5. /* SQL type 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
- 101. 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: 01 77 variable-name PICTURE PIC IS picture-string (1) COMP-3 IS COMPUTATIONAL-3 USAGE COMP-5 COMPUTATIONAL-5 . IS VALUE value Notes: 1 An alternative for COMP-3 is PACKED-DECIMAL. Floating point 01 77 variable-name IS USAGE (1) COMPUTATIONAL-1 COMP-1 (2) COMPUTATIONAL-2 COMP-2 Chapter 3. Programming 95
- 102. IS VALUE value . Notes: 1 REAL (SQLTYPE 480), Length 4 2 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 01 77 variable-name PICTURE PIC IS picture-string IS VALUE value . Variable length 01 variable-name . 49 identifier-1 PICTURE PIC IS S9(4) COMP-5 IS COMPUTATIONAL-5 USAGE IS VALUE value . 96 Developing Embedded SQL Applications
- 103. 49 identifier-2 PICTURE PIC IS 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
- 104. Fixed Length 01 77 variable-name PICTURE PIC IS picture-string USAGE IS DISPLAY-1 IS VALUE value . Variable Length 01 variable-name . 49 identifier-1 PICTURE PIC IS S9(4) COMP-5 IS COMPUTATIONAL-5 USAGE IS VALUE value . 49 identifier-2 PICTURE PIC IS picture-string 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
- 105. 01 variable-name USAGE IS SQL TYPE IS BLOB CLOB DBCLOB ( length ) . 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
- 106. The syntax for declaring large object (LOB) locator host variables in COBOL is: 01 variable-name USAGE IS SQL TYPE 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 USAGE IS SQL TYPE 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
- 107. 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
- 108. 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 pic s9(4) comp-5. 05 staff-name. 49 l pic s9(4) comp-5. 49 d pic x(9). 05 staff-info. 10 staff-dept pic s9(4) comp-5. 10 staff-job 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
- 109. 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
- 110. 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
- 111. 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/ /* SQL type 500 */ INTEGER*4 DEPT /* SQL type 496 */ REAL*4 BONUS /* SQL type 480 */ REAL*8 SALARY /* SQL type 480 */ CHARACTER MI /* SQL type 452 */ CHARACTER*112 ADDRESS /* SQL type 452 */ SQL TYPE IS VARCHAR (512) DESCRIPTION /* SQL type 448 */ SQL TYPE IS VARCHAR (32000) COMMENTS /* SQL type 448 */ SQL TYPE IS CLOB (1M) CHAPTER /* SQL type 408 */ SQL TYPE IS CLOB_LOCATOR CHAPLOC /* SQL type 964 */ SQL TYPE IS CLOB_FILE CHAPFL /* SQL type 920 */ SQL TYPE IS BLOB (1M) VIDEO /* SQL type 404 */ SQL TYPE IS BLOB_LOCATOR VIDLOC /* SQL type 960 */ SQL TYPE IS BLOB_FILE VIDFL /* SQL type 916 */ CHARACTER*10 DATE /* SQL type 384 */ CHARACTER*8 TIME /* SQL type 388 */ CHARACTER*26 TIMESTAMP /* SQL type 392 */ INTEGER*2 WAGE_IND /* SQL type 500 */ EXEC SQL END DECLARE SECTION 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
- 112. 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. INTEGER*2 INTEGER*4 REAL*4 REAL *8 DOUBLE PRECISION , varname / 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 , CHARACTER varname *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
- 113. 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 my_varchar(1000+2) integer*2 my_varchar_length character my_varchar_data(1000) equivalence( 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 my_lvarchar(10000+2) integer*2 my_lvarchar_length character my_lvarchar_data(10000) equivalence( 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
- 114. 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 ( length ) variable-name CLOB 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 my_blob(2097152+4) integer*4 my_blob_length character my_blob_data(2097152) equivalence( 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 my_clob(131072000+4) integer*4 my_clob_length character my_clob_data(131072000) equivalence( my_clob(1), + my_clob_length ) equivalence( my_clob(5), + my_clob_data ) 108 Developing Embedded SQL Applications
- 115. 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 BLOB_LOCATOR variable-name 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 variable-name CLOB_FILE 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
- 116. character my_file(267) integer*4 my_file_name_length integer*4 my_file_data_length integer*4 my_file_file_options character*255 my_file_name equivalence( 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
- 117. 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. 0 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
- 118. -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
- 119. 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
- 120. /* ------------ 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 :hv1='ordinary quoted string longer than 32K ...' CLOB :hv2="'string with embedded delimiting quotation marks ", "longer than 32K...'" CLOB :hv3="G'DBCS string with embedded delimiting single ", "quotation marks, beginning with G, longer than 32K...'" DBCLOB :hv4="BIN'string with embedded delimiting single ", "quotation marks, beginning with BIN, any length...'" BLOB 114 Developing Embedded SQL Applications
- 121. 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 LOCATOR CLOB DBCLOB 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 FILE CLOB DBCLOB 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
- 122. 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
- 123. 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
- 124. 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
- 125. 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 Only FORTRAN comments are allowed here EXEC SQL + -- SQL comments, and C full-line FORTRAN comment are allowed here + DECLARE C1 CURSOR FOR sname I=7 ! End of line FORTRAN comments allowed here C 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
- 126. 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
- 127. About this task The following diagram describes the structure of the 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 HEADER sqldaid CHAR sqln SMALLINT sqltype SMALLINT sqldata POINTER sqlname VARCHAR (30) sqldabc INTEGER sqld SMALLINT sqllen SMALLINT sqlind POINTER Other SQLVAR Entries SQLVAR (1 per field) Figure 2. The SQL Descriptor Area (SQLDA) Chapter 3. Programming 121
- 128. 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
- 129. 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
- 130. 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
- 131. 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
- 132. 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 Example Source Code C and C++ #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
- 133. Language Example Source Code COBOL 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
- 134. 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 ! Header integer*4 out_sqldabc integer*2 out_sqln integer*2 out_sqld integer*2 out_sqltype1 ! First Variable integer*2 out_sqllen1 integer*4 out_sqldata1 integer*4 out_sqlind1 integer*2 out_sqlnamel1 character*30 out_sqlnamec1 equivalence( out_sqlda(sqlda_sqldaid_ofs), out_sqldaid ) equivalence( out_sqlda(sqlda_sqldabc_ofs), out_sqldabc ) equivalence( out_sqlda(sqlda_sqln_ofs), out_sqln ) equivalence( out_sqlda(sqlda_sqld_ofs), out_sqld ) equivalence( out_sqlda(sqlvar1+sqlvar_type_ofs), out_sqltype1 ) equivalence( out_sqlda(sqlvar1+sqlvar_len_ofs), out_sqllen1 ) equivalence( out_sqlda(sqlvar1+sqlvar_data_ofs), out_sqldata1 ) equivalence( out_sqlda(sqlvar1+sqlvar_ind_ofs), out_sqlind1 ) equivalence( out_sqlda(sqlvar1+sqlvar_name_length_ofs), + out_sqlnamel1 ) equivalence( out_sqlda(sqlvar1+sqlvar_name_data_ofs), + out_sqlnamec1 ) C Declare Local Variables for Holding Returned Data. real*8 salary integer*2 sal_ind C Initialize the Output SQLDA (Header) out_sqldaid = ’OUT_SQLDA’ out_sqldabc = sqlda_header_sz + 1*sqlvar_struct_sz out_sqln = 1 out_sqld = 1 C 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
- 135. 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 n/a2 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 n/a3 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 REAL4 480/481 SQL_TYP_FLOAT / SQL_TYP_NFLOAT DECIMAL5 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 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
- 136. 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
- 137. 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
- 138. 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
- 139. 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
- 140. 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
- 141. 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
- 142. 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
- 143. 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
- 144. 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
- 145. Procedure To process a cursor: 1. Specify the cursor using a DECLARE CURSOR statement. 2. Perform the query and build the result table using the OPEN statement. 3. 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
- 146. 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 = %sn", appMsg); strcat( sqlInfo, sqlInfoToken); sprintf( sqlInfoToken, " line = %dn", line); strcat( sqlInfo, sqlInfoToken); sprintf( sqlInfoToken, " file = %sn", file); strcat( sqlInfo, sqlInfoToken); sprintf( sqlInfoToken, " SQLCODE = %ldn", 140 Developing Embedded SQL Applications
- 147. 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, "%sn", errorMsg); strcat( sqlInfo, sqlInfoToken); } /* get SQLSTATE message */ rc = sqlogstt( sqlstateMsg, 1024, 80, pSqlca->sqlstate); if (rc == 0) { sprintf( sqlInfoToken, "%sn", 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
- 148. 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
- 149. 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
- 150. EXEC SQL ROLLBACK RELEASE; EXEC SQL ROLLBACK WORK RELEASE; EXEC SQL COMMIT RELEASE; EXEC SQL 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
- 151. 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
- 152. 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. Source Files With SQL Statements Modified Source Files Object Files Source Files Without SQL Statements Libraries Precompiler (db2 PREP) PACKAGE Create a Package Host Language Compiler Host Language Linker Executable Program Database Manager Package (Package) Bind File Binder (db2 BIND) BINDFILE Create a Bind File 1 2 3 4 6 5 Figure 3. Preparing Programs Written in Compiled Host Languages 146 Developing Embedded SQL Applications
- 153. 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
- 154. 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
- 155. 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
- 156. 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
- 157. 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
- 158. 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
- 159. 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
- 160. 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
- 161. 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
- 162. 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 SQL Attributes: Bind Behavior Setting for Dynamic SQL Attributes: Run Behavior Setting for Dynamic SQL Attributes: Define Behavior Setting for Dynamic SQL Attributes: Invoke Behavior Authorization ID The implicit or explicit value of the BIND OWNER command parameter ID of User Executing Package Routine definer (not the routine's package owner) Current statement authorization ID when routine is invoked. Default qualifier for unqualified objects The implicit or explicit value of the BIND QUALIFIER command parameter CURRENT SCHEMA Special Register Routine definer (not the routine's package owner) Current statement authorization ID when routine is invoked. Can execute GRANT, REVOKE, ALTER, CREATE, DROP, COMMENT ON, RENAME, SET INTEGRITY, and SET EVENT MONITOR STATE No Yes No No 156 Developing Embedded SQL Applications
- 163. 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
- 164. 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
- 165. 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
- 166. 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
- 167. 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 ddcsmvs.lst for System z v ddcsvse.lst for VSE v ddcsvm.lst for VM v 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
- 168. 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 system.syssynonyms v system.syskeys v system.syscolauth v 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:sqllibbnd 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
- 169. For example: ddcspkgn @ddcsmvs.lst might yield the following output: Bind File Package Name ------------------------------ ------------------------------ f:sqllibbnddb2ajgrt.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
- 170. 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
- 171. 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 AIX HP-UX Linux Solaris Windows C samples/c 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
- 172. 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 IBM COBOL samples/cobol bldapp bldrtn n/a n/a n/a bldapp.bat bldrtn.bat Micro Focus COBOL samples/cobol_mf bldapp bldrtn 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
- 173. 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 C samples/c utilapi.c utilapi.h utilemb.sqc utilemb.h C++ samples/cpp utilapi.C utilapi.h utilemb.sqC utilemb.h IBM COBOL samples/cobol checkerr.cbl n/a n/a n/a Micro Focus COBOL samples/cobol_mf checkerr.cbl n/a n/a n/a 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
- 174. /* 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 sqllibsamplesc 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
- 175. -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
- 176. 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. +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. -Ae 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. +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. 170 Developing Embedded SQL Applications
- 177. 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. +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. -ext 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
- 178. 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. -o $1 Specify the executable. $1.o Specify the object file. 172 Developing Embedded SQL Applications
- 179. 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
- 180. 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
- 181. -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
- 182. 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
- 183. -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
- 184. 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 sqllibsamplesc and sqllibsamplescpp 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 sqllibsamplesc, or from the C++ source file tbmod.sqx in sqllibsamplescpp: – If connecting to the sample database on the same instance, enter: 178 Developing Embedded SQL Applications
- 185. 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 samplescdbthrds.sqc or samplescppdbthrds.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
- 186. To build the DB2 API non-embedded SQL sample program, cli_info, from either the source file cli_info.c, in sqllibsamplesc, or from the source file cli_info.cxx, in sqllibsamplescpp, 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 sqllibsamplesc and sqllibsamplescpp 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
- 187. 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 attach to node_name db2 create db sample2 db2 detach db2 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 samplesc or samplescpp 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
- 188. 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 sqllibsamplescobol 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: cob2 Use the compiler as a front end for the linker. -o $1 Specify the executable program. $1.o Specify the program object file. 182 Developing Embedded SQL Applications
- 189. 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
- 190. 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
- 191. -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
- 192. -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%includecobol_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
- 193. 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
- 194. 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%includecobol_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%includecobol_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%includecobol_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 2. Select System 3. Select the Advanced tab 4. Click Environment Variables 5. 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. 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
- 195. 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 -s /opt/lib/mfcobol/lib/libcobrts.so /usr/lib ln -s /opt/lib/mfcobol/lib/libcobrts_t.so /usr/lib ln -s /opt/lib/mfcobol/lib/libcobrts.so.2 /usr/lib ln -s /opt/lib/mfcobol/lib/libcobrts_t.so.2 /usr/lib ln -s /opt/lib/mfcobol/lib/libcobcrtn.so /usr/lib ln -s /opt/lib/mfcobol/lib/libcobcrtn.so.2 /usr/lib ln -s /opt/lib/mfcobol/lib/libcobmisc.so /usr/lib ln -s /opt/lib/mfcobol/lib/libcobmisc_t.so /usr/lib ln -s /opt/lib/mfcobol/lib/libcobmisc.so.2 /usr/lib ln -s /opt/lib/mfcobol/lib/libcobmisc_t.so.2 /usr/lib ln -s /opt/lib/mfcobol/lib/libcobscreen.so /usr/lib ln -s /opt/lib/mfcobol/lib/libcobscreen.so.2 /usr/lib ln -s /opt/lib/mfcobol/lib/libcobtrace.so /usr/lib ln -s /opt/lib/mfcobol/lib/libcobtrace_t.so /usr/lib ln -s /opt/lib/mfcobol/lib/libcobtrace.so.2 /usr/lib ln -s /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
- 196. 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
- 197. 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
- 198. 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
- 199. 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 sqllibsamplescobol 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
- 200. 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
- 201. 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 sqllibsamplescobol_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
- 202. 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
- 203. 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
- 204. /* Any comment will do. */ REXX sample programs can be found in the directory sqllibsamplesrexx. 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%SQLLIBsamplesc directory, refer to the %DB2PATH%SQLLIBsamplescbldapp.bat file. This batch file calls another batch file, %DB2PATH%SQLLIBsamplescembprep.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
- 205. 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
- 206. 200 Developing Embedded SQL Applications
- 207. 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
- 208. 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
- 209. 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 ReceiveTimeout v TcpipConnectTimeout v keepAliveTimeOut v 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
- 210. 204 Developing Embedded SQL Applications
- 211. 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
- 212. 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; /* bulk fetch */ ... /* 100 or less rows */ ... } end_fetch: EXEC SQL CLOSE empcr; 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
- 213. 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
- 214. 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
- 215. 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
- 216. 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
- 217. 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
- 218. 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 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 Concepts and Configuration Reference SC27-4546-00 Yes July 28, 2013 Data Movement Utilities Guide and Reference SC27-5528-00 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 212 Developing Embedded SQL Applications
- 219. Table 25. DB2 technical information (continued) Name Form Number Available in print Availability date Getting Started with DB2 Installation and Administration on Linux and Windows GI13-2085-00 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 and Configuring DB2 Connect Personal Edition SC27-5516-00 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
- 220. 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
- 221. 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
- 222. 216 Developing Embedded SQL Applications
- 223. 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
- 224. 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
- 225. 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
- 226. 220 Developing Embedded SQL Applications
- 227. Index Special characters .NET batch files 165 Numerics 32-bit platforms 16 64-bit platforms 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 165 BIGINT data type COBOL 46 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 © Copyright IBM Corp. 1993, 2013 221
- 228. 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 87 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 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 222 Developing Embedded SQL Applications
- 229. 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
- 230. data types BINARY 94 C embedded SQL applications 39, 84, 88 C++ embedded SQL applications 39, 84, 88 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, 56 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 46 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 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 224 Developing Embedded SQL Applications
- 231. 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 22 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 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 142 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 225
- 232. 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 55 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 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 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 226 Developing Embedded SQL Applications
- 233. 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 M macro expansion C/C++ language 88 member operators C/C++ restriction 87 MIA LANGLEVEL precompile option 39 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 N notices 217 NULL SQL value indicator variables 59 null-terminated character form 39 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 O Object REXX for Windows applications building 197 optimizer dynamic SQL 13 static SQL 13 P packages creating BIND command and existing bind file 157 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 Index 227
- 234. 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 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 228 Developing Embedded SQL Applications
- 235. 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 122 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 Index 229
- 236. 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 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 192 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 230 Developing Embedded SQL Applications
- 237. 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
- 238. 232 Developing Embedded SQL Applications