5
OCI Programming

This chapter contains information useful for OCI programming, including:

• Using the OCI NLS Functions

• NLS Language Information Retrieval

• String Manipulation

• Character Classification

• Character Set Conversion

• Messaging Mechanism

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 settings (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 ALTER SESSION. 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.

NLS Language Information Retrieval

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

Using environment handles, you can retrieve the following information:

• 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

OCINlsGetInfo

Syntax

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

Remarks

This function generates language information specified by item from OCI environment or user session handle hndl into an array pointed to by buf within a size limitation as buflen.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR on wrong items.

Table 5-1 OCINlsGetInfo Keywords/Parameters

Keyword/ Parameter	Meaning
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, it is recorded in errhp and this function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet()
buf(OUT)	Pointer to the destination buffer
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 OCI environment handle to return. 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 name OCI_NLS_CALENDAR: Calendar name

OCI_Nls_MaxBufSz

When calling OCINlsGetInfo(), you need to allocate the buffer to store the returned information for the particular language. The buffer size varies, depending 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. That is exactly what OCI_NLS_MAXBUFSZ is used for; it guarantees that the OCI_NLS_MAXBUFSZ is big enough to hold the largest item returned by OCINlsGetInfo(). This guarantees that the largest item returned by OCINlsGetInfo() will fit in the buffer.

See Oracle Call Interface Programmer's Guide and Oracle8i Data Cartridge Developer's Guide for further information.

NLS Language Information Retrieval Sample Code

The following is a simple case of retrieving information and checking 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);
}

String Manipulation

Two types of data structure are supported for string manipulation: multi-byte string and wide character string. Multi-byte strings are in native Oracle character set encoding and functions operated on them take the string as a whole unit. Wide character string wchar functions provide more flexibility in string manipulation and support character-based and string-based operations.

The wide character data type is Oracle-specific and not to be confused with the wchar_t defined by the ANSI/ISO C standard. The Oracle wide character is always 4 bytes in all platforms, while wchar_t is implementation- and platform-dependent. The idea of the Oracle wide character is to normalize multibyte character to have a fixed-width encoding for easy processing. This way, round-trip conversion between the Oracle wide character and the native character set is guaranteed.

The string manipulation can be classified into the following categories:

• Conversion of string between multibyte and wide character

• Character classifications

• Case conversion

• Display length calculation

• General string manipulation, such as compare, concatenation and searching

  Table 5-2 OCI String Manipulation Calls

  Function Call	Description
  OCIMultiByteToWideChar()	Converts an entire null-terminated string into the wchar format
  OCIMultiByteInSizeTo WideChar()	Converts part of a string into the wchar format
  OCIWideCharToMultiByte()	Converts an entire null-terminated wide character string into a multi-byte string
  OCIWideCharInSizeTo MultiByte()	Converts part of a wide character string into the multi-byte format
  OCIWideCharToLower()	If there is a lower-case character mapping in the specified locale, it will return the lower-case in wide character. If not, returns the same wide character
  OCIWideCharToUpper()	If there is an lower-case character mapping in the specified locale, it will return the upper-case in wide character. If not, returns the same wide character
  OCIWideCharStrcmp()	Compares two wide character strings in binary, linguistic, or case-insensitive manners
  OCIWideCharStrncmp()	Similar to OCIWideCharStrcmp(), but compares two multi-byte strings in binary, linguistic, or case-insensitive manners, except that at most len1 bytes form str1 and len2 bytes form str2 are compared
  OCIWideCharStrcat()	Appends a copy of the string pointed to by wsrcstr. Then returns the number of characters in the resulting string
  OCIWideCharStrchr()	Searches for the first occurrence of wc in the string pointed to by wstr. Then returns a pointer to the wchar if successful
  OCIWideCharStrcpy()	Copies the wchar string pointed to by wsrcstr into the array pointed to by wdststr. Then returns the number of characters copied
  OCIWideCharStrlen()	Computes the number of characters in the wchar string pointed to by wstr, and returns this number
  OCIWideCharStrncat()	Appends a copy of the string pointed to by wsrcstr. Then returns the number of characters in the resulting string, except that at most n characters are appended
  OCIWideCharStrncpy()	Copies the wchar string pointed to by wsrcstr into the array pointed to by wdststr. Then returns the number of characters copied, except that at most n characters are copied from the array
  OCIWideCharStrrchr()	Searches for the last occurrence of wc in the string pointed to by wstr
  OCIWideCharStrCase Conversion()	Converts the wide character string pointed to by wsrcstr into case specified by flag and copies the result into the array pointed to by wdststr
  OCIWideCharDisplayLength()	Determines the number of column positions required for wc in display
  OCIWideCharMultibyte Length()	Determines the number of bytes required for wc in multi-byte encoding
  OCIMultiByteStrcmp()	Compares two multi-byte strings in binary, linguistic, or case-insensitive manners
  OCIMultiByteStrncmp()	Compares two multi-byte strings in binary, linguistic, or case-insensitive manners, except that at most len1 bytes form str1 and len2 bytes form str2 are compared
  OCIMultiByteStrcat()	Appends a copy of the multi-byte string pointed to by srcstr
  OCIMultiByteStrcpy()	Copies the multi-byte string pointed to by srcstr into an array pointed to by dststr. It returns the number of bytes copied
  OCIMultiByteStrlen()	Computes the number of bytes in the multi-byte string pointed to by str, and returns this number
  OCIMultiByteStrncat()	Appends a copy of the multi-byte string pointed to by srcstr, except that at most n bytes from srcstr are appended to dststr
  OCIMultiByteStrncpy()	Copies the multi-byte string pointed to by srcstr into an array pointed to by dststr. It returns the number of bytes copied, except that at most n bytes are copied from the array pointed to by srcstr to the array pointed to by dststr
  OCIMultiByteStrnDisplay Length()	Returns the number of display positions occupied by the complete characters within the range of n bytes
  OCIMultiByteStrCase Conversion()	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);

