Character sets
C API

## Detailed Description

OCILIB supports both ANSI and Unicode.

Oracle started a real Unicode support with Oracle8i but only for bind and fetch data. All SQL and PL/SQ/ statements, database objects names were still only supported in ANSI.

With Oracle 9i, Oracle provides a full Unicode support.

So depending on the compile time Oracle library or the runtime loaded library, Unicode support differs.

OCILIB supports:

- ANSI (char)
- Unicode (wchar_t)
- UTF8 strings

OCILIB uses the character type 'otext' that is a define around char and wchar_t depending on the charset mode.

Option OCI_CHARSET_ANSI

- otext –> char
- OTEXT(x) –> x

Option OCI_CHARSET_WIDE

- otext –> wchar_t
- OTEXT(x) –> L ## x

Unicode and ISO C

Well, ISO C:

- doesn't know anything about Unicode.
- makes wide characters support tricky because wide character size is not defined and is freely adaptable by implementations.

OCILIB uses char/wchar_t strings for both public interface and internal storage.

Unicode builds of OCILIB initialize OCI in UTF16 Unicode mode. Oracle implements this mode with a 2 bytes (fixed length) UTF16 encoding.

Warning
  When using Unicode builds of OCILIB, make sure that the target Database charset is also using an Unicode charset or is a superset of UTF16. If not, strings may be converted with substitution characters by the Oracle client !

So, on systems implementing wchar_t as 2 bytes based UTF16 (e.g. Ms Windows), strings are directly passed to Oracle and taken back from it.

On other systems (most of the Unix systems) that use UTF32 as encoding, (4 bytes based wchar_t), OCILIB uses:

- temporary buffers for statements and object names
- buffer expansion from UTF16 to UTF32 for fetch and bind string:
  - allocation based on sizeof(wchar_t)
  - data filling based on sizeof(short) -> (UTF16 2 bytes)
  - data expansion to sizeof(wchar_t).

Buffer expansion is done in place and has the advantage of not requiring extra buffer. That reduces the cost of the Unicode/ISO C handling overhead on Unix systems.

UTF8 strings

OCILIB fully supports UTF8 strings :

- Within OCI_CHARSET_ANSI builds
- NLS_LANG environment variable must be set to any valid UTF8 Oracle charset string

Charset mapping macros

OCILIB main header file provides macro around most common string functions of the C standard library.

these macros are based on the model: ostr[libc function name]()

xxx is the standard C library string function name without the character type prefix (str/wcs).

List of available macros:

- ostrdup
- ostrcpy
- ostrncpy
- ostrcat
- ostrncat
- ostrlen
- ostrcmp
- ostrcasecmp
- osprintf
- ostol