OCI Locale Functions

Lists and describes OCI Locale Functions.

Table 22-3 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 22-3 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

OCINlsCharSetIdToName()

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.

OCINlsCharSetNameToId()

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.

OCINlsEnvironmentVariableGet()

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

  • OCI_NLS_NCHARSET_ID: NLS_NCHAR character set ID in ub2 data type

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

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 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 and OCI_ATTR_ENV_NCHARSET, respectively.

Returns

OCI_SUCCESS; or OCI_ERROR.

Related Functions

OCIEnvNlsCreate()

OCINlsGetInfo()

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.

OCINlsNumericInfoGet()

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.