Oracle® Database Globalization Support Guide 10g Release 2 (10.2) Part Number B14225-02 |
|
|
View PDF |
This chapter contains information about OCI programming in a global environment. It includes the following topics:
Many OCI NLS functions accept one of the following handles:
The environment handle
The user session handle
The OCI environment handle is associated with the client NLS environment and initialized with the client NLS environment variables. This environment does not change when ALTER
SESSION
statements are issued to the server. The character set associated with the environment handle is the client character set.
The OCI session handle is associated with the server session environment. Its NLS settings change when the session environment is modified with an ALTER
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 functionsUse the OCIEnvNlsCreate
function to specify client-side database and national character sets when the OCI environment is created.This function allows users to set character set information dynamically in applications, independent of the NLS_LANG
and NLS_NCHAR
initialization parameter settings. In addition, one application can initialize several environment handles for different client environments in the same server environment.
Any Oracle character set ID except AL16UTF16 can be specified through the OCIEnvNlsCreate
function to specify the encoding of metadata, SQL CHAR
data, and SQL NCHAR
data. Use OCI_UTF16ID
in the OCIEnvNlsCreate
function to specify UTF-16 data.
See Also:
Oracle Call Interface Programmer's Guide for more information about theOCIEnvNlsCreate
functionAn Oracle locale consists of language, territory, and character set definitions. 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 expect to see day and month names in German.
You can use the OCINlsGetInfo()
function to retrieve the following locale information:
Table 10-1 summarizes OCI functions that return locale information.
Table 10-1 OCI Functions That Return Locale Information
Function | Description |
---|---|
Returns locale information. See preceding text. |
|
Returns the Oracle character set ID for the specified Oracle character set name |
|
Returns the Oracle character set name from the specified character set ID |
|
Returns specified numeric information such as maximum character size |
|
Returns the character set ID from |
See Also:
Oracle Call Interface Programmer's GuideThe OCINlsNameMap
function maps Oracle character set names, language names, and territory names to and from Internet Assigned Numbers Authority (IANA) and International Organization for Standardization (ISO) names.
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 loss for round-trip conversion between the Oracle wide character format and the native character format.
String manipulation includes the :
Conversion of strings between native character format and wide character format
Character classifications
Case conversion
Calculations of display length
General string manipulation, 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.Table 10-2 OCI String Manipulation Functions
Function | Description |
---|---|
Converts an entire null-terminated string into the |
|
Converts part of a string into the |
|
Converts an entire null-terminated wide character string into a multibyte string |
|
Converts part of a wide character string into the multibyte format |
|
Converts the |
|
Converts the |
|
Compares two wide character strings by binary, linguistic, or case-insensitive comparison method. Note: The |
|
Similar to Note: As with |
|
Appends a copy of the string pointed to by |
|
Appends a copy of the string pointed to by |
|
Searches for the first occurrence of |
|
Searches for the last occurrence of |
|
Copies the |
|
Copies the |
|
Computes the number of characters in the |
|
Converts the wide character string pointed to by |
|
Determines the number of column positions required for |
|
Determines the number of bytes required for |
|
Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods |
|
Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. At most |
|
Appends a copy of the multibyte string pointed to by |
|
Appends a copy of the multibyte string pointed to by |
|
Copies the multibyte string pointed to by |
|
Copies the multibyte string pointed to by |
|
Returns the number of bytes in the multibyte string pointed to by |
|
Returns the number of display positions occupied by the complete characters within the range of |
|
Converts part of a string from one character set to another |
Table 10-3 shows the OCI character classification functions.
Table 10-3 OCI Character Classification Functions
Function | Description |
---|---|
Tests whether the wide character is an alphabetic letter or decimal digit |
|
Tests whether the wide character is an alphabetic letter |
|
Tests whether the wide character is a control character |
|
Tests whether the wide character is a decimal digit |
|
Tests whether the wide character is a graph character |
|
Tests whether the wide character is a lowercase letter |
|
Tests whether the wide character is a printable character |
|
Tests whether the wide character is a punctuation character |
|
Tests whether the wide character is a space character |
|
Tests whether the wide character is an uppercase character |
|
Tests whether the wide character is a hexadecimal digit |
|
Tests whether |
See Also:
Oracle Call Interface Programmer's GuideConversion between Oracle character sets and Unicode (16-bit, fixed-width Unicode encoding) is supported. Replacement characters are used if a character 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 the OCI character set conversion functions.
Table 10-4 OCI Character Set Conversion Functions
Function | Description |
---|---|
Converts a multibyte string pointed to by |
|
Converts a Unicode string pointed to by |
|
Converts a string from one character set to another |
|
Indicates whether replacement characters were used for characters that could not be converted in the last invocation of |
The user message API provides a simple interface for cartridge developers to retrieve their own messages as well as Oracle messages.
Table 10-5 summarizes the OCI messaging functions.
Table 10-5 OCI Messaging Functions
Function | Description |
---|---|
Opens a message handle in a language pointed to by |
|
Retrieves a message with message number identified by |
|
Closes a message handle pointed to by |
See Also:
Oracle Data Cartridge Developer's GuidePurpose
The lmsgen
utility converts text-based message files (.msg
) into binary format (.msb
) so that Oracle messages and OCI messages provided by the user can be returned to OCI functions in the desired language.
Messages used by the server are stored in binary-format files that are placed in the $ORACLE_HOME/product_name/mesg
directory, or the equivalent for your operating system. Multiple versions of these files can exist, one for each supported language, using the following filename convention:
<product_id><language_abbrev>.msb
For example, the file containing the server messages in French is called oraf.msb
, because ORA
is the product ID (<product_id
>) and F
is the language abbreviation (<language_abbrev
>) for French. The value for product_name
is rdbms, so it is in the $ORACLE_HOME/rdbms/mesg
directory.
Syntax
LMSGEN text_file product facility [language] [-i indir] [-o outdir]
text_file
is a message text file.product
is the name of the product.facility
is the name of the facility.language
is 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.indir
is the optional directory to specify the text file location.outdir
is the optional directory to specify the output file location.The output (.msb
) file will be generated under the $ORACLE_HOME/product/mesg/
directory.
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 three fields:
message_number, warning_level, message_text
0
.The following is an example of an Oracle message text file:
/ Copyright (c) 2004 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 definition 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 |
myapp |
facility |
imp |
language |
AMERICAN |
text_file |
impus.msg |
One of the lines in the text message file is the following:
00128,2, "Duplicate entry %s found in %s"
The lmsgen
utility converts the text message file (impus.msg
) into binary format, resulting in a file called impus.msb
. The directory $ORACLE_HOME/myapp/mesg
must already exist.
% lmsgen impus.msg myapp imp AMERICAN
The following output results:
Generating message file impus.msg --> $ORACLE_HOME/myapp/mesg/impus.msb NLS Binary Message File Generation Utility: Version 10.2.0.1.0 - Production Copyright (c) Oracle Corporation 1979, 2004. All rights reserved. CORE 10.2.0.1.0 Production