Using the WCHARTYPE precompiler option, you can specify which graphic
character format you want to use in your C or 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:
- 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.
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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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: - 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
run-time environment does not handle substitution characters for certain
double byte characters. This could result in run time conversion
errors.
- 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.