8
OCI Programming in a Global Environment

This chapter contains information useful for OCI programming. It includes the following topics:

Using the OCI NLS Functions

Many OCI NLS functions accept either the environment handle or the user session handle. The OCI environment handle is associated with the client NLS environment and initialized with the client NLS environment variables. This environment does not change when ALTER SESSION statements are issued to the server. The character set associated with the environment handle is the client character set. The OCI session handle (returned by OCISessionBegin) is associated with the server session environment. Its NLS settings change when the session environment is modified with an ALTER SESSION statement. The character set associated with the session handle is the database character set.

Note that the OCI session handle does not have any NLS settings associated with it until the first transaction begins in the session. SELECT statements do not begin a transaction.

Specifying Character Sets in OCI

Use the OCIEnvNlsCreate function to specify client-side database and national character sets when the OCI environment is created.This function allows users to set character set information dynamically in applications, independent of the NLS_LANG and NLS_CHAR initialization parameter settings. In addition, one application can initialize several environment handles for different client environments in the same server environment.

Any Oracle character set ID except AL16UTF16 can be specified through the OCIEnvNlsCreate function to specify the encoding of metadata, SQL CHAR data, and SQL NCHAR data. Use OCI_UTF16ID in the OCIEnvNlsCreate function, introduced in Oracle 9i Release 2 (9.2), to specify UTF-16 data. Note that the OCI_UTF16 parameter in the OCIEnvCreate function, which was introduced in Oracle9i release 1 (9.0.1) and was known as Unicode mode, has been deprecated.

See Also:

Oracle Call Interface Programmer's Guide for more information about the OCIEnvNlsCreate function and the OCIEnvCreate function

OCIEnvNlsCreate()

Syntax

sword OCIEnvNlsCreate   ( OCIEnv        **envhpp,
                          ub4           mode,
                          dvoid         *ctxp,
                          dvoid         *(*malocfp)
                                             (dvoid *ctxp,
                                              size_t size),
                          dvoid         *(*ralocfp)
                                             (dvoid *ctxp,
                                              dvoid *memptr,
                                              size_t newsize),
                          void          (*mfreefp)
                                             (dvoid *ctxp,
                                              dvoid *memptr))
                          size_t        xtramemsz,
                          dvoid         **usrmempp
                          ub2           charset,
                          ub2           ncharset );

Purpose

Creates and initializes an environment handle for OCI functions to work under. It is an enhanced version of the OCIEnvCreate() function.

Parameters

envhpp (OUT)

A pointer to an environment handle whose encoding setting is specified by mode. The setting is inherited by statement handles derived from envhpp.

mode (IN)

Specifies initialization of the mode. Valid modes are:

OCI_DEFAULT: The default value, which is non-UTF-16 encoding.
OCI_THREADED: Uses threaded environment. Internal data structures not exposed to the user are protected from concurrent accesses by multiple threads.
OCI_OBJECT: Uses object features.
OCI_UTF16: The environment handle and handles inherited from it assume UTF-16 encoding. This setting is deprecated. Instead, specify OCI_UTF16ID for both charset and ncharset.
OCI_SHARED: Uses shared data structures.
OCI_EVENTS: Uses publish-subscribe notifications.
OCI_NO_UCB: Suppresses the calling of the OCIEnvCallback dynamic callback routine. The default behavior is to allow calling of OCIEnvCallback at the time that the environment is created.
OCI_ENV_NO_MUTEX: No mutexing in this mode. All OCI calls done on the environment handle, or on handles derived from the environment handle, must be serialized.

ctxp (IN)

Specifies the user-defined context for the memory callback routines.

malocfp (IN)

Specifies the user-defined memory allocation function. If the mode is OCI_THREADED, then this memory allocation routine must be thread-safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory allocation function.

size (IN)

Specifies the size of memory to be allocated by the user-defined memory allocation function.

ralocfp (IN)

Specifies the user-defined memory re-allocation function. If the mode is OCI_THREADED, then this memory allocation routine must be thread-safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory reallocation function.

memp (IN)

Pointer to memory block.

newsize (IN)

Specifies the new size of memory to be allocated

mfreefp (IN)

Specifies the user-defined memory free function. If the mode is OCI_THREADED, then this memory-free routine must be thread-safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory-free function.

memptr (IN)

Pointer to memory to be freed

xtramemsz (IN)

Specifies the amount of user memory to be allocated for the duration of the environment.

usrmempp (OUT)

Returns a pointer to the user memory of size xtramemsz allocated by the call for the user.

charset (IN)

The client-side character set for the current environment handle. If it is 0, then the NLS_LANG setting is used. OCI_UTF16ID is a valid setting. This affects metadata and CHAR data.

ncharset (IN)

The client-side national character set for the current environment handle. If it is 0, then the NLS_NCHAR setting is used. OCI_UTF16ID is a valid setting. This affects NCHAR data.

Returns

OCI_SUCCESS: The environment handle has been successfully created.

OCI_ERROR: An error occurred.

Comments

Note:

This call should be invoked before any other OCI call and should be used instead of the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls are supported for backward compatibility.

This function sets nonzero charset and ncharset as client-side database and national character sets, replacing the ones specified by NLS_LANG and NLS_NCHAR. When charset and ncharset are 0, it behaves exactly the same as OCIEnvCreate(). Specifically, charset controls the encoding for metadata and data with implicit form attribute and ncharset controls the encoding for data with SQLCS_NCHAR form attribute.

Although OCI_UTF16ID can be set by OCIEnvNlsCreate(), NLS_LANG and NLS_NCHAR cannot have a UTF-16 setting.

The character set IDs in NLS_LANG and NLS_NCHAR can be retrieved with OCINlsEnvironmentVariableGet().

This call returns an environment handle which is then used by the remaining OCI functions. There can be multiple environments in OCI, each with its own environment modes. This function also performs any process-level initialization if required by any mode. For example, if the user wants to initialize an environment as OCI_THREADED, then all libraries that are used by OCI are also initialized in the threaded mode.

If you are writing a DLL or a shared library using OCI library then this call should be used instead of OCIInitialize() and OCIEnvInit() calls.

See Also:

"OCINlsEnvironmentVariableGet()"

Getting Locale Information in OCI

An Oracle locale consists of language, territory, and character set definitions. The locale determines conventions such as day and month names, as well as date, time, number, and currency formats. A globalized application obeys a user's locale setting and cultural conventions. For example, when the locale is set to German, users expect to see day and month names in German.

You can retrieve the following information with the OCINlsGetInfo() function:

Days of the week (translated)

Abbreviated days of the week (translated)

Month names (translated)

Abbreviated month names (translated)

Yes/no (translated)

AM/PM (translated)

AD/BC (translated)

Numeric format

Debit/credit

Date format

Currency formats

Default language

Default territory

Default character set

Default linguistic sort

Default calendar

This section includes the following topics:

OCINlsGetInfo()

Syntax

sword OCINlsGetInfo(dvoid *hndl, OCIError *errhp, OraText *buf, size_t buflen, 
ub2 item)

Purpose

This function obtains locale information specified by item from an OCI environment or user session handle (hndl) into an array pointed to by buf within a size limitation specified by buflen.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR

Parameters

hndl(IN/OUT)

The OCI environment or user session handle initialized in object mode

errhp(IN/OUT)

The OCI error handle. If there is an error, then it is recorded in errhp and the function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet().

buf(OUT)