Remarks

This routine converts an entire NULL-terminated string into the wchar format. The wchar output buffer will be NULL-terminated.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.

Table 5-3  OCIMultiByteToWideChar Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

This routine converts part of a string into the wchar format. It will convert as many complete characters as it can until it reaches the output buffer size or input buffer size or it reaches a NULL-terminator in source string. The output buffer will be NULL-terminated if space permits. If dstsz is zero, this function will only return the number of characters not including the ending NULL terminator needed for converted string.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.

Table 5-4 OCIMultiByteInSizeToWideChar Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle to determine the character set of 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 character. If it is zero, this function just returns number of characters will be need for the conversion
src (IN)	Source string to be converted
srcsz(IN)	Length of source string in byte
rsize(OUT)	Number of characters written into destination buffer, or number of characters for converted string is dstsz is zero. If it is a NULL pointer, nothing to return

OCIWideCharToMultiByte

Syntax

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

Remarks

This routine converts an entire NULL-terminated wide character string into a multi-byte string. The output buffer will be NULL-terminated.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.

Table 5-5 OCIWideCharToMultiByte Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle to determine the character set of string
dst(OUT)	Destination buffer for multi-byte string
src(IN)	Source wchar string to be converted
srcsz(IN)	Length of source string in byte
rsize(OUT)	Number of characters written into destination buffer. If it is a NULL pointer, nothing will be returned

OCIWideCharInSizeToMultiByte

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

Remarks

This routine converts part of wchar string into the multi-byte format. It will convert as many complete characters as it can until it reaches the output buffer size, the input buffer size, or it reaches a NULL-terminator in source string. The output buffer will be NULL-terminated if space permits. If dstsz is zero, the function just returns the size of byte not including ending NULL-terminator needed to store the converted string.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.

Table 5-6 OCIWideCharInSizeToMultiByte Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle to determine the character set of string
dst(OUT)	Destination buffer for multi-byte. It can be a NULL pointer if dstsz is zero
dstsz(IN)	Destination buffer size in byte. If it is zero, it just returns the size of bytes need for converted string
src(IN)	Source wchar string to be converted
srcsz(IN)	Length of source string in character
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 to return

OCIWideCharToLower

Syntax

OCIWchar OCIWideCharToLower(dvoid *hndl, OCIWchar wc)

Remarks

If there is a lower-case character mapping for wc in the specified locale, it will return the lower-case in wchar, else return wc itself.

Returns

A wchar.

Table 5-7 OCIWideCharToLower Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle to determine the character set
wc(IN)	wchar for upper-case mapping

OCIWideCharToUpper

Syntax

OCIWchar OCIWideCharToUpper(dvoid *hndl, OCIWchar wc)

Remarks

If there is a upper-case character mapping for wc in the specified locale, it will return the upper-case in wchar, it will return wc itself otherwise.

Returns

A wchar.

Table 5-8 OCIWideCharToUpper Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle to determine the character set
wc(IN)	wchar for upper-case mapping

OCIWideCharStrcmp

