Special host language programming considerations are discussed in the following pages. Included is information on language restrictions, host-language-specific include files, embedding SQL statements, host variables, and supported data types for host variables.
The following sections describe the C/C++ language restrictions.
Do not use C preprocessor constructs such as, macros, #ifdefs, or symbol substitutions in the host variable declare section or in any SQL statements. You can use these constructs elsewhere in your application. The SQL precompiler does not handle preprocessor functions such as macro processing or symbol substitution, and does not support conditional precompilation (#ifdefs). The following example demonstrates incorrect placement of the C preprocessor constructs:
#define NAME_LENGTH 20
EXEC SQL BEGIN DECLARE SECTION;
char name [NAME_LENGTH]; /* incorrect placement of macro */
EXEC SQL END DECLARE SECTION;
#ifdef PRODUCTION /* careful - both statements will be precompiled */
EXEC SQL SELECT NAME INTO :name FROM PRODUCTION.PAYROLL
WHERE ID = 10;
#else
EXEC SQL SELECT NAME INTO :name FROM TESTING.PAYROLL
WHERE ID = 10;
#endif
By default, the input file can have the following extensions:
The corresponding default output files have the following extensions:
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.
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/C++ precompiler searches the current directory first, then the directories specified by the DB2INCLUDE environment variable. Consider the following examples:
If the file specified in the INCLUDE statement is not enclosed in quotes, as above, the C/C++ precompiler searches for payroll.sqc, then payroll.h, in each directory in which it looks. On UNIX operating systems, the C/C++ precompiler searches for payroll.sqC, then payroll.sqx, then payroll.hpp, then payroll.h in each directory in which it looks. On OS/2 or Windows-based operating systems, the C/C++ precompiler searches for payroll.sqx, then payroll.hpp, then payroll.h in each directory in which it looks.
If the file name is enclosed in quotes, as above, no extension is added to the name.
If the file name in quotes 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 based systems, if DB2INCLUDE is set to '/disk2:myfiles/c', the C/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 OS/2 and Windows-based operating systems, substitute back slashes (\) for the forward slashes in the above 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 as usual. |
To help relate compiler errors back to the original source the precompiler generates ANSI #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 precompiler output. 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 wish to use behaves unexpectedly, use the NOLINEMACRO option (used with db2 PREP) when precompiling. This will prevent the #line macros from being generated.
Some characters from the C or C++ character set are not available on all keyboards. These characters can be entered into a C or C++ source program 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:
The remaining trigraphs listed below may occur elsewhere in a C or C++ source program:
When writing a stored procedure or a UDF using C++, you may want to consider declaring the procedure or UDF as:
extern "C" ...procedure or function declaration...
The extern "C" prevents type decoration of the function name by the C++ compiler. Without this declaration, you have to include all the type decoration for the function name when you call the stored procedure, or issue the CREATE FUNCTION statement.
The host-language-specific include files (header files) for C and C++ have the file extension .h. The include files that are intended to be used in your applications, are described below.
This file includes both sqlcli.h and sqlext.h (which contains ODBC Level2 API definitions).
Embedded SQL statements consist of the following three elements:
For example:
EXEC SQL SELECT col INTO :hostvar FROM table;
The following rules apply to embedded SQL statements:
C/C++ comments can be placed after the statement terminator because the precompiler distinguishes them as separate from the SQL statement.
EXEC SQL OPEN c1; if (SQLCODE >= 0) EXEC SQL FETCH c1 INTO :hv;
You can use comments in a static statement string wherever blanks are allowed. Use the C/C++ comment delimiters /* */, or the SQL comment symbol (--). //-style C++ comments are not permitted within static SQL statements, but they may be used elsewhere in your program. The precompiler removes comments before processing the SQL statement. You cannot use the C and C++ comment delimiters /* */ or // in a dynamic SQL statement. However, you can use them elsewhere in your program.
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 or delimited identifier.
Note that the actual characters used for end-of-line and TAB vary from platform to platform. For example, OS/2 uses Carriage Return/Line Feed for end-of-line, whereas UNIX-based systems use just a Line Feed.
Host variables are C or C++ language variables that are referenced within SQL statements. They allow an application to pass input data to and receive output data from the database manager. After the application is precompiled, host variables are used by the compiler as any other C/C++ variable. Obey the rules described in the following sections when naming, declaring, and using host variables.
The SQL precompiler identifies host variables by their declared name. The following rules apply:
EXEC SQL BEGIN DECLARE SECTION;
char varsql; /* allowed */
char sqlvar; /* not allowed */
char SQL_VAR; /* not allowed */
EXEC SQL END DECLARE SECTION;
void f1(int i)
{
EXEC SQL BEGIN DECLARE SECTION;
short host_var_1;
EXEC SQL END DECLARE SECTION;
EXEC SQL SELECT COL1 INTO :host_var_1 from TBL1;
}
void f2(int i)
{
EXEC SQL BEGIN DECLARE SECTION;
short host_var_2;
EXEC SQL END DECLARE SECTION;
EXEC SQL INSERT INTO TBL1 VALUES (:host_var_2);
}
It is also possible to have several local host variables with the same name as long as they all have the same type and size. To do this, declare the first occurrence of the host variable to the precompiler between BEGIN DECLARE SECTION and END DECLARE SECTION statements, and leave subsequent declarations of the variable out of declare sections. The following code shows an example of this:
void f3(int i)
{
EXEC SQL BEGIN DECLARE SECTION;
char host_var_3[25];
EXEC SQL END DECLARE SECTION;
EXEC SQL SELECT COL2 INTO :host_var_3 FROM TBL2;
}
void f4(int i)
{
char host_var_3[25];
EXEC SQL INSERT INTO TBL2 VALUES (:host_var_3);
}
Since f3 and f4 are in the same module, and since host_var_3 has the same type and length in both functions, a single declaration to the precompiler is sufficient to use it in both places.
An SQL declare section must be used to identify host variable declarations. This alerts the precompiler to any host variables that can be referenced in subsequent SQL statements.
The C/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. Using typedefs for host variable types is not allowed, and host variables cannot be embedded in structures. You can declare C++ class data members as host variables. For more information on classes, see "Using 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.
Figure 26 shows the syntax for declaring numeric host variables in C or C++.
Figure 26. Syntax for Numeric Host Variables in C or C++
(1)
>>--.----------.--.----------.--.-float-----------------.--------------->
|-auto-----| |-const----| | (2) |
|-extern---| '-volatile-' |-double----------------|
|-static---| | (3) |
'-register-' '-.-long-----.--.-----.-'
| (4)| '-int-'
'-short----'
<-,--------------------------------------------------<
>----.-------------------------.--varname--.----------.----;-----------><
| <---------------------< | '-=--value-'
'---.-*-.--.----------.---'
'-&-' |-const----|
'-volatile-'
NOTES:
(1) REAL (SQLTYPE 480), length 4
(2) DOUBLE (SQLTYPE 480), length 8
(3) INTEGER (SQLTYPE 496)
(4) SMALLINT (SQLTYPE 500)
|
Figure 27 shows the syntax for declaring fixed and null-terminated character host variables in C or C++.
Figure 27. Form 1: Syntax for Fixed and Null-terminated Character Host Variables in C/C++
>>--.----------.--.----------.--.----------.--char---------------------->
|-auto-----| |-const----| '-unsigned-'
|-extern---| '-volatile-'
|-static---|
'-register-'
<-,------------------------------<
>----.-| CHAR |-----.--.----------.----;-------------------------------><
'-| C String |-' '-=--value-'
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)
|
Figure 28 shows the syntax for declaring variable length character host variables in C or C++.
Figure 28. Form 2: Syntax for Variable Length Character Host Variables in C/C++
>>--.----------.--.----------.--struct--.-----.------------------------->
|-auto-----| |-const----| '-tag-'
|-extern---| '-volatile-'
|-static---|
'-register-'
(1)
>--{--short--.-----.--var1--;--.----------.--char--var2--[number]-----;---}-->
'-int-' '-unsigned-'
<-,------------------------------------------------<
>----.-------------------------.--varname--| Values |----;-------------><
| <---------------------< |
'---.-*-.--.----------.---'
'-&-' |-const----|
'-volatile-'
VALUES:
|--.------------------------------.-------------------------------------|
'-=--{--value-1--,--value-2--}-'
NOTE:
(1) In FORM 2, the value of [number] determines if the host variable is
VARCHAR (SQLTYPE 448) or LONG VARCHAR (SQLTYPE 456).
|
Notes:
Indicator variables should be declared as a short data type.
Graphic host variable declarations can take one of three forms:
For details on using graphic host variables, see "Handling Graphic Host Variables".
Figure 29 shows the syntax for declaring a graphic host variable using the single-graphic form and the null-terminated graphic form.
Figure 29. Syntax for Graphic Declaration (Single-Graphic Form and Null-Terminated Graphic Form)
(1)
>>--.----------.--.----------.--.-sqldbchar----.------------------------>
|-auto-----| |-const----| | (2) |
|-extern---| '-volatile-' '-wchar_t------'
|-static---|
'-register-'
<-,------------------------------<
>----.-| CHAR |-----.--.----------.----;-------------------------------><
'-| C String |-' '-=--value-'
CHAR:
(3)
|--.-------------------------.--varname---------------------------------|
| <---------------------< |
'---.-*-.--.----------.---'
'-&-' |-const----|
'-volatile-'
C STRING:
(4)
|--.-varname------------------------------------.--[length]-------------|
'-(--.-------------------------.--varname--)-'
| <---------------------< |
'---.-*-.--.----------.---'
'-&-' |-const----|
'-volatile-'
NOTES:
(1) To determine which of the two graphic types should be used, see
"Selecting the wchar_t or sqldbchar Data Type".
(2) To determine which of the two graphic types should be used, see
"Selecting the wchar_t or sqldbchar Data Type".
(3) GRAPHIC (SQLTYPE 468), Length 1
(4) Null-terminated graphic string (SQLTYPE 400)
|
Notes:
Figure 30 shows the syntax for declaring a graphic host variable using the VARGRAPHIC structured form.
Figure 30. Syntax for Graphic Declaration (VARGRAPHIC Structured Form)
>>--.----------.--.----------.--struct--.-----.------------------------->
|-auto-----| |-const----| '-tag-'
|-extern---| '-volatile-'
|-static---|
'-register-'
(1)
>--{--short--.-----.--var-1--;--.-sqldbchar----.--var-2--[length]--;--}->
'-int-' | (2) |
'-wchar_t------'
<-,--------------------------------------------<
>----.-------------------------.--| Variable |--;----------------------><
| <---------------------< |
'---.-*-.--.----------.---'
'-&-' |-const----|
'-volatile-'
VARIABLE:
|--variable-name--.------------------------------.----------------------|
'-=--{--value-1--,--value-2--}-'
NOTES:
(1) To determine which of the two graphic types should be used, see
"Selecting the wchar_t or sqldbchar Data Type".
(2) To determine which of the two graphic types should be used, see
"Selecting the wchar_t or sqldbchar Data Type".
|
Notes:
Figure 31 shows the syntax for declaring large object (LOB) host variables in C or C++.
Figure 31. Syntax for Large Object (LOB) Host Variables in C/C++
>>--.----------.--.----------.--SQL TYPE IS--.-BLOB---.----------------->
|-auto-----| |-const----| |-CLOB---|
|-extern---| '-volatile-' '-DBCLOB-'
|-static---|
'-register-'
>--(length-.---.-)------------------------------------------------------>
|-K-|
|-M-|
'-G-'
<-,--------------------------------------------------------<
>----.-------------------------.--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:
SQL TYPE IS BLOB my_blob;
| Note: | Wide character literals, for example, L"Hello", should only be used in a precompiled program if the WCHARTYPE CONVERT precompile option is selected. |
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 {
unsigned long 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 {
unsigned long 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 {
unsigned long 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:
struct my_dbclob2_t {
unsigned long length;
wchar_t data[30000];
} my_dbclob2 = SQL_DBCLOB_INIT(L"mydbdata");
Figure 32 shows the syntax for declaring large object (LOB) locator host variables in C or C++.
Figure 32. Syntax for Large Object (LOB) Locator Host Variables in C/C++
>>--.----------.--.----------.--SQL TYPE IS--.-BLOB_LOCATOR---.--------->
|-auto-----| |-const----| |-CLOB_LOCATOR---|
|-extern---| '-volatile-' '-DBCLOB_LOCATOR-'
|-static---|
'-register-'
<-,-----------<
>----| Options |-------------------------------------------------------><
OPTIONS:
|--.-------------------------------------------------------------.------|
| <---------------------< |
'---.-*-.--.----------.----variable-name--.--------------.--;-'
'-&-' |-const----| '-= init-value-'
'-volatile-'
|
Notes:
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:
long my_locator;
Figure 33 shows the syntax for declaring file reference host variables in C or C++.
Figure 33. Syntax for File Reference Host Variables in C/C++
>>--.----------.--.----------.--SQL TYPE IS--.-BLOB_FILE---.------------>
|-auto-----| |-const----| |-CLOB_FILE---|
|-extern---| '-volatile-' '-DBCLOB_FILE-'
|-static---|
'-register-'
<-,-----------<
>----| Options |-------------------------------------------------------><
OPTIONS:
|--.-------------------------------------------------------------.------|
| <---------------------< |
'---.-*-.--.----------.----variable-name--.--------------.--;-'
'-&-' |-const----| '-= init-value-'
'-volatile-'
|
Note:
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 {
unsigned long name_length;
unsigned long data_length;
unsigned long file_options;
char name[255];
} my_file;
In C++ declare sections, you cannot initialize host variables using 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;
C/C++ null-terminated strings have their own SQLTYPE (460/461 for character and 468/469 for graphic).
C/C++ null-terminated strings are handled differently depending on the value of the LANGLEVEL precompiler option. If a host variable of one of these SQLTYPEs 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:
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 as defined above. When specified in any other SQL context, a host variable of SQLTYPE 468 with length n is treated as a VARGRAPHIC data type with length n as defined above.
Host variables may be declared as pointers to specific data types with the following restrictions:
char mystring[20];
char (*mystring)[20];
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 an invalid 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 may not be what is intended. To define a pointer host variable that can indicate different character strings, use the first declaration form above.
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; /* Correct */
You can declare class data members as host variables (but not classes or objects themselves). The following example illustrates the method to use:
Figure 34. Example of Declaring Class Data Members as Host Variables
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.
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). This means that no SQLDA optimization will be done by the database manager. (This is true whenever pointer host variables are involved in SQL statements.)
The following example shows how you might directly use class data members which you have declared as host variables, in an SQL statement.
Figure 35. Example of Using Class Data Members Directly 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 example in Figure 34), 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.
Figure 36. Example of Using Class Data Members Indirectly in an 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;
}
|
You cannot use the C++ scope resolution operator '::', nor the C/C++ member operators '.' or '->' in embedded SQL statements. 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 desired scoped variable, and 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';
To handle graphic data in C or C++ applications, use host variables based on either the wchar_t C/C++ data type or the sqldbchar data type provided by DB2. You can assign these types of 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:
Single-graphic host variables have an SQLTYPE of 468/469 that is equivalent to GRAPHIC(1) SQL data type. (See Figure 29.)
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. (See Figure 29.)
VARGRAPHIC structured host variables have an SQLTYPE of 464/465 if their length is between 1 and 2 000 bytes. They have an SQLTYPE of 472/473 if their length is between 2000 and 16 350 bytes. (See Figure 30.)
Some character encoding schemes, particularly those from east Asian countries 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). 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/C++ data type. There are ANSI C and X/OPEN Portability Guide 4 (XPG4) conformant subroutines 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.
While the size and encoding of DB2 graphic data is constant from one platform to another for a particular code page, the size and internal format of the ANSI C or C++ wchar_t data type depends on which compiler you use and which platform you are on. 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. For more information on UCS-2 data, see "Japanese and Traditional-Chinese EUC Code Set Considerations".
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 (as described in "The WCHARTYPE Precompiler Option"). 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 may 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.
Using the WCHARTYPE precompiler option, you can specify which graphic character format you want to use in your C/C++ application. This option provides you with the flexibility to choose between having your graphic data in multi-byte format or in wide-character format. There are two possible values for the WCHARTYPE option:
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, etc.) 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.
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.
| Note: | The WCHARTYPE CONVERT precompile option is not currently supported in programs running on the DB2 Windows 3.1 client. For those programs, use the default (WCHARTYPE NOCONVERT). |
If you select WCHARTYPE NOCONVERT, declare all graphic host variables using the sqldbchar type for maximum portability to other DB2 client/server platforms.
See the Command Reference for more information.
Other guidelines you need to observe are:
Notes:
If your application code page is Japanese or Traditional-Chinese EUC, you can access GRAPHIC columns at a database server by using either the CONVERT or the NOCONVERT option, and 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 the following cases:
The Client Application Enabler converts graphic data from the wide character format to EUC, 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 EUC code page identifier. When graphic data is retrieved from a database by a client running under the Japanese or Traditional-Chinese EUC code set, it is tagged with the UCS-2 code page identifier. The Client Application Enabler then converts the data from UCS-2 to EUC, then to the wide character format. If an input SQLDA is used instead of a host variable, then you are required to ensure that graphic data is encoded using the wide character format. This data will be converted to UCS-2 and then sent to the database server. These conversions will impact performance.
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 simply 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 EUC to UCS-2 and from UCS-2 to EUC 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. 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). This is because characters in both of these EUC code sets become single-byte when converted from UCS-2 to PC DBCS.
For general EUC application development guidelines, see "Japanese and Traditional-Chinese EUC Code Set Considerations".
Certain predefined C and C++ data types correspond to the database manager column types. Only these C/C++ data types can be declared as host variables.
Table 16 shows the C/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 16. SQL Data Types Mapped to C/C++ Declarations
| SQL Column Type1 | C/C++ Data Type | SQL Column Type Description | ||
|---|---|---|---|---|
SMALLINT (500 or 501) |
short short int | 16-bit signed integer | ||
INTEGER (496 or 497) |
long long int | 32-bit signed integer | ||
REAL2 (480 or 481) | float | Single-precision floating point | ||
DOUBLE3 (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 | ||
VARCHAR(n) (448 or 449) |
struct tag {
short int;
char[n]
}
1<=n<=4 000
| Non null-terminated varying character string with 2-byte string length indicator | ||
Alternately use char[n+1] where n is large enough to
hold the data
1<=n<=4 000 | null-terminated variable-length character string
| |||
LONG VARCHAR (456 or 457) |
struct tag {
short int;
char[n]
}
4 001<=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 variable4 (964 or 965) |
sql type is clob_locator | Identifies CLOB entities residing on the server | ||
CLOB file reference variable4 (808 or 809) |
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 variable4 (960 or 961) |
sql type is blob_locator | Identifies BLOB entities on the server | ||
BLOB file reference variable4 (804 or 805) |
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. | |||
TIMESTAMP (392 or 393) | null-terminated character form | Allow at least 27 characters to accommodate the null-terminator. | ||
| VARCHAR structured form | Allow at least 26 characters. | |||
| ||||
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<=2 000
| 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<=2 000 | null-terminated variable-length double-byte character string
| |||
LONG VARGRAPHIC (472 or 473) |
struct tag {
short int;
sqldbchar[n]
}
2 001<=n<=16 350
| Non null-terminated varying double-byte character string with 2-byte string length indicator | ||
| ||||
GRAPHIC(1) (468 or 469) | wchar_t |
| ||
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<=2 000
| 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<=2 000 | null-terminated variable-length double-byte character string
| |||
LONG VARGRAPHIC (472 or 473) |
struct tag {
short int;
wchar_t [n]
}
2 001<=n<=16 350
| Non null-terminated varying double-byte character string with 2-byte string length indicator | ||
| ||||
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 | ||
DBCLOB locator variable4 (968 or 969) |
sql type is dbclob_locator | Identifies DBCLOB entities residing on the server | ||
DBCLOB file reference variable4 (812 or 813) |
sql type is dbclob_file | Descriptor for file containing DBCLOB data | ||
The following 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 */
long salary; /* SQL type 496 */
long 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[5764];
} 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 808 */
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 804 */
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 812 */
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];
} 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;
The following are additional rules for supported C/C++ data types:
The standard C or C++ string type 460 should not be used 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.
When using the LANGLEVEL precompile option with a value of SQL92E, the following two declarations may be included as host variables:
EXEC SQL BEGIN DECLARE SECTION;
char SQLSTATE[6]
long SQLCODE;
.
.
.
EXEC SQL END DECLARE SECTION;
If neither of these is specified, the SQLCODE declaration is assumed during the precompile step. Note that when using this option, the INCLUDE SQLCA statement should not be specified.
In an application that is made up of multiple source files, the SQLCODE and SQLSTATE variables may be defined in the first source file as above. Subsequent source files should modify the definitions as follows:
extern long SQLCODE; extern char SQLSTATE[6];