Pointer to the destination buffer. Returned strings are terminated by a NULL character.

buflen(IN)

The size of the destination buffer. The maximum length for each piece of information is OCI_NLS_MAXBUFSZ bytes

item(IN)

Specifies which item in the OCI environment handle to return. It can be one of the following values:

OCI_NLS_DAYNAME1: Native name for Monday
OCI_NLS_DAYNAME2: Native name for Tuesday
OCI_NLS_DAYNAME3: Native name for Wednesday
OCI_NLS_DAYNAME4: Native name for Thursday
OCI_NLS_DAYNAME5: Native name for Friday
OCI_NLS_DAYNAME6: Native name for Saturday
OCI_NLS_DAYNAME7: Native name for Sunday
OCI_NLS_ABDAYNAME1: Native abbreviated name for Monday
OCI_NLS_ABDAYNAME2: Native abbreviated name for Tuesday
OCI_NLS_ABDAYNAME3: Native abbreviated name for Wednesday
OCI_NLS_ABDAYNAME4: Native abbreviated name for Thursday
OCI_NLS_ABDAYNAME5: Native abbreviated name for Friday
OCI_NLS_ABDAYNAME6: Native abbreviated name for Saturday
OCI_NLS_ABDAYNAME7: Native abbreviated name for Sunday
OCI_NLS_MONTHNAME1: Native name for January
OCI_NLS_MONTHNAME2: Native name for February
OCI_NLS_MONTHNAME3: Native name for March
OCI_NLS_MONTHNAME4: Native name for April
OCI_NLS_MONTHNAME5: Native name for May
OCI_NLS_MONTHNAME6: Native name for June
OCI_NLS_MONTHNAME7: Native name for July
OCI_NLS_MONTHNAME8: Native name for August
OCI_NLS_MONTHNAME9: Native name for September
OCI_NLS_MONTHNAME10: Native name for October
OCI_NLS_MONTHNAME11: Native name for November
OCI_NLS_MONTHNAME12: Native name for December
OCI_NLS_ABMONTHNAME1: Native abbreviated name for January
OCI_NLS_ABMONTHNAME2: Native abbreviated name for February
OCI_NLS_ABMONTHNAME3: Native abbreviated name for March
OCI_NLS_ABMONTHNAME4: Native abbreviated name for April
OCI_NLS_ABMONTHNAME5: Native abbreviated name for May
OCI_NLS_ABMONTHNAME6: Native abbreviated name for June
OCI_NLS_ABMONTHNAME7: Native abbreviated name for July
OCI_NLS_ABMONTHNAME8: Native abbreviated name for August
OCI_NLS_ABMONTHNAME9: Native abbreviated name for September
OCI_NLS_ABMONTHNAME10: Native abbreviated name for October
OCI_NLS_ABMONTHNAME11: Native abbreviated name for November
OCI_NLS_ABMONTHNAME12: Native abbreviated name for December
OCI_NLS_YES: Native string for affirmative response
OCI_NLS_NO: Native negative response
OCI_NLS_AM: Native equivalent string of AM
OCI_NLS_PM: Native equivalent string of PM
OCI_NLS_AD: Native equivalent string of AD
OCI_NLS_BC: Native equivalent string of BC
OCI_NLS_DECIMAL: Decimal character
OCI_NLS_GROUP: Group separator
OCI_NLS_DEBIT: Native symbol of debit
OCI_NLS_CREDIT: Native symbol of credit
OCI_NLS_DATEFORMAT: Oracle date format
OCI_NLS_INT_CURRENCY: International currency symbol
OCI_NLS_DUAL_CURRENCY: Dual currency symbol
OCI_NLS_LOC_CURRENCY: Locale currency symbol
OCI_NLS_LANGUAGE: Language name
OCI_NLS_ABLANGUAGE: Abbreviation for language name
OCI_NLS_TERRITORY: Territory name
OCI_NLS_CHARACTER_SET: Character set name
OCI_NLS_LINGUISTIC_NAME: Linguistic sort name
OCI_NLS_CALENDAR: Calendar name
OCI_NLS_WRITING_DIR: Language writing direction
OCI_NLS_ABTERRITORY: Territory abbreviation
OCI_NLS_DDATEFORMAT: Oracle default date format
OCI_NLS_DTIMEFORMAT: Oracle default time format
OCI_NLS_SFDATEFORMAT: Local date format
OCI_NLS_SFTIMEFORMAT: Local time format
OCI_NLS_NUMGROUPING: Number grouping fields
OCI_NLS_LISTSEP: List separator
OCI_NLS_MONDECIMAL: Monetary decimal character
OCI_NLS_MONGROUP: Monetary group separator
OCI_NLS_MONGROUPING: Monetary grouping fields
OCI_NLS_INT_CURRENCYSEP: International currency separator

OCI_NLS_MAXBUFSZ

When calling OCINlsGetInfo(), you need to allocate the buffer to store the returned information. The buffer size depends on which item you are querying and what encoding you are using to store the information. Developers should not need to know how many bytes it takes to store January in Japanese using JA16SJIS encoding. The OCI_NLS_MAXBUFSZ attribute guarantees that the buffer is big enough to hold the largest item returned by OCINlsGetInfo().

Example: Getting Locale Information in OCI

This example code retrieves information and checks for errors.

sword MyPrintLinguisticName(envhp, errhp)
OCIEnv   *envhp;
OCIError *errhp;
{
  OraText  infoBuf[OCI_NLS_MAXBUFSZ];
  sword ret;
  
  ret = OCINlsGetInfo(envhp,                           /* environment handle */
                      errhp,                                 /* error handle */
                      infoBuf,                         /* destination buffer */
                      (size_t) OCI_NLS_MAXBUFSZ,              /* buffer size */
                      (ub2) OCI_NLS_LINGUISTIC_NAME);                /* item */

  if (ret != OCI_SUCCESS) 
  {
    checkerr(errhp, ret, OCI_HTYPE_ERROR);                
    ret = OCI_ERROR; 
  }
  else
  {
    printf("NLS linguistic: %s\n", infoBuf);
   }
  return(ret);
}

OCINlsCharSetNameTold()

Syntax

 ub2 OCINlsCharSetNameToId(dvoid *hndl, const oratext *name)

Purpose

This function returns the Oracle character set ID for the specified Oracle character set name.

Returns

Character set ID if the specified character set name and the OCI handle are valid. Otherwise it returns 0.

Parameters

hndl(IN/OUT)

OCI environment or session handle. If the handle is invalid, then the function returns zero.

name(IN)

Pointer to a null-terminated Oracle character set name. If the character set name is invalid, then the function returns zero.

OCINlsCharSetIdToName()

Syntax

sword OCINlsCharSetIdToName( dvoid *hndl, oratext *buf, size_t buflen, ub2 id)

Purpose

This function returns the Oracle character set name from the specified character set ID.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR

Parameters

hndl(IN/OUT)

OCI environment or session handle. If the handle is invalid, then the function returns OCI_INVALID_HANDLE.

buf(OUT)

Points to the destination buffer. If the function returns OCI_SUCCESS, then the parameter contains a null-terminated string for the character set name.

buflen(IN)

The size of the destination buffer. The recommended size is OCI_NLS_MAXBUFSZ to guarantee storage for an Oracle character set name. If the size of the destination buffer is smaller than the length of the character set name, the function returns OCI_ERROR.

id(IN)

Oracle character set ID

OCINlsNumericInfoGet()

Syntax

