OCI Locale Functions

31.2 OCI Locale Functions

Lists and describes OCI Locale Functions.

Table 31-2 lists the OCI locale functions that are described in this section.

An Oracle locale consists of language, territory, and character set definitions. The locale determines conventions such as day and month names, and 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 31-2 OCI Locale Functions

Function	Purpose
OCINlsCharSetIdToName()	Return the Oracle Database character set name from the specified character set ID
OCINlsCharSetNameToId()	Return the Oracle Database character set ID for the specified Oracle Database character set name
OCINlsEnvironmentVariableGet()	Return the character set ID from `NLS_LANG` or the national character set ID from `NLS_NCHAR`
OCINlsGetInfo()	Copy locale information from an OCI environment or user session handle into an array pointed to by the destination buffer within a specified size
OCINlsNumericInfoGet()	Copy numeric language information from the OCI environment or user session handle into an output number variable

31.2.1 OCINlsCharSetIdToName()

Returns the Oracle Database character set name from the specified character set ID.

Purpose

Returns the Oracle Database character set name from the specified character set ID.

Syntax

sword OCINlsCharSetIdToName ( void      *hndl, 
                              OraText   *buf, 
                              size_t     buflen
                              ub2        id );

Parameters

hndl (IN/OUT): OCI environment or user session handle. If the handle is invalid, then the function returns OCI_INVALID_HANDLE.
buf (OUT): Points to the destination buffer. If the function returns OCI_SUCCESS, then the parameter contains a NULL-terminated string for the character set name.
buflen (IN): The size of the destination buffer. The recommended size is OCI_NLS_MAXBUFSZ to guarantee storage for an Oracle Database 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.
id (IN): Oracle Database character set ID.

Returns

OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.

31.2.2 OCINlsCharSetNameToId()

Returns the Oracle Database character set ID for the specified Oracle Database character set name.

Purpose

Returns the Oracle Database character set ID for the specified Oracle Database character set name.

Syntax

ub2 OCINlsCharSetNameToId ( void            *hndl, 
                            const OraText   *name );

Parameters

hndl (IN/OUT): OCI environment or user session handle. If the handle is invalid, then the function returns zero.
name (IN): Pointer to a NULL-terminated Oracle Database 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.

31.2.3 OCINlsEnvironmentVariableGet()

Returns the character set ID from NLS_LANG or the national character set ID from NLS_NCHAR.

Purpose

Returns the character set ID from NLS_LANG or the national character set ID from NLS_NCHAR.

Syntax

sword OCINlsEnvironmentVariableGet ( void       *val,
                                     size_t      size,
                                     ub2         item,
                                     ub2         charset, 
                                     size_t     *rsize );

Parameters

val (IN/OUT)

Returns a value of a globalization support environment variable, such as the NLS_LANG character set ID or the NLS_NCHAR character set ID.

size (IN)

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. For numeric data, this argument is ignored.

item (IN)

Specifies one of these values to get from the globalization support environment variable:

OCI_NLS_CHARSET_ID: NLS_LANG character set ID in ub2 data type; if NLS_LANG is not set, the default character set ID is returned (ASCII).
OCI_NLS_NCHARSET_ID: NLS_NCHAR character set ID in ub2 data type; if NLS_NCHAR is not set, the value of OCI_NLS_CHARSET_ID is returned instead.

charset (IN): 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. For numeric data, this argument is ignored.
rsize (OUT): The length of the return value in bytes.

Comments

To allow for future enhancements of this function (to retrieve other values from environment variables) the data type of the output val is a pointer to void. 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_ID and OCI_ATTR_ENV_NCHARSET_ID, respectively.

Returns

OCI_SUCCESS; or OCI_ERROR.

Related Topics

OCIEnvNlsCreate()

31.2.4 OCINlsGetInfo()

Copy locale information from an OCI environment or user session handle into an array pointed to by the destination buffer within a specified size.

Purpose

Obtains locale information from an OCI environment or user session handle to an array pointed to by the destination buffer within a specified size.

Syntax

sword OCINlsGetInfo ( void        *hndl, 
                      OCIError    *errhp, 
                      OraText     *buf, 
                      size_t       buflen, 
                      ub2          item );

Parameters

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, then it is recorded in errhp, and the function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet().

buf (OUT)

Pointer to the destination buffer. Returned strings are terminated by a NULL character.

buflen (IN)

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 must 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().

item (IN)

Specifies which item in the OCI environment handle to return. It can be one of these 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: Native string 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 Database date format
OCI_NLS_INT_CURRENCY: International currency symbol
OCI_NLS_DUAL_CURRENCY: Dual 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 sort name
OCI_NLS_CALENDAR: Calendar name
OCI_NLS_WRITING_DIR: Language writing direction
OCI_NLS_ABTERRITORY: Territory abbreviation
OCI_NLS_DDATEFORMAT: Oracle Database default date format
OCI_NLS_DTIMEFORMAT: Oracle Database default time format
OCI_NLS_SFDATEFORMAT: Local date format
OCI_NLS_SFTIMEFORMAT: Local time format
OCI_NLS_NUMGROUPING: Number grouping fields
OCI_NLS_LISTSEP: List separator
OCI_NLS_MONDECIMAL: Monetary decimal character
OCI_NLS_MONGROUP: Monetary group separator
OCI_NLS_MONGROUPING: Monetary grouping fields
OCI_NLS_INT_CURRENCYSEP: International currency separator

Returns

OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.

Related Topics

OCIErrorGet()

31.2.5 OCINlsNumericInfoGet()

Copy numeric language information from the OCI environment or user session handle into an output number variable.

Purpose

Obtains numeric language information from the OCI environment or user session handle and puts it into an output number variable.

Syntax

sword OCINlsNumericInfoGet ( void        *hndl, 
                             OCIError    *errhp, 
                             sb4         *val, 
                             ub2          item );

Parameters

hndl (IN/OUT): The OCI environment or user session handle. If the handle is invalid, it returns OCI_INVALID_HANDLE.
errhp (IN/OUT): 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().
val (OUT): Pointer to the output number variable. If the function returns OCI_SUCCESS, then the parameter contains the requested globalization support numeric information.
item (IN): 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.

Related Topics

OCIErrorGet()