OCINlsEnvironmentVariableGet()

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

val (IN/OUT)

Returns a value of an NLS 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. In case of numeric data, this argument is ignored.

item (IN)

Specifies which item to get from the NLS environment variable, one of following values:

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, NLS_LANG will be used. OCI_UTF16ID is a valid value for this argument. In the case of numeric data, this argument is ignored.

rsize (OUT)

The length of the return value in bytes.

Returns

OCI_SUCCESS - the function has finished successfully.

OCI_ERROR - an error occurred.

Comments

Following NLS convention, the national character set id will be the same as the character set id if NLS_NCHAR is not set. If NLS_LANG is not set, the default character set id will be 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 will not be NULL-terminated.

Note that the function does not take an environment handle, so the character set id and the national character set id it returns are thevalues specified in NLS_LANG and NLS_NCHAR, instead of the values saved in the OCI environment handle. To get the character set ids actually used by the OCI environment handle, call OCIAttrGet() for OCI_ATTR_ENV_CHARSET and OCI_ATTR_ENV_NCHARSET respectively.

Related Functions

OCIEnvNlsCreate()