sword OCINlsNumericInfoGet( dvoid *hndl, OCIError *errhp, sb4 *val, ub2 item)

Purpose

This function obtains numeric language information specified by item from the OCI environment handle into an output number variable.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR

Parameters

hndl(IN/OUT)

OCI environment or session handle. If the handle is invalid, then the function returns OCI_INVALID_HANDLE.

errhp(IN/OUT)

The OCI error handle. If there is an error, then it is recorded in errhp and the function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet().

val(OUT)

Pointer to the output number variable. If the function returns OCI_SUCCESS, then the parameter contains the requested NLS numeric information.

item(IN)

It specifies which item to get from the OCI environment handle and can be one of following values:

OCI_NLS_CHARSET_MAXBYTESZ: Maximum character byte size for OCI environment or session handle character set
OCI_NLS_CHARSET_FIXEDWIDTH: Character byte size for fixed-width character set; 0 for variable-width character set

OCINlsEnvironmentVariableGet()

Purpose

Returns the character set ID from NLS_LANG or the national character set id from NLS_NCHAR.

Syntax

sword OCINlsEnvironmentVariableGet ( dvoid     *val,
                                     size_t    size,
                                     ub2       item,
                                     ub2 charset, 
                                     size_t    *rsize );

Parameters

val (IN/OUT)

Returns a value of an NLS environment variable such as the NLS_LANG character set ID or the NLS_NCHAR character set ID

size (IN)

Specifies the size of the given output value, which is applicable only to string data. The maximum length for each piece of information is OCI_NLS_MAXBUFSZ bytes. In the case of numeric data, this argument is ignored.

item (IN)

Specifies one of the following values to get from the NLS environment variable:

OCI_NLS_CHARSET_ID: NLS_LANG character set ID in ub2 datatype
OCI_NLS_NCHARSET_ID: NLS_NCHAR character set ID in ub2 datatype

charset (IN)

Specifies the character set ID for retrieved string data. If it is 0, then the NLS_LANG value is used. OCI_UTF16ID is a valid value for this argument. In the case of numeric data, this argument is ignored.

rsize (OUT)

The length of the return value in bytes

Returns

OCI_SUCCESS: The function finished successfully.

OCI_ERROR: An error occurred.

Comments

Following NLS convention, the national character set ID is the same as the character set ID if NLS_NCHAR is not set. If NLS_LANG is not set, tn the default character set ID is returned.

To allow for future enhancements of this function (to retrieve other values from environment variables) the datatype of the output val is a pointer to dvoid. String data is not terminated by NULL.

Note that the function does not take an environment handle, so the character set ID and the national character set ID that it returns are the values specified in NLS_LANG and NLS_NCHAR, instead of the values saved in the OCI environment handle. To get the character set IDs used by the OCI environment handle, call OCIAttrGet() for OCI_ATTR_ENV_CHARSET and OCI_ATTR_ENV_NCHARSET.

Mapping Locale Information Between Oracle and Other Standards

The OCINlsNameMap function maps Oracle character set names, language names, and territory names to and from Internet Assigned Numbers Authority (IANA) and International Organization for Standardization (ISO) names.

OCINlsNameMap()

Syntax

sword OCINlsNameMap( dvoid *hndl, oratext *buf, size_t buflen, const oratext 
*srcbuf, uword flag)

Purpose

This function maps Oracle character set names, language names, and territory names to and from IANA and ISO names.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR

Parameters

hndl(IN/OUT)

OCI environment or session handle. If the handle is invalid, then the function returns OCI_INVALID_HANDLE.

buf(OUT)

Points to the destination buffer. If the function returns OCI_SUCCESS, then the parameter contains a null-terminated string for the requested name.

buflen(IN)

The size of the destination buffer. The recommended size is OCI_NLS_MAXBUFSZ to guarantee storage of an NLS name. If the size of the destination buffer is smaller than the length of the name, then the function returns OCI_ERROR.

srcbuf(IN)

Pointer to a null-terminated NLS name. If it is not a valid name, then the function returns OCI_ERROR.

flag(IN)

It specifies the direction of the name mapping and can take the following values:

OCI_NLS_CS_IANA_TO_ORA: Map character set name from IANA to Oracle
OCI_NLS_CS_ORA_TO_IANA: Map character set name from Oracle to IANA.
OCI_NLS_LANG_ISO_TO_ORA: Map language name from ISO to Oracle
OCI_NLS_LANG_ORA_TO_ISO: Map language name from Oracle to ISO
OCI_NLS_TERR_ISO_TO_ORA: Map territory name from ISO to Oracle
OCI_NLS_TERR_ORA_TO_ISO: Map territory name from Oracle to ISO
OCI_NLS_TERR_ISO3_TO_ORA: Map territory name from 3-letter ISO abbreviation to Oracle
OCI_NLS_TERR_ORA_TO_ISO3: Map territory name from Oracle to 3-letter ISO abbreviation

Manipulating Strings in OCI

Two types of data structures are supported for string manipulation:

Multibyte strings
Wide character strings

Multibyte strings are encoded in native Oracle character sets. Functions that operate on multibyte strings take the string as a whole unit with the length of the string calculated in bytes. Wide character (wchar) string functions provide more flexibility in string manipulation. They support character-based and string-based operations with the length the string calculated in characters.

The wide character datatype is Oracle-specific and should not be confused with the wchar_t datatype defined by the ANSI/ISO C standard. The Oracle wide character datatype is always 4 bytes in all platforms, while the size of wchar_t depends on the implementation and the platform. The Oracle wide character datatype normalizes multibyte characters so that they have a fixed width for easy processing. This guarantees no data loss for round-trip conversion between the Oracle wide character set and the native character set.

String manipulation can be classified into the following categories:

Conversion of strings between multibyte and wide character
Character classifications
Case conversion
Calculations of display length
General string manipulation, such as comparison, concatenation, and searching

Table 8-1 summarizes the OCI string manipulation functions. They are described in more detail in the rest of this section.

Table 8-1 OCI String Manipulation Functions