Syntax

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

Remarks

It compares two wchar strings in binary (based on wchar encoding value), linguistic, or case-insensitive.

Returns

• 0, if wstr1 == wstr2.

• Positive, if wstr1 > wstr2.

• Negative, if wstr1 < wstr2.

  Table 5-9 OCIWideCharStrcmp Keywords/Parameters

  Keyword/Parameter	Meaning
  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)	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 linguistic comparison specified in the locale. This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison

OCIWideCharStrncmp

Syntax

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

Remarks

This function is similar to OCIWideCharStrcmp(), except that at most len1 characters from wstr1 and len2 characters from wstr1 are compared. The NULL-terminator will be taken into the comparison.

Returns

• 0, if wstr1 = wstr2

• Positive, if wstr1 > wstr2

• Negative, if wstr1 < wstr2

  Table 5-10  OCIWideCharStrncmp Keywords/Parameters

  Keyword/Parameter	Meaning
  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 linguistic comparison specified in the locale. This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison

OCIWideCharStrcat

Syntax

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

Remarks

This function appends a copy of the wchar string pointed to by wsrcstr, including the NULL-terminator to the end of wchar string pointed to by wdststr.

Returns

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

Table 5-11 OCIWideCharStrcat Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/)	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

OCIWideCharStrchr

Syntax

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

Remarks

This function searches for the first occurrence of wc in the wchar string pointed to by wstr.

Returns

A wchar pointer if successful, otherwise a NULL pointer.

Table 5-12  OCIWideCharStrchr Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

This function copies the wchar string pointed to by wsrcstr, including the NULL-terminator, into the array pointed to by wdststr.

Returns

The number of characters copied not including the ending NULL-terminator.

Table 5-13 OCIWideCharStrcpy Keywords/Parameters

Keyword/Parameter	Meaning
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

OCIWideCharStrlen

Syntax

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

Remarks

This function computes the number of characters in the wchar string pointed to by wstr, not including the NULL-terminator, and returns this number.

Returns

The number of characters not including ending NULL-terminator.

Table 5-14 OCIWideCharStrlen Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle to determine the character set
wstr(IN)	Pointer to the source wchar string

OCIWideCharStrncat

Syntax

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

Remarks

This function is similar to OCIWideCharStrcat(), except that at most n characters from wsrcstr are appended to wdststr. Note that the NULL-terminator in wsrcstr will stop appending. wdststr will be NULL-terminated.

Returns

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

Table 5-15 OCIWideCharStrncat Keywords/Parameters

Keyword/Parameter	Meaning
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
n(IN)	Number of characters from wsrcstr to append

OCIWideCharStrncpy

Syntax

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

Remarks

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 will stop coping and result string will be NULL-terminated.

Returns

The number of characters copied not including the ending NULL-terminator.

Table 5-16 OCIWideCharStrncpy Keywords/Parameters

Keyword/Parameter	Meaning
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

OCIWideCharStrrchr

Syntax

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

Remarks

This function searches for the last occurrence of wc in the wchar string pointed to by wstr. It returns a pointer to the wchar if successful, or a NULL pointer.

Returns

wchar pointer if successful, otherwise a NULL pointer.

Table 5-17 OCIWideCharStrrchr Keywords/Parameters

Keyword/Parameter	Meaning
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

OCIWideCharStrCaseConversion

Syntax

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

Remarks

This function converts the wide char string pointed to by wsrcstr into the uppercase or lowercase specified by flag and copies the result into the array pointed to by wdststr. The result string will be NULL-terminated.

Returns

The number of characters for result string not including NULL-terminator.

Table 5-18 OCIWideCharStrCaseConversion Keywords/Parameters

Keyword/Parameter	Meaning
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 uppercase. OCI_NLS_LOWERCASE: convert to lowercase. This flag can be ORed with OCI_NLS_LINGUISTIC to specify that the linguistic setting in the locale will be used for case conversion

OCIWideCharDisplayLength

Syntax

size_t OCIWideCharDisplayLength(dvoid *hndl, OCIWchar wc)

Remarks

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.

Returns

The number of display positions.

Table 5-19 OCIWideCharDisplayLength Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

This function determines the number of byte required for wc in multi-byte encoding. It returns the number of bytes in multi-byte for wc.

Returns

The number of bytes.

Table 5-20 OCIWideCharMultiByteLength Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

It compares two multi-byte strings in binary (based on encoding value), linguistic, or case-insensitive.

Returns

• 0, if str1 == str2.

• Positive, if str1 > str2.

