Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
|
|
View PDF |
This section describes the OCI locale functions.
An 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 obeys 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.
Table 21-3 OCI Locale Functions
Function/Page | Purpose |
---|---|
|
Returns the Oracle character set name from the specified character set ID. |
|
Returns the Oracle character set ID for the specified Oracle character set name. |
OCINlsEnvironmentVariableGet() |
Returns the character set ID from |
|
Copies locale information from an OCI environment or user session handle into an array pointed to by the destination buffer within a specified size. |
|
Copies numeric language information from the OCI environment handle into an output number variable. |
Purpose
Returns the Oracle character set name from the specified character set ID.
Syntax
sword OCINlsCharSetIdToName ( dvoid *hndl, oratext *buf, size_t buflen ub2 id );
Parameters
OCI environment or session handle. If the handle is invalid, then the function returns OCI_INVALID_HANDLE
.
Points to the destination buffer. If the function returns OCI_SUCCESS
, then the parameter contains a NULL
-terminated string for the character set name.
The size of the destination buffer. The recommended size is OCI_NLS_MAXBUFSZ
to guarantee storage for an Oracle character set name. If the size of the destination buffer is smaller than the length of the character set name, then the function returns OCI_ERROR
.
Oracle character set ID
Returns
OCI_SUCCESS
, OCI_INVALID_HANDLE
, or OCI_ERROR
Purpose
Returns the Oracle character set ID for the specified Oracle character set name.
Syntax
ub2 OCINlsCharSetNameToId ( dvoid *hndl, CONST oratext *name );
Parameters
OCI environment or session handle. If the handle is invalid, then the function returns zero.
Pointer to a NULL
-terminated Oracle character set name. If the character set name is invalid, then the function returns zero.
Returns
Character set ID if the specified character set name and the OCI handle are valid. Otherwise, it returns 0
.
Purpose
Returns the character set ID from NLS_LANG
or the national character set id from NLS_NCHAR
.
Syntax
sword OCINlsEnvironmentVariableGet ( dvoid *val, size_t size, ub2 item, ub2 charset, size_t *rsize );
Parameters
Returns a value of a globalization support environment variable such as the NLS_LANG
character set ID or the NLS_NCHAR
character set ID.
Specifies the size of the given output value, which is applicable only to string data. The maximum length for each piece of information is OCI_NLS_MAXBUFSZ
bytes. In the case of numeric data, this argument is ignored.
Specifies one of the following values to get from the globalization support environment variable:
OCI_NLS_CHARSET_ID
: NLS_LANG
character set ID in ub2
datatype.
OCI_NLS_NCHARSET_ID
: NLS_NCHAR
character set ID in ub2
datatype.
Specifies the character set ID for retrieved string data. If it is 0
, then the NLS_LANG
value is used. OCI_UTF16ID
is a valid value for this argument. In the case of numeric data, this argument is ignored.
The length of the return value in bytes.
Comments
Following globalization support convention, the national character set ID is the same as the character set ID if NLS_NCHAR
is not set. If NLS_LANG
is not set, then the default character set ID is returned.
To allow for future enhancements of this function (to retrieve other values from environment variables) the datatype of the output val
is a pointer to dvoid
. String data is not terminated by NULL
.
Note that the function does not take an environment handle, so the character set ID and the national character set ID that it returns are the values specified in NLS_LANG
and NLS_NCHAR
, instead of the values saved in the OCI environment handle. To get the character set IDs used by the OCI environment handle, call OCIAttrGet()
for OCI_ATTR_ENV_CHARSET
and OCI_ATTR_ENV_NCHARSET
, respectively.
Returns
OCI_SUCCESS
or OCI_ERROR
Related Functions
Purpose
Obtains locale information from an OCI environment or user session handle into an array pointed to by the destination buffer within a specified size.
Syntax
sword OCINlsGetInfo ( dvoid *hndl, OCIError *errhp, OraText *buf, size_t buflen, ub2 item );
Parameters
The OCI environment or user session handle initialized in object mode.
The OCI error handle. If there is an error, then it is recorded in errhp
and the function returns a NULL
pointer. Diagnostic information can be obtained by calling OCIErrorGet()
.
Pointer to the destination buffer. Returned strings are terminated by a NULL
character.
The size of the destination buffer. The maximum length for each piece of information is OCI_NLS_MAXBUFSZ
bytes.
OCI_NLS_MAXBUFSIZE
: When calling OCINlsGetInfo
(), you need to allocate the buffer to store the returned information. The buffer size depends 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. The OCI_NLS_MAXBUFSZ
attribute guarantees that the buffer is big enough to hold the largest item returned by OCINlsGetInfo
().
Specifies which item in the OCI environment handle to return. It can be one of the following values:
OCI_NLS_DAYNAME1
: Native name for MondayOCI_NLS_DAYNAME2
: Native name for TuesdayOCI_NLS_DAYNAME3
: Native name for WednesdayOCI_NLS_DAYNAME4
: Native name for ThursdayOCI_NLS_DAYNAME5
: Native name for FridayOCI_NLS_DAYNAME6
: Native name for SaturdayOCI_NLS_DAYNAME7
: Native name for SundayOCI_NLS_ABDAYNAME1
: Native abbreviated name for MondayOCI_NLS_ABDAYNAME2
: Native abbreviated name for TuesdayOCI_NLS_ABDAYNAME3
: Native abbreviated name for WednesdayOCI_NLS_ABDAYNAME4
: Native abbreviated name for ThursdayOCI_NLS_ABDAYNAME5
: Native abbreviated name for FridayOCI_NLS_ABDAYNAME6
: Native abbreviated name for SaturdayOCI_NLS_ABDAYNAME7
: Native abbreviated name for SundayOCI_NLS_MONTHNAME1
: Native name for JanuaryOCI_NLS_MONTHNAME2
: Native name for FebruaryOCI_NLS_MONTHNAME3
: Native name for MarchOCI_NLS_MONTHNAME4
: Native name for AprilOCI_NLS_MONTHNAME5
: Native name for MayOCI_NLS_MONTHNAME6
: Native name for JuneOCI_NLS_MONTHNAME7
: Native name for JulyOCI_NLS_MONTHNAME8
: Native name for AugustOCI_NLS_MONTHNAME9
: Native name for SeptemberOCI_NLS_MONTHNAME10
: Native name for OctoberOCI_NLS_MONTHNAME11
: Native name for NovemberOCI_NLS_MONTHNAME12
: Native name for DecemberOCI_NLS_ABMONTHNAME1
: Native abbreviated name for JanuaryOCI_NLS_ABMONTHNAME2
: Native abbreviated name for FebruaryOCI_NLS_ABMONTHNAME3
: Native abbreviated name for MarchOCI_NLS_ABMONTHNAME4
: Native abbreviated name for AprilOCI_NLS_ABMONTHNAME5
: Native abbreviated name for MayOCI_NLS_ABMONTHNAME6
: Native abbreviated name for JuneOCI_NLS_ABMONTHNAME7
: Native abbreviated name for JulyOCI_NLS_ABMONTHNAME8
: Native abbreviated name for AugustOCI_NLS_ABMONTHNAME9
: Native abbreviated name for SeptemberOCI_NLS_ABMONTHNAME10
: Native abbreviated name for OctoberOCI_NLS_ABMONTHNAME11
: Native abbreviated name for NovemberOCI_NLS_ABMONTHNAME12
: Native abbreviated name for DecemberOCI_NLS_YES
: Native string for affirmative responseOCI_NLS_NO
: Native negative responseOCI_NLS_AM
: Native equivalent string of AMOCI_NLS_PM
: Native equivalent string of PMOCI_NLS_AD
: Native equivalent string of ADOCI_NLS_BC
: Native equivalent string of BCOCI_NLS_DECIMAL
: Decimal characterOCI_NLS_GROUP
: Group separatorOCI_NLS_DEBIT
: Native symbol of debitOCI_NLS_CREDIT
: Native symbol of creditOCI_NLS_DATEFORMAT
: Oracle date formatOCI_NLS_INT_CURRENCY
: International currency symbolOCI_NLS_DUAL_CURRENCY
: Dual currency symbolOCI_NLS_LOC_CURRENCY
: Locale currency symbolOCI_NLS_LANGUAGE
: Language nameOCI_NLS_ABLANGUAGE
: Abbreviation for language nameOCI_NLS_TERRITORY
: Territory nameOCI_NLS_CHARACTER_SET
: Character set nameOCI_NLS_LINGUISTIC_NAME
: Linguistic sort nameOCI_NLS_CALENDAR
: Calendar nameOCI_NLS_WRITING_DIR
: Language writing directionOCI_NLS_ABTERRITORY
: Territory abbreviationOCI_NLS_DDATEFORMAT
: Oracle default date formatOCI_NLS_DTIMEFORMAT
: Oracle default time formatOCI_NLS_SFDATEFORMAT
: Local date formatOCI_NLS_SFTIMEFORMAT
: Local time formatOCI_NLS_NUMGROUPING
: Number grouping fieldsOCI_NLS_LISTSEP
: List separatorOCI_NLS_MONDECIMAL
: Monetary decimal characterOCI_NLS_MONGROUP
: Monetary group separatorOCI_NLS_MONGROUPING
: Monetary grouping fieldsOCI_NLS_INT_CURRENCYSEP
: International currency separatorReturns
OCI_SUCCESS
, OCI_INVALID_HANDLE
, or OCI_ERROR
Purpose
Obtains numeric language information from the OCI environment handle and puts it into an output number variable.
Syntax
sword OCINlsNumericInfoGet ( dvoid *hndl, OCIError *errhp, sb4 *val, ub2 item );
Parameters
The OCI error handle. If there is an error, then it is recorded in errhp
and the function returns a NULL
pointer. Diagnostic information can be obtained by calling OCIErrorGet()
.
Pointer to the output number variable. If the function returns OCI_SUCCESS
, then the parameter contains the requested globalization support numeric information.
It specifies which item to get from the OCI environment handle and can be one of following values:
OCI_NLS_CHARSET_MAXBYTESZ
: Maximum character byte size for OCI environment or session handle character set
OCI_NLS_CHARSET_FIXEDWIDTH
: Character byte size for fixed-width character set; 0
for variable-width character set
Returns
OCI_SUCCESS
, OCI_INVALID_HANDLE
, or OCI_ERROR