Function	Description
`OCIMultiByteToWideChar()`	Converts an entire null-terminated string into the `wchar` format
`OCIMultiByteInSizeToWideChar()`	Converts part of a string into the `wchar` format
`OCIWideCharToMultiByte()`	Converts an entire null-terminated wide character string into a multibyte string
`OCIWideCharInSizeToMultiByte()`	Converts part of a wide character string into the multibyte format
`OCIWideCharToLower()`	Converts the `wchar` character specified by `wc` into the corresponding lowercase character if it exists in the specified locale. If no corresponding lowercase character exists, then it returns `wc` itself.
`OCIWideCharToUpper()`	Converts the `wchar` character specified by `wc` into the corresponding uppercase character if it exists in the specified locale. If no corresponding uppercase character exists, then it returns `wc` itself.
`OCIWideCharStrcmp()`	Compares two wide character strings by binary, linguistic, or case-insensitive comparison method
`OCIWideCharStrncmp()`	Similar to `OCIWideCharStrcmp()`. Compares two wide character strings by binary, linguistic, or case-insensitive comparison methods. At most `len1` bytes form `str1`, and `len2` bytes form `str2`.
`OCIWideCharStrcat()`	Appends a copy of the string pointed to by `wsrcstr`. Then it returns the number of characters in the resulting string.
`OCIWideCharStrncat()`	Appends a copy of the string pointed to by `wsrcstr`. Then it returns the number of characters in the resulting string. At most `n` characters are appended.
`OCIWideCharStrchr()`	Searches for the first occurrence of `wc` in the string pointed to by `wstr`. Then it returns a pointer to the `wchar` if the search is successful.
`OCIWideCharStrrchr()`	Searches for the last occurrence of `wc` in the string pointed to by `wstr`
`OCIWideCharStrcpy()`	Copies the `wchar` string pointed to by `wsrcstr` into the array pointed to by `wdststr`. Then it returns the number of characters copied.
`OCIWideCharStrncpy()`	Copies the `wchar` string pointed to by `wsrcstr` into the array pointed to by `wdststr`. Then it returns the number of characters copied. At most `n` characters are copied from the array.
`OCIWideCharStrlen()`	Computes the number of characters in the `wchar` string pointed to by `wstr` and returns this number
`OCIWideCharStrCaseConversion()`	Converts the wide character string pointed to by `wsrcstr` into the case specified by a flag and copies the result into the array pointed to by `wdststr`
`OCIWideCharDisplayLength()`	Determines the number of column positions required for `wc` in display
`OCIWideCharMultibyteLength()`	Determines the number of bytes required for `wc` in multibyte encoding
`OCIMultiByteStrcmp()`	Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods
`OCIMultiByteStrncmp()`	Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. At most `len1` bytes form `str1` and `len2` bytes form `str2.`
`OCIMultiByteStrcat()`	Appends a copy of the multibyte string pointed to by `srcstr`
`OCIMultiByteStrncat()`	Appends a copy of the multibyte string pointed to by `srcstr`. At most `n` bytes from `srcstr` are appended to `dststr`
`OCIMultiByteStrcpy()`	Copies the multibyte string pointed to by `srcstr` into an array pointed to by `dststr`. It returns the number of bytes copied.
`OCIMultiByteStrncpy()`	Copies the multibyte string pointed to by `srcstr` into an array pointed to by `dststr`. It returns the number of bytes copied. At most `n` bytes are copied from the array pointed to by `srcstr` to the array pointed to by `dststr`.
`OCIMultiByteStrlen()`	Returns the number of bytes in the multibyte string pointed to by `str`
`OCIMultiByteStrnDisplayLength()`	Returns the number of display positions occupied by the complete characters within the range of `n` bytes
`OCIMultiByteStrCaseConversion()`	Converts part of a string from one character set to another

OCIMultiByteToWideChar()

Syntax

sword OCIMultiByteToWideChar(dvoid *hndl, OCIWchar *dst, CONST OraText *src, 
size_t *rsize);

Purpose

This routine converts an entire NULL-terminated string into the wchar format. The wchar output buffer are NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set of string

dst(OUT)

Destination buffer for wchar

src(IN)

Source string to be converted

rsize(OUT)

Number of characters converted including NULL terminator. If it is a NULL pointer, nothing to return

OCIMultiByteInSizeToWideChar()

Syntax

sword OCIMultiByteInSizeToWideChar(dvoid *hndl, OCIWchar *dst, size_t dstsz, 
CONST OraText *src, size_t srcsz, size_t *rsize)

Purpose

This routine converts part of a string into the wchar format. It converts as many complete characters as it can until it reaches the output buffer size limit or input buffer size limit or it reaches a NULL terminator in a source string. The output buffer is NULL-terminated if space permits. If dstsz is zero, then this function returns only the number of characters not including the ending NULL terminator needed for a converted string. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set of the string

dst(OUT)

Pointer to a destination buffer for wchar. It can be NULL pointer when dstsz is zero.

dstsz(IN)

Destination buffer size in number of characters. If it is zero, this function just returns number of characters needed for the conversion.

src (IN)

Source string to be converted

srcsz(IN)

Length of source string in bytes

rsize(OUT)

Number of characters written into destination buffer, or number of characters for converted string if dstsz is zero. If it is a NULL pointer, nothing is returned.

OCIWideCharToMultiByte()

Syntax

sword OCIWideCharToMultiByte(dvoid *hndl, OraText *dst, CONST OCIWchar *src, 
size_t *rsize)

Purpose

This routine converts an entire NULL-terminated wide character string into a multibyte string. The output buffer is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set of string

dst(OUT)

Destination buffer for multibyte string

src(IN)

Source wchar string to be converted

srcsz(IN)

Length of source string in characters

rsize(OUT)

Number of bytes written into destination buffer. If it is a NULL pointer, then nothing is returned.

OCIWideCharInSizeToMultiByte()

Syntax

sword OCIWideCharInSizeToMultiByte(dvoid *hndl, OraText *dst, size_t dstsz, 
CONST OCIWchar *src, size_t srcsz, size_t *rsize)

Purpose

This routine converts part of wchar string into the multibyte format. It converts as many complete characters as it can until it reaches the output buffer size or the input buffer size or until it reaches a NULL terminator in source string. The output buffer is NULL-terminated if space permits. If dstsz is zero, the function just returns the size of byte not including the NULL terminator needed to store the converted string. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set of string

dst(OUT)

Destination buffer for multibyte. It can be a NULL pointer if dstsz is zero

dstsz(IN)

Destination buffer size in bytes. If it is zero, it returns the size in bytes need for converted string.

src(IN)

Source wchar string to be converted

srcsz(IN)

Length of source string in characters

rsize(OUT)

Number of bytes written into destination buffer, or number of bytes need to store the converted string if dstsz is zero. If it is a NULL pointer, nothing is returned.

OCIWideCharToLower()

Syntax

OCIWchar OCIWideCharToLower(dvoid *hndl, OCIWchar wc)

Purpose

This function converts the wchar character specified by wc into the corresponding lowercase character if it exists in the specified locale. If no corresponding lowercase character exists, then it returns wc itself. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

A wchar

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for lowercase conversion

OCIWideCharToUpper()

Syntax

OCIWchar OCIWideCharToUpper(dvoid *hndl, OCIWchar wc)

Purpose

This function converts the wchar character specified by wc into the corresponding uppercase character if it exists in the specified locale. If no corresponding uppercase character exists, then it returns wc itself. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces an error.

Returns

A wchar

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for uppercase conversion

OCIWideCharStrcmp()

Syntax

int OCIWideCharStrcmp(dvoid *hndl, CONST OCIWchar *wstr1, CONST OCIWchar *wstr2, 
int flag)

Purpose

It compares two wchar strings by binary (based on wchar encoding value), linguistic, or case-insensitive comparison methods. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

0, if wstr1 = wstr2
Positive, if wstr1 > wstr2
Negative, if wstr1 < wstr2

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wstr1(IN)

Pointer to a NULL-terminated wchar string

wstr2(IN)

Pointer to a NULL-terminated wchar string

flag(IN)

Used to decide the comparison method. It can take one of the following values:

OCI_NLS_BINARY: Binary comparison. This is the default value.
OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale definition.

This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison. For example, use OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings linguistically without regard to case.

OCIWideCharStrncmp()

Syntax

int OCIWideCharStrncmp(dvoid *hndl, CONST OCIWchar *wstr1, size_t len1, CONST 
OCIWchar *wstr2, size_t len2, int flag)

Purpose

This function is similar to OCIWideCharStrcmp(). It compares two wide character strings by binary, linguistic, or case-insensitive comparison methods. At most len1 bytes from wstr1 and len2 bytes from wstr2 are compared. The NULL terminator is used in the comparison. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

0, if wstr1 = wstr2
Positive, if wstr1 > wstr2
Negative, if wstr1 < wstr2

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wstr1(IN)