• Negative, if str1 < str2.

  Table 5-21 OCIMultiByteStrcmp Keywords/Parameters

  Keyword/Parameter	Meaning
  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: for the binary comparison, this is default value. OCI_NLS_LINGUISTIC: for linguistic comparison specified in the locale. This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison

OCIMultiByteStrncmp

Syntax

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

Remarks

This function is similar to OCIMultiByteStrcmp(), except that at most len1 bytes from str1 and len2 bytes from str2 are compared. The NULL-terminator will be taken into the comparison.

Returns

• 0, if str1 = str2

• Positive, if str1 > str2

• Negative, if str1 < str2

  Table 5-22 OCIMultiByteStrncmp Keywords/Parameters

  Keyword/Parameter	Meaning
  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: for the binary comparison, this is default value. OCI_NLS_LINGUISTIC: for linguistic comparison specified in the locale. This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive comparison

OCIMultiByteStrcat

Syntax

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

Remarks

This function appends a copy of the multi-byte string pointed to by srcstr, including the NULL-terminator to the end of string pointed to by dststr. It returns the number of bytes in the result string not including the ending NULL-terminator.

Returns

The number of bytes in the result string not including the ending NULL-terminator.

Table 5-23 OCIMultiByteStrcat Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle to determine the character set
dststr(IN/OUT)	Pointer to the destination multi-byte string for appending
srcstr(IN)	Pointer to the source string to append

OCIMultiByteStrcpy

Syntax

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

Remarks

This function copies the multi-byte string pointed to by srcstr, including the NULL-terminator, into the array pointed to by dststr. It returns the number of bytes copied, not including the ending NULL-terminator.

Returns

The number of bytes copied not including the ending NULL-terminator.

Table 5-24  OCIMultiByteStrcpy Keywords/Parameters

Keyword/Parameter	Meaning
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 multi-byte string

OCIMultiByteStrlen

Syntax

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

Remarks

This function computes the number of bytes in the multi-byte string pointed to by str, not including the NULL-terminator, and returns this number.

Returns

The number of bytes not including ending NULL-terminator.

Table 5-25 OCIMultiByteStrlen Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	Pointer to the OCI environment or user session handle
str(IN)	Pointer to the source multi-byte string

OCIMultiByteStrncat

Syntax

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

Remarks

This function is similar to OCIMultiByteStrcat(), except that at most n bytes from srcstr are appended to dststr. Note that the NULL-terminator in srcstr will stop appending and the function will append as many character as possible within n bytes. dststr will be NULL-terminated.

Returns

The number of bytes in the result string not including the ending NULL-terminator.

Table 5-26 OCIMultiByteStrncat Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	Pointer to OCI environment or user session handle
dststr(IN/OUT)	Pointer to the destination multi-byte string for appending
srcstr(IN)	Pointer to the source multi-byte string to append
n(IN)	The number of bytes from srcstr to append

OCIMultiByteStrncpy

Syntax

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

Remarks

This function is similar to OCIMultiByteStrcpy(), except that 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 will stop coping and the function will copy as many character as possible within n bytes. The result string will be NULL-terminated.

Returns

The number of bytes copied not including the ending NULL-terminator.

Table 5-27 OCIMultiByteStrncpy Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	Pointer to OCI environment or user session handle
srcstr(OUT)	Pointer to the destination buffer
dststr(IN)	Pointer to the source multi-byte string
n(IN)	The number of bytes from srcstr to copy

OCIMultiByteStrnDisplayLength

Syntax

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

Remarks

This function returns the number of display positions occupied by the complete characters within the range of n bytes.

Returns

The number of display positions.

Table 5-28 OCIMultiByteStrncpy Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle
str(IN)	Pointer to a multi-byte string
n(IN)	The number of bytes to examine

OCIMultiByteStrCaseConversion

Syntax

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

Remarks

This function convert the multi-byte string pointed to by srcstr into the uppercase or lowercase specified by flag and copies the result into the array pointed to by dststr. The result string will be NULL-terminated.

Returns

The number of bytes for result string not including NULL-terminator.

Table 5-29 OCIMultibyteStrCaseConversion Keywords/Parameters

Keyword/Parameter	Meaning
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 convert: OCI_NLS_UPPERCASE: convert to uppercase. OCI_NLS_LOWERCASE: convert to lowercase. This flag can be ORed with OCI_NLS_LINGUISTIC to specify that the linguistic setting in the locale will be used for case conversion

String Manipulation Sample Code

