8 Globalization and Unicode Support

UString Datatype

UString is a datatype that enables applications and the OCCI library to pass and receive Unicode data in UTF-16 encoding. UString is templated from the C++ STL basic_string with Oracle's utext datatype.

typedef basic_string<utext> UString;

Oracle's utext datatype is a 2 byte short datatype and represents Unicode characters in the UTF-16 encoding. A Unicode character's codepoint can be represented in 1 utext or 2 utexts (2 or 4 bytes). Characters from European and most Asian scripts are represented in a single utext. Supplementary characters defined in the Unicode 3.1 standard are represented with 2 utext elements.

In Microsoft Windows platforms, UString is equivalent to the C++ standard wstring datatype. This is because the wchar_t datatype is type defined to a 2 byte short in these platforms, which is same as Oracle's utext, allowing applications to use a wstring type variable where a UString would be normally required. Consequently, applications can also pass wide-character string literals, created by prefixing the literal with the letter 'L', to OCCI Unicode APIs.

//bind Unicode data using wstring datatype
//binding the Euro symbol, UTF16 codepoint 0x20AC
wchar_t eurochars[] = {0x20AC,0x00};
wstring eurostr(eurochars);
stmt->setUString(1,eurostr);
 
//Call the Unicode version of createConnection by
//passing widechar literals
Connection *conn = env->createConnection(L"SCOTT",L"TIGER",L"");

OCCI applications should use the UString datatype for data in UTF16 characterset

Multibyte and UTF16 data

For data in multibyte charactersets like JA16SJIS and UTF8, applications should use the C++ string type. The existing OCCI APIs that take string arguments can handle data in any multibyte characterset. Due to the use of string type, OCCI supports only byte length semantics for multibyte characterset strings.

//bind UTF8 data
//binding the Euro symbol, UTF8 codepoint : 0xE282AC
char eurochars[] = {0xE2,0x82,0xAC,0x00};
string eurostr(eurochars)
stmt->setString(1,eurostr);//use the string interface

//bind Unicode data using UString datatype
//binding the Euro symbol, UTF16 codepoint 0x20AC
utext eurochars[] = {0x20AC,0x00};
UString eurostr(eurochars);
stmt->setUString(1,eurostr);//use the UString interface

CLOB and NCLOB Datatypes

Oracle provides the CLOB and NCLOB datatypes for storing and processing large amounts of character data. CLOBs represent data in the database characterset and NCLOBs represent data in the database national characterset. CLOBs and NCLOBs can be used as column types in relational tables and as attributes in object types.

The OCCI Clob class is used to work with both CLOB and NCLOB datatypes. If the database type is NCLOB, then the Clob set CharSetForm() method should be called with OCCI_SQLCS_NCHAR before reading/writing from the LOB.

The OCCI Clob class has support for multibyte and UTF16 charactersets. By default, the Clob interfaces assume the data is encoded in the client-side characterset (for both CLOBs and NCLOBs). To specify a different characterset or to specify the client-side national characterset for a NCLOB, call the setCharSetId() or setCharSetIdUString() methods with the appropriate characterset. The OCCI specific string 'OCCIUTF16' can be passed to indicate UTF16 as the characterset.

//client characterset - ZHT16BIG5, national characterset - UTF16
Environment *env = Environment::createEnvironment("ZHT16BIG5","OCCIUTF16");...
Clob nclobvar;
//for NCLOBs, need to call setCharSetForm method. 
nclobvar.setCharSetForm(OCCI_SQLCS_NCHAR);...
//if reading/writing data in UTF16 for this NCLOB, still need to 
//explicitly call setCharSetId
nclobvar.setCharSetId("OCCIUTF16")
 

To read or write data in multibyte charactersets, use the existing read and write interfaces that take a char buffer. New overloaded interfaces that take utext buffers for UTF16 data have been added to the Clob Class as read(), write() and writeChunk() methods. The arguments and return values for these methods are either bytes or characters, depending on the characterset of the LOB.