10
OCI Programming in a Global Environment

This chapter contains information about OCI programming in a global environment. It includes the following topics:

Using the OCI NLS Functions
Specifying Character Sets in OCI
Getting Locale Information in OCI
Mapping Locale Information Between Oracle and Other Standards
Manipulating Strings in OCI
Classifying Characters in OCI
Converting Character Sets in OCI
< a href="ch10oci.htm#1007467">OCI Messaging Functions
lmsgen Utility

Using the OCI NLS Functions

Many OCI NLS fu nctions accept one of the following handles:

The environment h andle
The user session handle

The OCI environment handle is associated with the client NLS environment and initialized with the client NLS environment variables. T his environment does not change when ALTER SESSION statements are issued to the server. The character set a ssociated with the environment handle is the client character set.

The OCI session handle i s associated with the server session environment. Its NLS settings change when the session environment is modified with an ALTE R SESSION statement. The character set associated with the session handle is the database character set.

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

See Also:

Oracle Call Interface Programmer's Guide for detailed information about the OCI NLS functions

Getting Locale Information in OCI
An Oracle locale consists of language, territory, and character set definiti ons. The locale determines conventions such as day and month names, as well as date, time, number, and currency formats. A globalized application complies with a user's locale setting and cultural conventions. For example, when the locale is set to German, users exp ect to see day and month names in German.

You can use the `OCINlsGetInfo()` func tion to retrieve the following locale information:

Days of the week (transl ated)

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

< a name="1006066">Default character set

Default linguistic sort

Default calendar

Table 10-1 summarizes OCI functions that return locale information.
Table 10-1 OCI Funct ions That Return Locale Information

Function	Description
OCINlsGetInfo()	Returns locale informat ion. See preceding text.
OCINlsCharSetNameTold()	Returns the Oracle character set I D for the specified Oracle character set name
OCINlsCharSetIdToName()	Returns the O racle character set name from the specified character set ID
OCINlsNumericInfoGet()	Returns specified numeric information such as maximum character size
OCINlsEnvironmentVariableGet()	Returns the character set ID from `NLS_LANG` or the national character set ID from `NLS_NCHAR`

< tr class="NoteAlso">

Mapping Locale Information Between Oracle an d Other Standards

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

Manipulating Strings in OCI

Two types of data structures are supported for string manipulation:

Native character strings

Wide character strings

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

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

String manipulation can be classified as followings:

< /a>Conversion of strings between native character format and wide character format

Character classifications
Case conversion
Calculations of display length
General string manipula tion, such as comparison, concatenation, and searching

Table 10-2 summarizes the OCI string manipulation functions.

Note:

The functions and descriptions in Table 10-2 that refer to multibyte strings apply to native character strings.

< /div>

Table 10-2 OCI String Manipulation Functions

