OCIEnvCreate()

Purpose

Creates and initializes an environment for OCI functions to work under.

Syntax

sword OCIEnvCreate   ( OCIEnv        **envhpp,
                       ub4           mode,
                       CONST dvoid   *ctxp,
                       CONST dvoid   *(*malocfp)
                                     (dvoid *ctxp,
                                      size_t size),
                       CONST dvoid   *(*ralocfp)
                                     (dvoid *ctxp,
                                      dvoid *memptr,
                                      size_t newsize),
                       CONST void    (*mfreefp)
                                     (dvoid *ctxp,
                                      dvoid *memptr))
                       size_t         xtramemsz,
                       dvoid          **usrmempp );

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_UTF16 - the environment handle and handles inherited from it assume UTF-16 encoding.
• 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.
• OCI_NEW_LENGTH_SEMANTICS - byte-length semantics is used consistently for all handles, regardless of character sets.

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.

Comments

This call creates an environment for all the OCI calls using the modes specified by the user.

This call is invoked before any other OCI calls, so it sets up any Unicode support in the environment handle, at the top-most level. The Unicode setting is made by the mode argument. Set mode to OCI_UTF16.

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

Related Functions

OCIHandleAlloc(),OCIHandleFree(),OCIEnvInit(), OCIEnvNlsCreate(),OCITerminate()