Deprecated Initialize Functions

Table E-2 lists the deprecated Initialize functions that are described in this section.

Table E-2 Deprecated Initialize Functions

Function Purpose

OCIEnvInit()

Initialize an environment handle.

OCIInitialize()

Initialize OCI process environment.

OCIEnvInit()

Purpose

Allocates and initializes an OCI environment handle. This function is deprecated.

Syntax

sword OCIEnvInit ( OCIEnv    **envhpp,
                   ub4       mode,
                   size_t    xtramemsz,
                   void      **usrmempp );

Parameters

envhpp (OUT)

A pointer to a handle to the environment.

mode (IN)

Specifies initialization of an environment mode. Valid modes are:

  • OCI_DEFAULT

  • OCI_ENV_NO_UCB

In OCI_DEFAULT mode, the OCI library always mutexes handles.

The OCI_ENV_NO_UCB mode is used to suppress the calling of the dynamic callback routine OCIEnvCallback() at environment initialization time. The default behavior is to allow such a call to be made.

See Also:

"Dynamic Callback Registrations"
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 for the duration of the environment.

Comments

Note:

Use OCIEnvCreate() instead of the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls are supported for backward compatibility.

This call allocates and initializes an OCI environment handle. No changes are made to an initialized handle. If OCI_ERROR or OCI_SUCCESS_WITH_INFO is returned, you can use the environment handle to obtain Oracle-specific errors and diagnostics.

This call is processed locally, without a server round-trip.

The environment handle can be freed using OCIHandleFree().

See Also:

"User Memory Allocation" for more information about the xtramemsz parameter and user memory allocation

Related Functions

OCIHandleAlloc(), OCIHandleFree(), OCIEnvCreate(), OCITerminate()

OCIInitialize()

Purpose

Initializes the OCI process environment. This function is deprecated.

Syntax

sword OCIInitialize ( ub4           mode,
                      const void    *ctxp, 
                      const void    *(*malocfp) 
                                    ( void  *ctxp,
                                        size_t size ),
                      const void    *(*ralocfp)
                                    ( void  *ctxp,
                                       void  *memptr,
                                       size_t newsize ),
                      const void    (*mfreefp)
                                    ( void  *ctxp,
                                       void  *memptr ));

Parameters

mode (IN)

Specifies initialization of the mode. The valid modes are:

  • OCI_DEFAULT - Default mode.

  • OCI_THREADED - Threaded environment. In this mode, internal data structures not exposed to the user are protected from concurrent accesses by multiple threads.

  • OCI_OBJECT - Uses object features.

  • OCI_EVENTS - Uses publish-subscribe notifications.

ctxp (IN)

User-defined context for the memory callback routines.

malocfp (IN)

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

ctxp (IN/OUT)

Context pointer for the user-defined memory allocation function.

size (IN)

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

ralocfp (IN)

User-defined memory reallocation function. If mode is OCI_THREADED, this memory allocation routine must be thread-safe.

ctxp (IN/OUT)

Context pointer for the user-defined memory reallocation function.

memptr (IN/OUT)

Pointer to memory block.

newsize (IN)

New size of memory to be allocated.

mfreefp (IN)

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

ctxp (IN/OUT)

Context pointer for the user-defined memory free function.

memptr (IN/OUT)

Pointer to memory to be freed.

Comments

Note:

Use OCIEnvCreate() instead of the deprecated OCIInitialize() call. The OCIInitialize() call is supported for backward compatibility.

This call initializes the OCI process environment. OCIInitialize() must be invoked before any other OCI call.

This function provides the ability for the application to define its own memory management functions through callbacks. If the application has defined such functions (that is, memory allocation, memory reallocation, memory free), they should be registered using the callback parameters in this function.

These memory callbacks are optional. If the application passes NULL values for the memory callbacks in this function, the default process memory allocation mechanism is used.

See Also:

Example

The following statement shows an example of how to call OCIInitialize() in both threaded and object mode, with no user-defined memory functions:

OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (void  *)0,
     (void  * (*)()) 0, (void  * (*)()) 0,  (void (*)()) 0 );

Related Functions

OCIHandleAlloc(), OCIHandleFree(), OCIEnvCreate(), OCITerminate()