Funct ion	Description
`OCIMultiByteToWideChar()`	Converts an entire null-terminated string into the `wchar` format
`OCIMultiByteInSizeToWideChar()`	Converts part of a string into the `wchar` format
`OCIWideCharToMultiByte()`	Converts an entire null-terminated wide character string in to a multibyte string
`OCIWideCharInSizeToMultiByte()`	Converts part of a wide character string into the multibyte format
`OCIWideCharToLower()`	Converts the `wchar` character specified by `wc` into the corresponding lowercase character if it exists in th e specified locale. If no corresponding lowercase character exists, then it returns `wc` itself.
`OCIWideCharToUpper()`	Converts the `wchar` character specified by `wc` int o the corresponding uppercase character if it exists in the specified locale. If no corresponding uppercase character exists, then it returns `wc` itself.
`OCIWideCharStrcmp()`	Compares two wide character strings by binary, linguistic, or case-insensitive comparison method
`OCIWideCharStrncmp()`	Similar to `OCIWideCharStrcmp()`. Compares two wide character strings by binary, linguistic , or case-insensitive comparison methods. At most `len1` bytes form `str1`, and `len2` bytes form str2.
`OCIWideCharStrcat()`	Appends a copy of the string poin ted to by `wsrcstr`. Then it returns the number of characters in the resulting string.
`OCIWideCharStrncat()`	Appends a copy of the string pointed to by `wsrcstr`. Then it returns the number of characters in the resulting string. At most `n` characters are appended.
`OCIWideCharStrchr()`	Searches for the first occurrence of `wc` in the string pointed to b y `wstr`. Then it returns a pointer to the `wchar` if the search is successful.
`OCIWideCharStrrchr()`	Searches for the last occurrence of `wc` in the string pointed to by `wstr`
`OCIWideCharStrcpy()`	Copies the `wchar` st ring pointed to by `wsrcstr` into the array pointed to by `wdststr`. Then it returns the number of characters c opied.
`OCI WideCharStrncpy()`	Copies the `wchar` string point ed to by `wsrcstr` into the array pointed to by `wdststr`. Then it returns the number of characters copied. At most `n` characters are copied from the array.
`OCIWideCharStrlen()`	Computes the number of characters in the `wchar` string pointed to by `wstr` and returns this number
`OCI WideCharStrCaseConversion()`	Converts the wide character stri ng pointed to by `wsrcstr` into the case specified by a flag and copies the result into the array pointed to by `wdst str`
`OCIWideCharDisplayLength()`	Determines the number of column positions required for `wc` in display
`OCIWideCharMultibyteLength()`	Determines the number of bytes required for `wc` in multibyte encoding
`OCIMultiByteStrcmp()`	Compares two multibyte strings by binary, linguistic, or case-insensitive comparison method s
`OCIMulti ByteStrncmp()`	Compares two multibyte strings by binary, ling uistic, or case-insensitive comparison methods. At most `len1` bytes form `str1` and `len2` bytes fo rm `str2.`
`OCIMultiByteStrcat()`	Appends a copy of the multi byte string pointed to by `srcstr`
`OCIMultiByteStrncat()`	Ap pends a copy of the multibyte string pointed to by `srcstr`. At most `n` bytes from `srcstr` are appended to `dststr`
`OCIMultiByteStrcpy()`	Copies the multibyte string pointed to by `srcstr` into an array pointed to by `dststr`. It returns the number of bytes co pied.
`OCIM ultiByteStrncpy()`	Copies the multibyte string pointed to by `srcstr` into an array pointed to by `dststr`. It returns the number of bytes copied. At most `n` bytes are copied from the array pointed to by `srcstr` to the array pointed to by `dststr`.
`OCIMultiByteStrlen()`	Returns the number of bytes in the multibyte string pointed t o by `str`
`OCIMultiByteStrnDisplayLength()`	Returns the numb er of display positions occupied by the complete characters within the range of `n` bytes
`OCIMultiByteStrCaseConversion()`	Converts part of a string from one character set to another

Classifying Characters in OCI

Table 10-3 shows the OCI character classification functions.

Table 10-3 OCI Character Classification Functions

Function	Description
`OCIWideCharIsAlnum()`	Tests whether the wide character is an alphabetic 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 digit
`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()< /code>`	Tests whether the wide character is a punctuation character< /p>
`OCIWideCha rIsSpace()`	Tests whether the wide character is a space chara cter
`OCIWi deCharIsUpper()`	Tests whether the wide character is an upper case character
< code>OCIWideCharIsXdigit()	Tests whether the wide character is a hexadecimal digit
`OCIWideCharIsSingleByte()`	Tests whether `w c` is a single-byte character when converted into multibyte

Converting Character Sets in OCI

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

Table 10-4 summarizes th e OCI character set conversion functions.

Table 10-4 OCI Character Set Conversion Functions

< tr class="Formal" align="left" valign="top">

Function Description

OCICharSetToUnicode()
< /td>
Converts a multibyte string pointed to by src to Unicode i nto the array pointed to by dst

OCIUnicodeToCharSet()

Con verts a Unicode string pointed to by src to multibyte into the array pointed to by dst