The following is a simple case of handling string manipulation.

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);
}

See Oracle Call Interface Programmer's Guide and Oracle8i Data Cartridge Developer's Guide for further information.

Character Classification

The Oracle Call Interface offers many function calls for classifying characters.

Table 5-30 OCI Character Classification Calls

Function Call	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 multi-byte

OCIWideCharIsAlnum

Syntax

boolean OCIWideCharIsAlnum(dvoid *hndl, OCIWchar wc)

Remarks

It tests whether wc is a letter or decimal digit.

Returns

TRUE or FALSE.

Table 5-31 OCIWideCharIsAlnum Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

It tests whether wc is an alphabetic letter.

Returns

TRUE or FALSE.

Table 5-32 OCIWideCharIsAlpha Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

It tests whether wc is a control character.

Returns

TRUE or FALSE.

Table 5-33 OCIWideCharIsCntrl Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

It tests whether wc is a decimal digit character.

Returns

TRUE or FALSE.

Table 5-34  OCIWideCharIsDigit Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

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

Returns

TRUE or FALSE.

Table 5-35 OCIWideCharIsGraph Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

It tests whether wc is a lowercase letter.

Returns

TRUE or FALSE.

Table 5-36 OCIWideCharIsLower Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

It tests whether wc is a printable character.

Returns

TRUE or FALSE.

Table 5-37 OCIWideCharIsPrint Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

It tests whether wc is a punctuation character.

Returns

TRUE or FALSE.

Table 5-38 OCIWideCharIsPunct Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

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

Returns

TRUE or FALSE.

Table 5-39 OCIWideCharIsSpace Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

It tests whether wc is an uppercase letter.

Returns

TRUE or FALSE.

Table 5-40 OCIWideCharIsUpper Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

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

Returns

TRUE or FALSE.

Table 5-41  OCIWideCharIsXdigit Keywords/Parameters

Keyword/Parameter	Meaning
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)

Remarks

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

Returns

TRUE or FALSE.

Table 5-42 OCIWideCharIsSingleByte Keywords/Parameters

Keyword/Parameter	Meaning
hndl(IN/OUT)	OCI environment or user session handle to determine the character set
wc(IN)	wchar for testing

Character Classification Sample Code

 /* Character classification sample code */
