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 |
|---|---|
|
|
|
|
|
|