OCINlsCharSetConvert()< /p>

Converts a string from one character set to another

OCICharSetConversionIsRep lacementUsed()

Indicates whether replacement characters were used for characters that could not be converted in the last invocation of OCINlsCharSetConvert() or OCIUnicodeToC harSet()

See Also:

Oracle Call Interface Programmer's Guide

"OCI Programming with Unicode"

OCI Messaging Functions

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

Table 10-5 summarizes th e OCI messaging functions.

Table 10-5 OCI Messaging Functions

Function Description

OCIMessageOpen()

Opens a message handle in a language pointed to by hndl

OCIMessageGet()

Retrieves a message with message number identified by msgno. If the buffer is not zero, then the function copies the message into the buffer specified by msgbuf.

OCIMessageClose()

Closes a message handle pointed to by msgh and frees any memory associated with this handle

See Also:
Oracle Data Cartridge Developer's Guide

lmsgen Utility

Purpose

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

Syntax

LMSGEN text_file product facility [language]

text_file is a message text file.

product is the name of the product.

facility is the name of the facility.

languageis the optional message language corresponding to the language specified in the NLS_LANG parameter. The language parameter is required if the message file is not tagged properly with language.
< h4 class="H3">Text Message Files Text message files must follow these guidelines: Lines that start with / and // are treated as internal comments and are ignored. To tag the message file with a specific language, include a line similar to the following: # CHARACTER_SET_NAME= Japanese_Japan.JA16EUC Each message contains 3 fields: message_number, warning_level, message_text The mess age number must be unique within a message file. The warning level is not currently used. Use 0. The message text cannot be longer than 511 bytes. The following is an example of an Oracle message te xt file: / Copyright (c) 2001 by the Oracle Corporation. All rights reserved. / This is a test us7ascii message file # CHARACTER_SET_NAME= american_america.us7ascii / 00000, 00000, "Export terminated unsuccessfully\n" 00003, 00000, "no storage de finition found for segment(%lu, %lu)" Example: Creating a Binary Message File from a Text Message File The following table contains sample values for the lmsgen parameters: Parameter Value product $HOME/myApplication facility imp language AMERICAN text_file impus.msg The text message file is found in the fo llowing location: $HOME/myApp/mesg/impus.msg One of the lines in the text message file is: 00128,2, "Duplicate ent ry %s found in %s" The lmsgen utility converts the t ext message file (impus.msg) into binary format, resulting in a file called impus.msb: % lmsgen impus.msg $HOME/myApplication imp AMERICAN The following output results: Generating message file impus.msg --> /home/scott/myApplication/mesg/impus.msb NLS Binary Message File Generation U tility: Version 10.1.0.0.0 -Production Copyright (c) Oracle Corporation 1979, 2003. All rights reserved. CORE 10.1.0.0.0 Production

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

Function	Description
`OCICharSetToUnicode()` < /td>	Converts a multibyte string pointed to by `src` to Unicode i nto the array pointed to by `dst`
`OCIUnicodeToCharSet()`	Con verts a Unicode string pointed to by `src` to multibyte into the array pointed to by `dst`
`OCINlsCharSetConvert()`< /p>	Converts a string from one character set to another
`OCICharSetConversionIsRep lacementUsed()`	Indicates whether replacement characters were used for characters that could not be converted in the last invocation of `OCINlsCharSetConvert()` or `OCIUnicodeToC harSet()`

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

10 OCI Programming in a Global Environment

Using the OCI NLS Functions

Mapping Locale Information Between Oracle an d Other Standards

Manipulating Strings in OCI

Table 10-2 OCI String Manipulation Functions

Classifying Characters in OCI

Table 10-3 OCI Character Classification Functions

Converting Character Sets in OCI

Table 10-4 OCI Character Set Conversion Functions

OCI Messaging Functions

Table 10-5 OCI Messaging Functions

lmsgen Utility

Purpose

Syntax

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

10
OCI Programming in a Global Environment