Pointer to the first wchar string

len1(IN)

The length for the first string for comparison

wstr2(IN)

Pointer to the second wchar string

len2(IN)

The length for the second string for comparison

flag(IN)

It is used to decide the comparison method. It can take one of the following values:

OCI_NLS_BINARY: For the binary comparison, this is default value.
OCI_NLS_LINGUISTIC: For the linguistic comparison specified in the locale.

OCIWideCharStrcat()

Syntax

size_t OCIWideCharStrcat(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar 
*wsrcstr)

Purpose

This function appends a copy of the wchar string pointed to by wsrcstr, including the NULL terminator to the wchar string pointed to by wdststr. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of characters in the result string, not including the NULL terminator.

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wdststr(IN/OUT)

Pointer to the destination wchar string for appending

wsrcstr(IN)

Pointer to the source wchar string to append

OCIWideCharStrncat()

Syntax

size_t OCIWideCharStrncat(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar 
*wsrcstr, size_t n)

Purpose

This function is similar to OCIWideCharStrcat(). At most n characters from wsrcstr are appended to wdststr. Note that the NULL terminator in wsrcstr stops appending. wdststr is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of characters in the result string, not including the NULL terminator

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wdststr(IN/OUT)

Pointer to the destination wchar string to append

wsrcstr(IN)

Pointer to the source wchar string to append

n(IN)

Number of characters from wsrcstr to append

OCIWideCharStrchr()

Syntax

OCIWchar *OCIWideCharStrchr(dvoid *hndl, CONST OCIWchar *wstr, OCIWchar wc)

Purpose

This function searches for the first occurrence of wc in the wchar string pointed to by wstr. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

A wchar pointer if successful, otherwise a NULL pointer

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wstr(IN)

Pointer to the wchar string to search

wc(IN)

wchar to search for

OCIWideCharStrrchr()

Syntax

OCIWchar *OCIWideCharStrrchr(dvoid *hndl, CONST OCIWchar *wstr, OCIWchar wc)

Purpose

This function searches for the last occurrence of wc in the wchar string pointed to by wstr. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

wchar pointer if successful, otherwise a NULL pointer

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wstr(IN)

Pointer to the wchar string to search

wc(IN)

wchar to search for

OCIWideCharStrcpy()

Syntax

size_t OCIWideCharStrcpy(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar 
*wsrcstr)

Purpose

This function copies the wchar string pointed to by wsrcstr, including the NULL terminator, into the array pointed to by wdststr. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of characters copied not including the NULL terminator

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wdststr(OUT)

Pointer to the destination wchar buffer

wsrcstr(IN)

Pointer to the source wchar string

OCIWideCharStrncpy()

Syntax

size_t OCIWideCharStrncpy(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar 
*wsrcstr, size_t n)

Purpose

This function is similar to OCIWideCharStrcpy(), except that at most n characters are copied from the array pointed to by wsrcstr to the array pointed to by wdststr. Note that the NULL terminator in wdststr stops copying and the result string is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of characters copied not including the NULL terminator

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wdststr(OUT)

Pointer to the destination wchar buffer

wsrcstr(IN)

Pointer to the source wchar string

n(IN)

Number of characters from wsrcstr to copy

OCIWideCharStrlen()

Syntax

size_t OCIWideCharStrlen(dvoid *hndl, CONST OCIWchar *wstr)

Purpose

This function computes the number of characters in the wchar string pointed to by wstr, not including the NULL terminator, and returns this number. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of characters not including the NULL terminator

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wstr(IN)

Pointer to the source wchar string

OCIWideCharStrCaseConversion()

Syntax

size_t OCIWideCharStrCaseConversion(dvoid *hndl, OCIWchar *wdststr, CONST 
OCIWchar*wsrcstr, ub4 flag)

Purpose

This function converts the wide char string pointed to by wsrcstr into the upper case or lower case specified by the flag and copies the result into the array pointed to by wdststr. The result string is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of characters for the result string, not including the NULL terminator

Parameters

hndl(IN/OUT)

OCI environment or user session handle

wdststr(OUT)

Pointer to destination array

wsrcstr(IN)

Pointer to source string

flag(IN)

Specify the case to convert:

OCI_NLS_UPPERCASE: Convert to upper case
OCI_NLS_LOWERCASE: Convert to lower case

This flag can be used with OCI_NLS_LINGUISTIC to specify that the linguistic setting in the locale is used for case conversion.

OCIWideCharDisplayLength()

Syntax

size_t OCIWideCharDisplayLength(dvoid *hndl, OCIWchar wc)

Purpose

This function determines the number of column positions required for wc in display. It returns the number of column positions, or 0 if wc is the NULL terminator. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of display positions

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar character

OCIWideCharMultiByteLength()

Syntax

size_t OCIWideCharMultiByteLen(dvoid *hndl, OCIWchar wc)

Purpose

This function determines the number of bytes required for wc in multibyte encoding. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of bytes required for wc

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar character

OCIMultiByteStrcmp()

Syntax

int OCIMultiByteStrcmp(dvoid *hndl, CONST OraText *str1, CONST OraText *str2, 
int flag)

Purpose

It compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

0, if str1 = str2
Positive, if str1 > str2
Negative, if str1 < str2

Parameters

hndl(IN/OUT)

OCI environment or user session handle

str1(IN)

Pointer to a NULL-terminated string

str2(IN)

Pointer to a NULL-terminated string

flag(IN)

It is used to decide the comparison method. It can take one of the following values:

OCI_NLS_BINARY: Binary comparison This is the default value.
OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale

OCIMultiByteStrncmp()

Syntax

int OCIMultiByteStrncmp(dvoid *hndl, CONST OraText *str1, size_t len1, OraText 
*str2, size_t len2, int flag)

Purpose

This function is similar to OCIMultiByteStrcmp(), except that at most len1 bytes from str1 and len2 bytes from str2 are compared. The NULL terminator is used in the comparison. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

0, if str1 = str2
Positive, if str1 > str2
Negative, if str1 < str2

Parameters

hndl(IN/OUT)

OCI environment or user session handle

str1(IN)

Pointer to the first string

len1(IN)

The length for the first string for comparison

str2(IN)

Pointer to the second string

len2(IN)

The length for the second string for comparison

flag(IN)

It is used to decide the comparison method. It can take one of the following values:

OCI_NLS_BINARY: Binary comparison. This is the default value.
OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale

OCIMultiByteStrcat()

Syntax

size_t OCIMultiByteStrcat(dvoid *hndl, OraText *dststr, CONST OraText *srcstr)

Purpose

This function appends a copy of the multibyte string pointed to by srcstr, including the NULL terminator to the end of string pointed to by dststr. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of bytes in the result string, not including the NULL terminator

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

dststr(IN/OUT)

Pointer to the destination multibyte string for appending

srcstr(IN)

Pointer to the source string to append

OCIMultiByteStrncat()

Syntax

size_t OCIMultiByteStrncat(dvoid *hndl, OraText *dststr, CONST OraText *srcstr, 
size_t n)

Purpose

This function is similar to OCIMultiByteStrcat(). At most n bytes from srcstr are appended to dststr. Note that the NULL terminator in srcstr stops appending and the function appends as many character as possible within n bytes. dststr is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of bytes in the result string, not including the NULL terminator

Parameters

hndl(IN/OUT)

Pointer to OCI environment or user session handle

dststr(IN/OUT)

