OCIInitialize()

Purpose

Initializes the OCI process environment.

Syntax

sword OCIInitialize ( 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 _*/));

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 - will use object features.
• OCI_SHARED - will utilize shared data structures.
• OCI_EVENTS - will utilize publish-subscribe notifications.

ctxp (IN)

User defined context for the memory call back 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 re-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 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

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 re-allocation, 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.

Shared Data Structures Mode

When a SQL statement is processed, certain underlying data is associated with the statement. This data includes information about statement text and bind data, as well as define and describe information for queries. This data remains the same from one execution of a statement to another, even if the statement is executed by different users.

When an OCI application is initialized in OCI_SHARED mode, common statement data is shared between multiple statement handles, thus providing memory savings for the application. This savings may be particularly valuable for applications which create multiple statement handles which execute the same SQL statement on different users' sessions, either on the same or multiple connections.

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, (dvoid *)0,
     (dvoid * (*)()) 0, (dvoid * (*)()) 0,  (void (*)()) 0 );

Related Functions

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