boolean MyIsNumberWideCharString(envhp, srcStr)
OCIEnv   *envhp;
OCIWchar *srcStr;                                 /* wide char source string */
{
  OCIWchar *pstr = srcStr;                        /* define and init pointer */
  boolean status = TRUE;                  /* define and init 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);
}

See Oracle Call Interface Programmer's Guide and Oracle8i Data Cartridge Developer's Guide for further information.

Character Set Conversion

Conversion between Oracle character set and Unicode (16 bit, fixed width Unicode encoding) is supported. Replacement characters will be used if there is no mapping from Unicode to the Oracle character set, therefore, round-trip conversion is not always possible.

Table 5-43 OCI Character Set Conversion Calls

Function Call	Description
OCICharsetToUnicode()	Converts a multi-byte string pointed to by src to Unicode into the array pointed to by dst
OCIUnicodeToCharset()	Converts a Unicode string pointed to by src to multi-byte into the array pointed to by dst
OCICharSetConversionIs ReplacementUsed()	Indicates whether the replacement character was used for nonconvertible characters in character set conversion in the last invocation of OCICharsetConv()

OCICharSetToUnicode

Syntax

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

Remarks

This function converts a multi-byte string pointed to by src to Unicode into the array pointed to by dst. The conversion will stop when it reach to the source limitation or destination limitation. The function will return number of characters converted into Unicode. If dstlen is zero, it will just return the number of characters into rsize for the result without real conversion.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.

Table 5-44  OCICharSetToUnicode Keywords/Parameters

Keyword/Parameter	Meaning
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 character
src(IN)	Pointer to multi-byte source string
srclen(IN)	The size of source string in bytes
rsize(OUT)	The number of characters converted. If it is a NULL pointer, nothing to return

OCIUnicodeToCharSet

Syntax

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

Remarks

This function converts a Unicode string pointed to by src to multi-byte into the array pointed to by dst. The conversion will stop when it reach to the source limitation or destination limitation. The function will return the number of bytes converted into multi-byte. If dstlen is zero, it will just return the number of bytes into rsize for the result without real conversion.

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

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.

Table 5-45 OCIUnicodeToCharSet Keywords/Parameters

Keyword/Parameter	Meaning
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 source string in characters
rsize(OUT)	The number of bytes converted. If it is a NULL pointer, nothing to return

OCICharSetConversionIsReplacementUsed

Syntax

boolean OCICharSetConversionIsReplacementUsed(dvoid *hndl)

Remarks

This function indicates whether or not the replacement character was used for nonconvertible characters in character set conversion in the last invocation of OCICharSetToUnicode().

Returns

TRUE is the replacement character was used in last OCICharsetConv() invoking, else FALSE.

Table 5-46 OCICharSetConversionIsReplacementUsed Keywords/Parameters

Keyword/Parameter	Meaning
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 will be used if there is no mapping from Unicode to the Oracle character set, thus, round-trip conversion is not always possible.

Character Set Conversion Sample Code

The following is 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);
}

See Oracle Call Interface Programmer's Guide and Oracle8i Data Cartridge Developer's Guide for further information.

Messaging Mechanism

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

Table 5-47 OCI Messaging Function Calls

Function Call	Description
OCIMessageOpen()	Opens a message handle for facility of product in a language pointed to by hndl
OCIMessageGet()	Retrieves a message with message number identified by msgno and if the buffer is not zero, the function will copy 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

See Oracle Call Interface Programmer's Guide and Oracle8i Data Cartridge Developer's Guide for further information.

OCIMessageOpen

Syntax

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

Remarks

This function opens a message handle for facility of product in a language pointed to by hndl. It first tries to open the message file corresponding to hndl for the facility. If it succeeds, it will use that file to initialize a message handle, else it will use the default message file which is for American language for the facility. The function returns a pointer pointed to a message handle into the msghp parameter.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.

Table 5-48 OCICharSetConversionIsReplacementUsed Keywords/Parameters

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 record in errhp and this 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. Product name is used to locate the directory for message in a system dependent way. For example, in Solaris, the directory of message files for the product 'rdbms' 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 facility 'img' in the American language will be 'imgus.msb' where 'us' is the abbreviation for the American language and 'msb' as message binary file extension
dur(IN)	The duration for memory allocation for the return message handle. It can be the following values: OCI_DURATION_PROCESS OCI_DURATION_STATEMENT OCI_DURATION_SESSION

OCIMessageGet

Syntax

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

Remarks

This function will get message with message number identified by msgno and if buflen is not zero, the function will copy the message into the buffer pointed to by msgbuf. If buflen is zero, the message will be copied into a message buffer inside the message handle pointed to by msgh. For both cases. it will return the pointer to the NULL-terminated message string. If it cannot get the message required, it will return a NULL pointer.

Returns

A pointer to a NULL-terminated message string on success, otherwise a NULL pointer.

Table 5-49 OCIMessageGet Keywords/Parameters

Keyword/Parameter	Meaning
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 to the message retrieved. If buflen is zero, it can be NULL pointer
buflen(IN)	The size of the above destination buffer

OCIMessageClose

Syntax

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

Remarks

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.

Table 5-50 OCIMessageClose Keywords/Parameters

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 record in errhp and this 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()

LMSGEN

Remarks

The lmsgen utility converts text based message files (.msg) into binary format (.msb).

Syntax

LMSGEN <text file> <product> <facility> [language]
WHERE, 
   <text file> is a message text file
   <product>   the name of the product
   <facility>  the name of the facility
    [language]  optional message language in <language>_<territory>.<character 
set> format

This is required if the message file is not tagged properly with language.

Text Message File Format

• Lines start with "/" and "//" are treated as internal comments and hence are ignored.

• To tag the message file with a specific language:

  #   CHARACTER_SET_NAME= Japanese_Japan.JA16EUC
  
  

• Each message is composed of 3 fields:

  <message #>, <warning level #>, <message text>
  
  

  • Message # has to be unique within a message file.

  • Warning level # is not used currently, simply use 0.

  • Message text cannot be longer than 76 bytes.

Example

/ Copyright (c) 1988 by the Oracle Corporation.  All rights reserved.
/ This is a testing 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)"

Message Example

Settings

This example will retrieve messages from a .msb message file. The following settings are used:

product = $HOME/myApp
facility = imp
Language = American language

Based on the above setting, the message file $HOME/myApp/mesg/impus.msb will be used.

Message file

Lmsgen will convert the message file (impus.msg) into binary format (impus.msb).

The following is a portion of the text message file, impus.msg:

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

Messaging sample code:

/* Assume that the OCI environment or user session handle, product, facility and 
cache size are all 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 we has no more message to retrieve */
OCIMessageClose(hndl, errhp, msghnd);