Pointer to the destination multibyte string for appending

srcstr(IN)

Pointer to the source multibyte string to append

n(IN)

The number of bytes from srcstr to append

OCIMultiByteStrcpy()

Syntax

size_t OCIMultiByteStrcpy(dvoid *hndl, OraText *dststr, CONST OraText *srcstr)

Purpose

This function copies the multibyte string pointed to by srcstr, including the NULL terminator, into the array pointed to by dststr. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of bytes copied, not including the NULL terminator

Parameters

hndl(IN/OUT)

Pointer to the OCI environment or user session handle

dststr(OUT)

Pointer to the destination buffer

srcstr(IN)

Pointer to the source multibyte string

OCIMultiByteStrncpy()

Syntax

size_t OCIMultiByteStrncpy(dvoid *hndl, OraText *dststr, CONST OraText *srcstr, 
size_t n)

Purpose

This function is similar to OCIMultiByteStrcpy(). At most n bytes are copied from the array pointed to by srcstr to the array pointed to by dststr. Note that the NULL terminator in srcstr stops copying and the function copies as many characters as possible within n bytes. The result string is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of bytes copied not including the NULL terminator

Parameters

hndl(IN/OUT)

Pointer to OCI environment or user session handle

srcstr(OUT)

Pointer to the destination buffer

dststr(IN)

Pointer to the source multibyte string

n(IN)

The number of bytes from srcstr to copy

OCIMultiByteStrlen()

Syntax

size_t OCIMultiByteStrlen(dvoid *hndl, CONST OraText *str)

Purpose

This function returns the number of bytes in the multibyte string pointed to by str, not including the NULL terminator. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of bytes not including the NULL terminator

Parameters

hndl(IN/OUT)

Pointer to the OCI environment or user session handle

str(IN)

Pointer to the source multibyte string

OCIMultiByteStrnDisplayLength()

Syntax

size_t OCIMultiByteStrnDisplayLength(dvoid *hndl, CONST OraText *str1, size_t n)

Purpose

This function returns the number of display positions occupied by the complete characters within the range of n bytes. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of display positions

Parameters

hndl(IN/OUT)

OCI environment or user session handle

str(IN)

Pointer to a multibyte string

n(IN)

The number of bytes to examine

OCIMultiByteStrCaseConversion()

Syntax

size_t OCIMultiByteStrCaseConversion(dvoid *hndl, OraText *dststr, CONST OraText 
*srcstr, ub4 flag)

Purpose

This function converts the multibyte string pointed to by srcstr into upper case or lower case as specified by the flag and copies the result into the array pointed to by dststr. The result string is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

The number of bytes for result string, not including the NULL terminator

Parameters

hndl(IN/OUT)

OCI environment or user session handle

dststr(OUT)

Pointer to destination array

srcstr(IN)

Pointer to source string

flag(IN)

Specify the case to which to convert:

OCI_NLS_UPPERCASE: Convert to upper case
OCI_NLS_LOWERCASE: Convert to lower case

This flag can be used with OCI_NLS_LINGUISTIC to specify that the linguistic setting in the locale is used for case conversion.

Example: Manipulating Strings in OCI

The following example shows a simple case of manipulating strings.

size_t MyConvertMultiByteToWideChar(envhp, dstBuf, dstSize, srcStr)
OCIEnv     *envhp;
OCIWchar   *dstBuf;
size_t      dstSize;
OraText       *srcStr;                         /* null terminated source string 
*/
{
  sword  ret;
  size_t dstLen = 0;
  size_t srcLen;

  /* get length of source string */
  srcLen = OCIMultiByteStrlen(envhp, srcStr);
  
  ret = OCIMultiByteInSizeToWideChar(envhp,       /* environment handle */
                 dstBuf,                               /* destination buffer */
                 dstSize,                         /* destination buffer size */
                 srcStr,                                    /* source string */
                 srcLen,                          /* length of source string */
                 &dstLen);                  /* pointer to destination length */

  if (ret != OCI_SUCCESS)                                          
  {
    checkerr(envhp, ret, OCI_HTYPE_ENV);                 
  }
  return(dstLen);
}

Classifying Characters in OCI

Table 8-2 shows the OCI character classification functions. They are described in more detail in the rest of this section.

Table 8-2 OCI Character Classification Functions

Function	Description
`OCIWideCharIsAlnum()`	Tests whether the wide character is a letter or decimal digit
`OCIWideCharIsAlpha()`	Tests whether the wide character is an alphabetic letter
`OCIWideCharIsCntrl()`	Tests whether the wide character is a control character
`OCIWideCharIsDigit()`	Tests whether the wide character is a decimal digital character
`OCIWideCharIsGraph()`	Tests whether the wide character is a graph character
`OCIWideCharIsLower()`	Tests whether the wide character is a lowercase letter
`OCIWideCharIsPrint()`	Tests whether the wide character is a printable character
`OCIWideCharIsPunct()`	Tests whether the wide character is a punctuation character
`OCIWideCharIsSpace()`	Tests whether the wide character is a space character
`OCIWideCharIsUpper()`	Tests whether the wide character is an uppercase character
`OCIWideCharIsXdigit()`	Tests whether the wide character is a hexadecimal digit
`OCIWideCharIsSingleByte()`	Tests whether `wc` is a single-byte character when converted into multibyte

OCIWideCharIsAlnum()

Syntax

