OCIEnvNlsCreate()

Purpose

Creates and initializes an environment handle for OCI functions to work under. It is an enhanced version of the OCIEnvCreate() function.

Syntax

sword OCIEnvNlsCreate   ( OCIEnv        **envhpp,
                          ub4           mode,
                          dvoid         *ctxp,
                          dvoid         *(*malocfp)
                                             (dvoid *ctxp,
                                              size_t size),
                          dvoid         *(*ralocfp)
                                             (dvoid *ctxp,
                                              dvoid *memptr,
                                              size_t newsize),
                          void          (*mfreefp)
                                             (dvoid *ctxp,
                                              dvoid *memptr))
                          size_t        xtramemsz,
                          dvoid         **usrmempp
                          ub2           charset,
                          ub2           ncharset );

Parameters

envhpp (OUT)

A pointer to an environment handle whose encoding setting is specified by mode. The setting will be inherited by statement handles derived from envhpp.

mode (IN)

Specifies initialization of the mode. Valid modes are:

• OCI_DEFAULT- the default value, which is non-UTF-16 encoding.
• OCI_THREADED - uses threaded environment. Internal data structures not exposed to the user are protected from concurrent accesses by multiple threads.
• OCI_OBJECT - uses object features.
• OCI_SHARED - utilizes shared data structures.
• OCI_EVENTS - utilizes publish-subscribe notifications.
• OCI_NO_UCB - suppresses the calling of the dynamic callback routine OCIEnvCallback. The default behavior is to allow calling of OCIEnvCallback at the time that the environment is created.

  See Also: "Dynamic Callback Registrations"

• OCI_ENV_NO_MUTEX - no mutexing in this mode. All OCI calls done on the environment handle, or on handles derived from the environment handle, must be serialized.

ctxp (IN)

Specifies the user-defined context for the memory callback routines.

malocfp (IN)

Specifies the user-defined memory allocation function. If mode is OCI_THREADED, this memory allocation routine must be thread-safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory allocation function.

size (IN)

Specifies the size of memory to be allocated by the user-defined memory allocation function.

ralocfp (IN)

Specifies the user-defined memory re-allocation function. If the mode is OCI_THREADED, this memory allocation routine must be thread safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory reallocation function.

memp (IN)

Pointer to memory block.

newsize (IN)

Specifies the new size of memory to be allocated

mfreefp (IN)

Specifies the user-defined memory free function. If mode is OCI_THREADED, this memory free routine must be thread-safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory free function.

memptr (IN)

Pointer to memory to be freed

xtramemsz (IN)

Specifies the amount of user memory to be allocated for the duration of the environment.

usrmempp (OUT)

Returns a pointer to the user memory of size xtramemsz allocated by the call for the user.

charset (IN)

The client-side character set for the current environment handle. If it is 0, the NLS_LANG setting is used. OCI_UTF16ID is a valid setting; it is used by the metadata and the CHAR data.

ncharset (IN)

The client-side national character set for the current environment handle. If it is 0, NLS_NCHAR setting is used. OCI_UTF16ID is a valid setting; it is used by the NCHAR data.

Returns

OCI_SUCCESS - environment handle has been successfully created.

OCI_ERROR - an error occurred.

Comments

This call creates an environment for all the OCI calls using the modes specified by the user. OCI_UTF16 is not a supported mode for this function. OCIEnvNlsCreate() with OCI_UTF16ID passed as both charset and ncharset is equivalent to OCIEnvCreate() with both OCI_UTF16 and OCI_NEW_LENGTH_SEMANTICS modes set.

After using OCIEnvNlsCreate() to create the environment handle, the actual lengths and returned lengths of bind and define handles are always in number of bytes. This applies to the following calls:

• OCIBindByName()
• OCIBindByPos()
• OCIBindDynamic()
• OCIDefineByPos()
• OCIDefineDynamic()

This function enables you to set charset and ncharset ids at environment creation time. It is an enhanced version of the OCIEnvCreate() function. Consequently, in this function, OCI_UTF16 mode is not supported, but its functionality can be achieved by setting OCI_UTF16ID as both charset and ncharset.

This function sets nonzero charset and ncharset as client side database and national character sets, replacing the ones specified by NLS_LANG and NLS_NCHAR. When charset and ncharset are 0, it behaves exactly the same as OCIEnvCreate(). Specifically, charset controls the encoding for metadata and data with implicit form attribute and ncharset controls the encoding for data with SQLCS_NCHAR form attribute.

Although OCI_UTF16ID can be set by OCIEnvNlsCreate(), it cannot be set in NLS_LANG or NLS_NCHAR. To access the character set ids in NLS_LANG and NLS_NCHAR, use OCINlsEnvironmentVariableGet().

This call returns an environment handle which is then used by the remaining OCI functions. There can be multiple environments in OCI, each with its own environment modes. This function also performs any process level initialization if required by any mode. For example if the user wants to initialize an environment as OCI_THREADED, then all libraries that are used by OCI are also initialized in the threaded mode.

If you are writing a DLL or a shared library using OCI library then this call should definitely be used instead of OCIInitialize() and OCIEnvInit() calls.

Related Functions

OCIHandleAlloc(), OCIHandleFree(), OCITerminate(), OCINlsEnvironmentVariableGet()