DB2 10.5 for Linux, UNIX, and Windows

WCHARTYPE precompiler option for graphic data in C and C++ embedded SQL applications

You can use the WCHARTYPE precompiler option to specify whether you want to use multibyte format or wide-character format for your graphic data.

There are two possible values for the WCHARTYPE option:

CONVERT

If you select the WCHARTYPE CONVERT option in Linux or UNIX operating systems, character codes are converted between the graphic host variable and the database manager. For graphic input host variables, the character code is converted from wide-character format to multibyte DBCS character format with the ANSI C function wcstombs() before the data is sent to the database manager. For graphic output host variables, the character code is converted from multibyte DBCS character format to wide-character format with the ANSI C function mbstowcs() before the data received from the database manager is stored in the host variable.

For Windows operating systems, if a conversion failure is encountered for graphic host variables, user can set the SkipLocalCPConversionForWcharConvert keyword to ON in the IBM® data server driver configuration file (db2dsdriver.cfg) to avoid the failure.

The advantage to using the WCHARTYPE CONVERT option is that it allows your application to use the ANSI C mechanisms for dealing with wide-character strings (L-literals, 'wc' string functions, and others) without having to explicitly convert the data to multibyte format before data is sent to the database manager. The disadvantage is that the implicit conversion can have an impact on the performance of your application at run time, and it can increase memory requirements.

If you select the WCHARTYPE CONVERT option, declare all graphic host variables with wchar_t instead of sqldbchar.

If you want the WCHARTYPE CONVERT option 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 multibyte format when interfacing with the database manager.

If you select the WCHARTYPE NOCONVERT option, declare all graphic host variables with the sqldbchar type for maximum portability to other DB2 client/server environments.

You must consider the guidelines include in the following list:

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.
Avoid use of non-DBCS (non-double byte characters) characters, and wide-characters that can be converted to non-DBCS characters, in graphic strings. 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 the WCHARTYPE CONVERT setting is in effect, wide-character data that converts to DBCS data. Use character host variables to store mixed double-byte and single-byte data. Mixed data host variables are unaffected by the setting of the WCHARTYPE option.
In applications where the WCHARTYPE NOCONVERT precompile option is used, avoid use of L-literals with graphic host variables as L-literals are in wide-character format. An L-literal is a C wide-character string literal that is 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, use graphic string constants, which are independent of the WCHARTYPE setting in SQL statements.
The setting of the WCHARTYPE option affects graphic data that is passed to and from the database manager using the SQLDA structure and host variables. If the WCHARTYPE CONVERT setting is in effect, graphic data that is received from the application through an SQLDA is presumed to be in wide-character format, and is converted to DBCS format by implicit call to the wcstombs() function. Similarly, graphic output data that is received by an application was converted to wide-character format before the data was placed in application storage.
Not-fenced stored procedures must be precompiled with the WCHARTYPE NOCONVERT option. Ordinary fenced stored procedures can be precompiled with either the CONVERT or NOCONVERT options, which affects the format of graphic data that is manipulated by SQL statements that are contained in the stored procedure. In either case, however, any graphic data that is passed into the stored procedure through the SQLDA is 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 is 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 occurs on the SQLDA, depending on the calling application's WCHARTYPE setting.
Graphic data that is passed to user-defined functions (UDFs) is always in DBCS format. Likewise, any graphic data that is returned from a UDF is assumed to be in DBCS format for DBCS databases, and UCS-2 format for EUC and UCS-2 databases.
Data that is stored in DBCLOB files by using 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 that are 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 converts the code page in this situation; however, the Microsoft C runtime environment does not handle substitution characters for certain double byte character and it can result in run time conversion errors.
If you precompile C applications with 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 an environment with mixed CONVERT and NOCONVERT applications, you can encounter errors if invalid graphic data is inserted by a NOCONVERT application and then fetched by a CONVERT application.