Release 8.1.5
A67789-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i National Language Support Guide Release 8.1.5 A67789-01 |
|
This chapter contains information useful for OCI programming, including:
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 will obey a user's locale setting and cultural conventions. For example, in a German locale setting, users will expect to see day and month names in German.
Using environment handles, you can retrieve the following information:
sword OCINlsGetInfo(dvoid *hndl, OCIError *errhp, text *buf, size_t buflen, ub2 item)
This function generates language information specified by item from OCI environment or user session handle hndl into an array pointed to by buf within size limitation as buflen.
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR on wrong item.
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.
The following is a simple case of retrieving information and checking for errors.
sword MyPrintLinguisticName(envhp, errhp) OCIEnv *envhp; OCIError *errhp; { text 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); /* item */ if (ret != OCI_SUCCESS) { checkerr(errhp, ret, OCI_HTYPE_ERROR); ret = OCI_ERROR; } else { printf("NLS linguistic: %s\n", infoBuf); } return(ret); }
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 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:
Table 5-2 OCI String Manipulation Calls
sword OCIMultiByteToWideChar(dvoid *hndl, OCIWchar *dst, CONST text *src, size_t *rsize);
This routine converts an entire NULL-terminated string into the wchar format. The wchar output buffer will be NULL-terminated.
OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.
sword OCIMultiByteInSizeToWideChar(dvoid *hndl, OCIWchar *dst, size_t dstsz, CONST text *src, size_t srcsz, size_t *rsize)
This routine converts part of a string into the wchar format. It will convert as many complete characters as it can until it reaches 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.
OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.
sword OCIWideCharToMultiByte(dvoid *hndl, text *dst, CONST OCIWchar *src, size_t *rsize)
This routine converts an entire NULL-terminated wide character string into multi-byte string. The output buffer will be NULL-terminated.
OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.
sword OCIWideCharInSizeToMultiByte(dvoid *hndl, text *dst, size_t dstsz, CONST OCIWchar *src, size_t srcsz, size_t *rsize)
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 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, the function just returns the size of byte not including ending NULL-terminator needed to store the converted string.
OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.
OCIWchar OCIWideCharToLower(dvoid *hndl, OCIWchar wc)
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.
A wchar.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
OCIWchar OCIWideCharToUpper(dvoid *hndl, OCIWchar wc)
If there is a upper-case character mapping for wc in the specified locale, it will return the upper-case in wchar, else return wc itself.
A wchar.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
int OCIWideCharStrcmp(dvoid *hndl, CONST OCIWchar *wstr1, CONST OCIWchar *wstr2, int flag)
It compares two wchar string in binary (based on wchar encoding value), linguistic, or case-insensitive.
Table 5-9 OCIWideCharStrcmp Keywords/Parameters
int OCIWideCharStrncmp(dvoid *hndl, CONST OCIWchar *wstr1, size_t len1, CONST OCIWchar *wstr2, size_t len2, int flag)
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.
Table 5-10 OCIWideCharStrncmp Keywords/Parameters
size_t OCIWideCharStrcat(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar *wsrcstr)
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.
The number of characters in the result string not including the ending NULL-terminator.
OCIWchar *OCIWideCharStrchr(dvoid *hndl, CONST OCIWchar *wstr, OCIWchar wc)
This function searches for the first occurrence of wc in the wchar string pointed to by wstr.
A wchar pointer if successful, otherwise a NULL pointer.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
pointer to the |
|
|
|
size_t OCIWideCharStrcpy(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar *wsrcstr)
This function copies the wchar string pointed to by wsrcstr, including the NULL-terminator, into the array pointed to by wdststr.
The number of characters copied not including the ending NULL-terminator.
size_t OCIWideCharStrlen(dvoid *hndl, CONST OCIWchar *wstr)
This function computes the number of characters in the wchar string pointed to by wstr, not including the NULL-terminator, and returns this number.
The number of characters not including ending NULL-terminator.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
pointer to the source |
size_t OCIWideCharStrncat(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar *wsrcstr, size_t n)
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.
The number of characters in the result string not including the ending NULL-terminator.
size_t OCIWideCharStrncpy(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar *wsrcstr, size_t n)
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.
The number of characters copied not including the ending NULL-terminator.
OCIWchar *OCIWideCharStrrchr(dvoid *hndl, CONST OCIWchar *wstr, OCIWchar wc)
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.
wchar pointer if successful, otherwise a NULL pointer.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
pointer to the |
|
|
|
size_t OCIWideCharStrCaseConversion(dvoid *hndl, OCIWchar *wdststr, CONST OCIWchar*wsrcstr, ub4 flag)
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.
The number of characters for result string not including NULL-terminator.
size_t OCIWideCharDisplayLength(dvoid *hndl, OCIWchar wc )
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.
The number of display positions.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
size_t OCIWideCharMultiByteLen(dvoid *hndl, OCIWchar wc )
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.
The number of bytes.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
int OCIMultiByteStrcmp(dvoid *hndl, CONST text *str1, CONST text *str2, int flag)
It compares two multi-byte strings in binary (based on encoding value), linguistic, or case-insensitive.
Table 5-21 OCIMultiByteStrcmp Keywords/Parameters
int OCIMultiByteStrncmp(dvoid *hndl, CONST text *str1, size_t len1, text *str2, size_t len2, int flag)
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.
Table 5-22 OCIMultiByeStrncmp Keywords/Parameters
size_t OCIMultiByteStrcat(dvoid *hndl, text *dststr, CONST text *srcstr)
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.
The number of bytes in the result string not including the ending NULL-terminator.
size_t OCIMultiByteStrcpy(dvoid *hndl, text *dststr, CONST text *srcstr)
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.
The number of bytes copied not including the ending NULL-terminator.
| Keyword/Parameter | Meaning |
|---|---|
|
|
pointer to the |
|
|
pointer to the destination buffer |
|
|
pointer to the source multi-byte string |
size_t OCIMultiByteStrlen(dvoid *hndl, CONST text *str)
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.
The number of bytes not including ending NULL-terminator.
| Keyword/Parameter | Meaning |
|---|---|
|
|
pointer to the OCI environment or user session handle |
|
|
|
size_t OCIMultiByteStrncat(dvoid *hndl, text *dststr, CONST text *srcstr, size_t n)
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.
The number of bytes in the result string not including the ending NULL-terminator.
size_t OCIMultiByteStrncpy(dvoid *hndl, text *dststr, CONST text *srcstr, size_t n)
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.
The number of bytes copied not including the ending NULL-terminator.
size_t OCIMultiByteStrnDisplayLength(dvoid *hndl, CONST text *str1, size_t n)
This function returns the number of display positions occupied by the complete characters within the range of n bytes.
The number of display positions.
| Keyword/Parameter | Meaning |
|---|---|
|
|
OCI environment or user session handle |
|
|
pointer to a multi-byte string |
|
|
number of bytes to examine |
size_t OCIMultiByteStrCaseConversion(dvoid *hndl, text *dststr, CONST text *srcstr, ub4 flag)
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.
The number of bytes for result string not including NULL-terminator.
The following is a simple case of handling string manipulation.
size_t MyConvertMultiByteToWideChar(envhp, dstBuf, dstSize, srcStr) OCIEnv *envhp; OCIWchar *dstBuf; size_t dstSize; text *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.
The Oracle Call Interface offers many function calls for classifying characters.
| 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. |
boolean OCIWideCharIsAlnum(dvoid *hndl, OCIWchar wc)
It tests whether wc is a letter or decimal digit.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsAlpha(dvoid *hndl, OCIWchar wc)
It tests whether wc is an alphabetic letter.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsCntrl(dvoid *hndl, OCIWchar wc)
It tests whether wc is a control character.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsDigit(dvoid *hndl, OCIWchar wc)
It tests whether wc is a decimal digit character.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsGraph(dvoid *hndl, OCIWchar wc)
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.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsLower(dvoid *hndl, OCIWchar wc)
It tests whether wc is a lowercase letter.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsPrint(dvoid *hndl, OCIWchar wc)
It tests whether wc is a printable character.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsPunct(dvoid *hndl, OCIWchar wc)
It tests whether wc is a punctuation character.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsSpace(dvoid *hndl, OCIWchar wc)
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).
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsUpper(dvoid *hndl, OCIWchar wc)
It tests whether wc is an uppercase letter.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsXdigit(dvoid *hndl, OCIWchar wc)
It tests whether wc is a hexadecimal digit (0-9, A-F, a-f).
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
boolean OCIWideCharIsSingleByte(dvoid *hndl, OCIWchar wc)
It tests whether wc is a single-byte character when converted into multi-byte.
TRUE or FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
|
|
|
|
/* 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.
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.
| 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(). |
sword OCICharSetToUnicode(dvoid *hndl, ub2 *dst, size_t dstlen, CONST text *src, size_t srclen, size_t *rsize)
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.
OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.
sword OCIUnicodeToCharSet(dvoid *hndl, text *dst, size_t dstlen, CONST ub2 *src, size_t srclen, size_t *rsize)
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.
OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.
boolean OCICharSetConversionIsReplacementUsed(dvoid *hndl)
This function indicates whether or not the replacement character was used for nonconvertible characters in character set conversion in last invoke of OCICharSetToUnicode().
TRUE is the replacement character was used in last OCICharsetConv() invoking, else FALSE.
| Keyword/Parameter | Meaning |
|---|---|
|
|
pointer to an |
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.
The following is a simple conversion into Unicode.
size_t MyConvertMultiByteToUnicode(envhp, dstBuf, dstSize, srcStr) OCIEnv *envhp; ub2 *dstBuf; size_t dstSize; text *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.
The user message API provides a simple interface for cartridge developers to retrieve their own messages as well as Oracle messages.
| Function Call | Description |
|---|---|
| OCIMessageOpen() | Opens a message handle for facility of product in a language pointed to by envhp. |
| 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.
sword OCIMessageOpen(dvoid *hndl, OCIError *errhp, OCIMsg **msghp, CONST text *product, CONST text *facility, OCIDuration dur)
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.
OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.
text *OCIMessageGet(OCIMsg *msgh, ub4 msgno, text *msgbuf, size_t buflen)
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.
A pointer to a NULL-terminated message string on success, otherwise a NULL pointer.
sword OCIMessageClose(dvoid *hndl, OCIError *errhp, OCIMsg *msgh)
This function closes a message handle pointed to by msgh and frees any memory associated with this handle.
OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR.
The lmsgen utility converts text based message files (.msg) into binary format (.msb).
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.
# CHARACTER_SET_NAME= Japanese_Japan.JA16EUC
<message #>, <warning level #>, <message text>
/ 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)"
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.
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" ...
/* 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);