boolean OCIWideCharIsAlnum(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a letter or decimal digit.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsAlpha()

Syntax

boolean OCIWideCharIsAlpha(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is an alphabetic letter.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsCntrl()

Syntax

boolean OCIWideCharIsCntrl(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a control character.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsDigit()

Syntax

boolean OCIWideCharIsDigit(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a decimal digit character.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsGraph()

Syntax

boolean OCIWideCharIsGraph(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a graph character. A graph character is a character with a visible representation and normally includes alphabetic letters, decimal digits, and punctuation.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsLower()

Syntax

boolean OCIWideCharIsLower(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a lowercase letter.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsPrint()

Syntax

boolean OCIWideCharIsPrint(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a printable character.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsPunct()

Syntax

boolean OCIWideCharIsPunct(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a punctuation character.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsSpace()

Syntax

boolean OCIWideCharIsSpace(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a space character. A space character causes white space only in displayed text (for example, space, tab, carriage return, new line, vertical tab or form feed).

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsUpper()

Syntax

boolean OCIWideCharIsUpper(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is an uppercase letter.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsXdigit()

Syntax

boolean OCIWideCharIsXdigit(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a hexadecimal digit (0-9, A-F, a-f).

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

OCIWideCharIsSingleByte()

Syntax

boolean OCIWideCharIsSingleByte(dvoid *hndl, OCIWchar wc)

Purpose

It tests whether wc is a single-byte character when converted into multibyte.

Returns

TRUE or FALSE

Parameters

hndl(IN/OUT)

OCI environment or user session handle to determine the character set

wc(IN)

wchar for testing

Example: Classifying Characters in OCI

The following example shows how to classify characters in OCI.

boolean MyIsNumberWideCharString(envhp, srcStr)
OCIEnv   *envhp;
OCIWchar *srcStr;                                 /* wide char source string */
{
  OCIWchar *pstr = srcStr;                        /* define and init pointer */
  boolean status = TRUE;            /* define and initialize status variable */

  /* Check input */
  if (pstr == (OCIWchar*) NULL)
    return(FALSE);


  if (*pstr == (OCIWchar) NULL)
    return(FALSE);

                                            /* check each character for digit */
  do 
  {
    if (OCIWideCharIsDigit(envhp, *pstr) != TRUE)
    {
      status = FALSE;
      break;                                  /* non-decimal digit character */
    }
  } while ( *++pstr != (OCIWchar) NULL);

  return(status);
}

Converting Character Sets in OCI

Conversion between Oracle character sets and Unicode (16-bit, fixed-width Unicode encoding) is supported. Replacement characters are used if a character has no mapping from Unicode to the Oracle character set. Therefore, conversion back to the original character set is not always possible without data loss.

Table 8-3 summarizes the OCI character set conversion functions. They are described in more detail in the rest of this section.

Table 8-3 OCI Character Set Conversion Functions

Function	Description
`OCICharsetToUnicode()`	Converts a multibyte string pointed to by `src` to Unicode into the array pointed to by `dst`
`OCIUnicodeToCharset()`	Converts a Unicode string pointed to by `src` to multibyte into the array pointed to by `dst`
OCINlsCharSetConvert()	Converts a string from one character set to another
`OCICharSetConversionIsReplacementUsed()`	Indicates whether replacement characters were used for characters that could not be converted in the last invocation of `OCINlsCharsetConvert()` or `OCICharSetToUnicode()`

OCICharSetToUnicode()

Syntax

sword OCICharSetToUnicode(dvoid *hndl, ub2 *dst, size_t dstlen, CONST OraText 
*src, size_t srclen, size_t *rsize)

Purpose

This function converts a multibyte string pointed to by src to Unicode into the array pointed to by dst. The conversion stops when it reaches the source limitation or destination limitation. The function returns the number of characters converted into a Unicode string. If dstlen is 0, then the function scans the string, counts the number of characters, and returns the number of characters into rsize, but does not convert the string.

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR

Parameters

hndl(IN/OUT)

Pointer to an OCI environment or user session handle

dst(OUT)

Pointer to a destination buffer

dstlen(IN)

The size of the destination buffer in characters

src(IN)

Pointer to a multibyte source string

srclen(IN)

The size of the source string in bytes

rsize(OUT)

The number of characters converted. If it is a NULL pointer, then nothing is returned.

OCIUnicodeToCharSet()

Syntax

sword OCIUnicodeToCharSet(dvoid *hndl, OraText *dst, size_t dstlen, CONST ub2 
*src, size_t srclen, size_t *rsize)

Purpose

This function converts a Unicode string pointed to by src to a multibyte string into the array pointed to by dst. The conversion stops when it reaches the source limitation or destination limitation. The function returns the number of bytes converted into a multibyte string. If dstlen is zero, it returns the number of bytes into rsize without conversion.

If a Unicode character is not convertible for the character set specified in OCI environment or user session handle, a replacement character is used for it. In this case, OCICharsetConversionIsReplacementUsed() returns TRUE.

If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate function, then this function produces an error.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR

Parameters

hndl(IN/OUT)

Pointer to an OCI environment or user session handle

dst(OUT)

Pointer to a destination buffer

dstlen(IN)

The size of destination buffer in bytes

src(IN)

Pointer to a Unicode string

srclen(IN)

The size of the source string in characters

rsize(OUT)

The number of bytes converted. If it is a NULL pointer, nothing is returned.

OCINlsCharSetConvert()

Syntax

sword OCINlsCharSetConvert(dvoid *envhp, OCIError *errhp,ub2 dstid, dvoid *dstp, 
size_t dstlen,ub2 srcid, CONST dvoid *srcp, size_tsrclen, size_t *rsize);

Purpose

This function converts a string pointed to by src in the character set specified by srcid to the array pointed to by dst in the character set specified by dstid. The conversion stops when it reaches the data size limitation of either the source or the destination. The function returns the number of bytes converted into the destination buffer. Although either the source or the destination character set ID can be specified as OCI_UTF16ID, the length of the original and the converted data is represented in bytes, rather than number of characters. Note that the conversion does not stop when it encounters null data. To get the character set ID from the character set name, use OCINlsCharSetNameToId(). To check if derived data in the destination buffer contains replacement characters, use OCICharSetConversionIsReplacementUsed(). The buffers should be aligned with the byte boundaries appropriate for the character sets. For example, the ub2 datatype should be used to hold strings in UTF-16.

Returns

OCI_SUCCESS or OCI_ERROR; number of bytes converted

Parameters

errhp(IN/OUT)

OCI error handle. If there is an error, it is recorded in errhp and the function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet().

dstid(IN)

Character set ID for the destination buffer

dstp(OUT)

Pointer to the destination buffer

dstlen(IN)

The maximum size in bytes of the destination buffer

srcid(IN)

Character set ID for the source buffer

srcp(IN)

Pointer to the source buffer

srclen(IN)

The length in bytes of the source buffer

rsize(OUT)

The number of characters converted. If the pointer is NULL, then nothing is returned.

OCICharSetConversionIsReplacementUsed()

Syntax

boolean OCICharSetConversionIsReplacementUsed(dvoid *hndl)

Purpose

This function indicates whether the replacement character was used for characters that could not be converted during the last invocation of OCICharSetToUnicode() or OCICharSetConvert().

Returns

The function returns TRUE if the replacement character was used when OCICharSetConvert() or OCICharSetToUnicode() was last invoked. Otherwise the function returns FALSE.

Parameter

hndl(IN/OUT)

Pointer to an OCI environment or user session handle

Conversion between the Oracle character set and Unicode (16-bit, fixed-width Unicode encoding) is supported. Replacement characters are used if there is no mapping for a character from Unicode to the Oracle character set. Thus, not every character can make a round-trip conversion to the original character. Data loss occurs with certain characters.

Example: Converting Character Sets in OCI

The following example shows a simple conversion into Unicode.

size_t MyConvertMultiByteToUnicode(envhp, dstBuf, dstSize, srcStr)
OCIEnv *envhp;
ub2    *dstBuf;
size_t  dstSize;
OraText   *srcStr;
{
  sword  ret;
  size_t dstLen = 0;
  size_t srcLen;

  /* get length of source string */
  srcLen = OCIMultiByteStrlen(envhp, srcStr);


  ret = OCICharSetToUnicode(envhp,                     /* environment handle */
                 dstBuf,                               /* destination buffer */
                 dstSize,                      /* size of destination buffer */
                 srcStr,                                    /* source string */
                 srcLen,                          /* length of source string */
                 &dstLen);                  /* pointer to destination length */

  if (ret != OCI_SUCCESS)
  {
    checkerr(envhp, ret, OCI_HTYPE_ENV);
  }
  return(dstLen);
}

OCI Messaging Functions

The user message API provides a simple interface for cartridge developers to retrieve their own messages as well as Oracle messages.

Table 8-4 summarizes the OCI messaging functions.

Table 8-4 OCI Messaging Functions

Function	Description
`OCIMessageOpen()`	Opens a message handle in a language pointed to by `hndl`
`OCIMessageGet()`	Retrieves a message with message number identified by `msgno`. If the buffer is not zero, then the function copies the message into the buffer pointed to by `msgbuf`.
`OCIMessageClose()`	Closes a message handle pointed to by `msgh` and frees any memory associated with this handle

This section contains the following topics:

OCIMessageOpen()

Syntax

sword OCIMessageOpen(dvoid *hndl, OCIError *errhp, OCIMsg **msghp, CONST OraText 
*product, CONST OraText *facility, OCIDuration dur)

Purpose

This function opens a message-handling facility in a language pointed to by hndl. It first tries to open the message file corresponding to hndl. If it succeeds, then it uses that file to initialize a message handle. If it cannot find the message file that corresponds to the language, it looks for a primary language file as a fallback. For example, if the Latin American Spanish file is not found, then it tries to open the Spanish file. If the fallback fails, then it uses the default message file, whose language is AMERICAN. The function returns a pointer to a message handle into the msghp parameter.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR

Parameters

hndl(IN/OUT)

Pointer to an OCI environment or user session handle for message language

errhp(IN/OUT)

The OCI error handle. If there is an error, it is recorded in errhp, and the function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet().

msghp(OUT)

A message handle for return

product(IN)

A pointer to a product name. The product name is used to locate the directory for messages. Its location depends on the operating system. For example, in Solaris, the directory of message files for the rdbms product is $ORACLE_HOME/rdbms.

facility(IN)

A pointer to a facility name in the product. It is used to construct a message file name. A message file name follows the conversion with facility as prefix. For example, the message file name for the img facility in the American language is imgus.msb, where us is the abbreviation for the American language and msb is the message binary file extension.

dur(IN)

The duration for memory allocation for the return message handle. It can have the following values:

OCI_DURATION_PROCESS
OCI_DURATION_SESSION
OCI_DURATION_STATEMENT

OCIMessageGet()

Syntax

OraText *OCIMessageGet(OCIMsg *msgh, ub4 msgno, OraText *msgbuf, size_t buflen)

Purpose

This function gets a message with the message number identified by msgno. If buflen is not zero, then the function copies the message into the buffer pointed to by msgbuf. If buflen is zero, then the message is copied into a message buffer inside the message handle pointed to by msgh.

Returns

It returns the pointer to the NULL-terminated message string. If the translated message cannot be found, then it tries to return the equivalent English message. If the equivalent English message cannot be found, then it returns a NULL pointer.

Parameters

msgh(IN/OUT)

Pointer to a message handle which was previously opened by OCIMessageOpen()

msgno(IN)

The message number for getting message

msgbuf(OUT)

Pointer to a destination buffer for the retrieved message. If buflen is zero, then it can be a NULL pointer.

buflen(IN)

The size of the destination buffer

OCIMessageClose()

Syntax

sword OCIMessageClose(dvoid *hndl, OCIError *errhp, OCIMsg *msgh)

Purpose

This function closes a message handle pointed to by msgh and frees any memory associated with this handle.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR

Parameters

Table 8-5 OCIMessageClose Keywords/Parameters (Cont.) Keyword/Parameter Meaning

hndl(IN/OUT)

Pointer to an OCI environment or user session handle for message language

errhp(IN/OUT)

The OCI error handle. If there is an error, it is recorded in errhp and the function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet().

msgh(IN/OUT)

A pointer to a message handle that was previously opened by OCIMessageOpen()

Example: Retrieving a Message from a Text Message File

This example creates a message handle, initializes it to retrieve messages from impus.msg, retrieves message number 128, and closes the message handle. It assumes that OCI environment handles, OCI session handles, product, facility, and cache size have been initialized properly.

OCIMsg msghnd;                                              /* message handle */
         /* initialize a message handle for retrieving messages from impus.msg*/
err = OCIMessageOpen(hndl,errhp, &msghnd, prod,fac,OCI_DURATION_SESSION);
if (err != OCI_SUCCESS)
                                                            /* error handling */
...
                            /* retrieve the message with message number = 128 */
msgptr = OCIMessageGet(msghnd, 128, msgbuf, sizeof(msgbuf));
                         /* do something with the message, such as display it */
...
      /* close the message handle when there are no more messages to retrieve */

OCIMessageClose(hndl, errhp, msghnd);

lmsgen Utility

Purpose

The lmsgen utility converts text-based message files (.msg) into binary format (.msb) so that Oracle messages and OCI messages provided by the user can be returned to OCI functions in the desired language.

Syntax

LMSGEN text_file product facility [language]

text_file is a message text file.
product is the name of the product.
facility is the name of the facility.

language is the optional message language corresponding to the language specified in the NLS_LANG parameter. The language parameter is required if the message file is not tagged properly with language.

Text Message Files

Text message files must follow these guidelines:

Lines that start with / and // are treated as internal comments and are ignored.
To tag the message file with a specific language, include a line similar to the following:
```
#   CHARACTER_SET_NAME= Japanese_Japan.JA16EUC
```
Each message contains 3 fields:
```
message_number, warning_level, message_text
```
The message number must be unique within a message file.
The warning level is not currently used. Use 0.
The message text cannot be longer than 76 bytes.

The following is an example of an Oracle message text file:

/ Copyright (c) 2001 by the Oracle Corporation.  All rights reserved.
/ This is a test us7ascii message file
# CHARACTER_SET_NAME= american_america.us7ascii
/
00000, 00000, "Export terminated unsuccessfully\n"
00003, 00000, "no storage definition found for segment(%lu, %lu)"

Example: Creating a Binary Message File from a Text Message File

The following table contains sample values for the lmsgen parameters:

Parameter	Value
`product`	`$HOME/myApplication`
`facility`	`imp`
`language`	`AMERICAN`
`text_file`	`impus.msg`

The text message file is found in the following location:

$HOME/myApp/mesg/impus.msg

One of the lines in the text message file is:

00128,2, "Duplicate entry %s found in %s"

The lmsgen utility converts the text message file (impus.msg) into binary format, resulting in a file called impus.msb:

% lmsgen impus.msg $HOME/myApplication imp AMERICAN

The following output results:

Generating message file impus.msg -->
/home/scott/myApplication/mesg/impus.msb

NLS Binary Message File Generation Utility: Version 9.2.0.0.0 -Production

Copyright (c) Oracle Corporation 1979, 2001.  All rights reserved.

CORE    9.2.0.0.0       Production

8 OCI Programming in a Global Environment

Using the OCI NLS Functions

Specifying Character Sets in OCI

OCIEnvNlsCreate()

Syntax

Purpose

Parameters

Returns

Comments

Getting Locale Information in OCI

OCINlsGetInfo()

Syntax

Purpose

Returns

Parameters

OCI_NLS_MAXBUFSZ

Example: Getting Locale Information in OCI

OCINlsCharSetNameTold()

Syntax

Purpose

Returns

Parameters

OCINlsCharSetIdToName()

Syntax

Purpose

Returns

Parameters

OCINlsNumericInfoGet()

Syntax

Purpose

Returns

Parameters

OCINlsEnvironmentVariableGet()

Purpose

Syntax

Parameters

Returns

Comments

Mapping Locale Information Between Oracle and Other Standards

OCINlsNameMap()

Syntax

Purpose

Returns

Parameters

Manipulating Strings in OCI

Table 8-1 OCI String Manipulation Functions

OCIMultiByteToWideChar()

Syntax

Purpose

Returns

Parameters

OCIMultiByteInSizeToWideChar()

Syntax

Purpose

Returns

Parameters

OCIWideCharToMultiByte()

Syntax

Purpose

Returns

Parameters

OCIWideCharInSizeToMultiByte()

Syntax

Purpose

Returns

Parameters

OCIWideCharToLower()

Syntax

Purpose

Returns

Parameters

OCIWideCharToUpper()

Syntax

Purpose

Returns

Parameters

OCIWideCharStrcmp()

Syntax

Purpose

Returns

8
OCI Programming in a Global Environment