|Oracle Call Interface Programmer's Guide
Release 2 (9.2)
Part Number A96584-01
OCI Relational Functions, 6 of 38
Creates and initializes an environment handle for OCI functions to work under. It is an enhanced version of the
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 );
A pointer to an environment handle whose encoding setting is specified by
mode. The setting will be inherited by statement handles derived from
Specifies initialization of the mode. Valid modes are:
OCIEnvCallback. The default behavior is to allow calling of
OCIEnvCallbackat the time that the environment is created.
Specifies the user-defined context for the memory callback routines.
Specifies the user-defined memory allocation function. If
mode is OCI_THREADED, this memory allocation routine must be thread-safe.
Specifies the context pointer for the user-defined memory allocation function.
Specifies the size of memory to be allocated by the user-defined memory allocation function.
Specifies the user-defined memory re-allocation function. If the mode is OCI_THREADED, this memory allocation routine must be thread safe.
Specifies the context pointer for the user-defined memory reallocation function.
Pointer to memory block.
Specifies the new size of memory to be allocated
Specifies the user-defined memory free function. If mode is OCI_THREADED, this memory free routine must be thread-safe.
Specifies the context pointer for the user-defined memory free function.
Pointer to memory to be freed
Specifies the amount of user memory to be allocated for the duration of the environment.
Returns a pointer to the user memory of size
xtramemsz allocated by the call for the user.
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.
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.
OCI_SUCCESS - environment handle has been successfully created.
OCI_ERROR - an error occurred.
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
ncharset is equivalent to
OCIEnvCreate() with both OCI_UTF16 and OCI_NEW_LENGTH_SEMANTICS modes set.
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:
This function enables you to set
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
This function sets nonzero
ncharset as client side database and national character sets, replacing the ones specified by NLS_LANG and NLS_NCHAR. When
ncharset are 0, it behaves exactly the same as
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
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
For more information about the