Oracle8i National Language Support Guide
Release 8.1.5

A67789-01

Library

Product

Contents

Index

Prev Next

5
OCI Programming

This chapter contains information useful for OCI programming, including:

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

OCINlsGetInfo()

Using environment handles, you can retrieve the following information:

OCINlsGetInfo

Syntax
sword OCINlsGetInfo(dvoid *hndl, OCIError *errhp, text *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 size limitation as buflen.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR on wrong item.

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 destination buffer. The maximum length for each information is OCI_NLS_MAXBUFSZ bytes  

item (IN)  

It specifies to get which item in OCI environment handle and can be one of 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 : Nativestring 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_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;
{
  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);
}

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

OCIMultiByteToWideChar

Syntax
sword OCIMultiByteToWideChar(dvoid *hndl, OCIWchar *dst, CONST text *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 text *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 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, text *dst, CONST OCIWchar *src, size_t 
*rsize)
Remarks

This routine converts an entire NULL-terminated wide character string into 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 to return  

OCIWideCharInSizeToMultiByte

sword OCIWideCharInSizeToMultiByte(dvoid *hndl, text *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 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.

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 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, else return wc itself.

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 string in binary (based on wchar encoding value), linguistic, or case-insensitive.

Returns

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

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

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 text *str1, CONST text *str2, int 
flag)
Remarks

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

Returns

OCIMultiByteStrncmp

Syntax
int OCIMultiByteStrncmp(dvoid *hndl, CONST text *str1, size_t len1, text *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

OCIMultiByteStrcat

Syntax
size_t OCIMultiByteStrcat(dvoid *hndl, text *dststr, CONST text *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, text *dststr, CONST text *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  

srcstr (OUT)  

pointer to the destination buffer  

dststr (IN)  

pointer to the source multi-byte string  

OCIMultiByteStrlen

Syntax
size_t OCIMultiByteStrlen(dvoid *hndl, CONST text *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, text *dststr, CONST text *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  

srcstr (IN/OUT)  

pointer to the destination multi-byte string for appending  

dststr (IN)  

pointer to the source multi-byte string to append  

n (IN)  

number of bytes from srcstr to append  

OCIMultiByteStrncpy

Syntax
size_t OCIMultiByteStrncpy(dvoid *hndl, text *dststr, CONST text *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)  

number of bytes from srcstr to copy  

OCIMultiByteStrnDisplayLength

Syntax
size_t OCIMultiByteStrnDisplayLength(dvoid *hndl, CONST text *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)  

number of bytes to examine  

OCIMultiByteStrCaseConversion

Syntax
size_t OCIMultiByteStrCaseConversion(dvoid *hndl, text *dststr, CONST text 
*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 OCIMultibyteStrCaseKeywords/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;
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.

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 text *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)  

size of destination buffer in character  

src (IN)  

pointer to multi-byte source string  

srclen(IN)  

size of source string in bytes  

rsize (OUT)  

number of characters converted. If it is a NULL pointer, nothing to return  

OCIUnicodeToCharSet

Syntax
sword OCIUnicodeToCharSet(dvoid *hndl, text *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)  

size of destination buffer in bytes  

src (IN)  

pointer to a Unicode string  

srclen(IN)  

size of source string in characters  

rsize (OUT)  

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 last invoke 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;
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.

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

OCIMessageOpen

Syntax
sword OCIMessageOpen(dvoid *hndl, OCIError *errhp, OCIMsg **msghp, CONST text 
*product, CONST text *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)  

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
text *OCIMessageGet(OCIMsg *msgh, ub4 msgno, text *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 which 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

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



Prev

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index