Skip Headers
Oracle® Call Interface Programmer's Guide
11g Release 1 (11.1)

B28395-12
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

Connect, Authorize, and Initialize Functions

This section describes the OCI connect, authorize, and initialize functions.

Table 16-2 Connect, Authorize, and Initialize Functions  

Function Purpose

OCIAppCtxClearAll()

To clear all attribute-value information in a namespace of an application context.

OCIAppCtxSet()

To set an attribute and its associated value in a namespace of an application context.

OCIConnectionPoolCreate()

Initializes the connection pool.

OCIConnectionPoolDestroy()

Destroys the connection pool.

OCIDBShutdown()

Shuts down the Oracle Database

OCIDBStartup()

Starts an Oracle Database instance

OCIEnvCreate()

Creates and initializes an OCI environment.

OCIEnvInit()

Initialize an environment handle.

OCIEnvNlsCreate()

Creates and initializes an environment for OCI functions to work under. Allows you to set character set id and national character set id at environment creation time.

OCIInitialize()

Initialize OCI process environment.

OCILogon()

Simplified single-session logon.

OCILogon2()

This function is used to create a logon session in various modes.

OCIServerAttach()

Attach to a server; initialize server context handle.

OCIServerDetach()

Detach from a server; uninitialize server context handle.

OCISessionBegin()

Authenticate a user.

OCISessionEnd()

Terminate a user session.

OCISessionGet()

Get a session from a session pool.

OCISessionPoolCreate()

Initializes a session pool.

OCISessionPoolDestroy()

Destroys a session pool.

OCISessionRelease()

Releases a session.

OCITerminate()

Detaches from a shared memory subsystem.


OCIAppCtxClearAll()

Purpose

To clear all attribute-value information in a namespace of an application context.

Syntax

sword OCIAppCtxClearAll ( void      *sesshndl,
                          void      *nsptr, 
                          ub4       nsptrlen,
                          OCIError  *errhp,
                          ub4       mode ;

Parameters

sesshndl (IN/OUT)

Pointer to a session handle.

nsptr (IN)

Pointer to namespace string (currently only CLIENTCONTEXT).

nsptrlen (IN)

Length of the namespace string.

mode (IN)

Mode (OCI_DEFAULT is the default).

errhp (OUT)

An error handle which can be passed to OCIErrorGet().

Returns

Returns error number.

Comments

This will clean up the context information on the server side during the next call to the server. This namespace information is cleared from the session handle once the information has been sent to the server and must be set up again if needed.

Related Functions

OCIAppCtxSet()

OCIAppCtxSet()

Purpose

To set an attribute and its associated value in a namespace of an application context.

Syntax

sword OCIAppCtxSet ( void      *sesshndl,
                     void      *nsptr,
                     ub4       nsptrlen,
                     void      *attrptr,
                     ub4       attrptrlen,
                     void      *valueptr,
                     ub4       valueptrlen,
                     OCIError  *errhp, 
                     ub4       mode );

Parameters

sesshndl (IN/OUT)

Pointer to a session handle.

nsptr (IN)

Pointer to namespace string (currently only CLIENTCONTEXT).

nsptrlen (IN)

Length of the namespace string.

attrptr (IN)

Pointer to attribute string.

attrptrlen (IN)

The length of the string pointed to by attrptr.

valueptr (IN)

Pointer to value string.

valueptrlen (IN)

The length of the string pointed to by valueptr.

mode (IN)

Mode (OCI_DEFAULT is the default.

errhp (OUT)

An error handle which can be passed to OCIErrorGet().

Returns

Returns error number

Comments

The information set on the session handle is sent to the server during the next call to the server.

This information is cleared from the session handle once the information has been sent to the server and must be set up again if needed.

Related Functions

OCIAppCtxClearAll()

OCIConnectionPoolCreate()

Purpose

Initializes the connection pool.

Syntax

sword OCIConnectionPoolCreate ( OCIEnv         *envhp,
                                OCIError       *errhp, 
                                OCICPool       *poolhp,
                                OraText        **poolName,
                                sb4            *poolNameLen,
                                const OraText  *dblink, 
                                sb4            dblinkLen,
                                ub4            connMin,
                                ub4            connMax,
                                ub4            connIncr,
                                const OraText  *poolUsername,
                                sb4            poolUserLen,
                                const OraText  *poolPassword,
                                sb4            poolPassLen,
                                ub4            mode );

Parameters

envhp (IN)

A pointer to the environment where the connection pool is to be created

errhp (IN/OUT)

An error handle which can be passed to OCIErrorGet().

poolhp (IN)

An allocated pool handle.

poolName (OUT)

The name of the connection pool connected to.

poolNameLen (OUT)

The length of the string pointed to by poolName.

dblink (IN)

Specifies the database (server) to connect to.

dblinkLen (IN)

The length of the string pointed to by dblink.

connMin (IN)

Specifies the minimum number of connections in the connection pool. Valid values are 0 and higher.

These number of connections are opened to the server by OCIConnectionPoolCreate(). After this, connections are opened only when necessary. Generally, it should be set to the number of concurrent statements the application is planning or expecting to run.

connMax (IN)

Specifies the maximum number of connections that can be opened to the database. Once this value is reached, no more connections are opened. Valid values are 1 and higher.

connIncr (IN)

Allows the application to set the next increment for connections to be opened to the database if the current number of connections are less than connMax. Valid values are 0 and higher.

poolUsername (IN)

Connection pooling requires an implicit primary session and this attribute provides a user name for that session.

poolUserLen (IN)

The length of poolUsername.

poolPassword (IN)

The password for the user name poolUsername.

poolPassLen (IN)

The length of poolPassword.

mode (IN)

The modes supported are

  • OCI_DEFAULT

  • OCI_CPOOL_REINITIALIZE.

Ordinarily, OCIConnectionPoolCreate() will be called with mode set to OCI_DEFAULT.

If you wish to change the pool attributes dynamically (for example: change the connMin, connMax, and connIncr parameters), call OCIConnectionPoolCreate() with mode set to OCI_CPOOL_REINITIALIZE. When this is done, the other parameters are ignored.

Comments

The OUT parameters poolName and poolNameLen will contain values to be used in subsequent OCIServerAttach() and OCILogon2() calls in place of the database name and the database name length arguments.

OCIConnectionPoolDestroy()

Purpose

Destroys the connection pool.

Syntax

sword OCIConnectionPoolDestroy ( OCICPool     *poolhp,
                                 OCIError     *errhp, 
                                 ub4          mode );

Parameters

poolhp (IN)

A pool handle for which a pool has been created.

errhp (IN/OUT)

An error handle which can be passed to OCIErrorGet().

mode (IN)

Currently, this function will support only the OCI_DEFAULT mode.

Related Functions

OCIConnectionPoolCreate()

OCIDBShutdown()

Purpose

Shuts down an Oracle Database instance.

Syntax

sword OCIDBShutdown ( OCISvcCtx     *svchp,
                      OCIError      *errhp,
                      OCIAdmin      *admhp,
                      ub4           mode);

Parameters

svchp (IN)

A handle to a service context. There must be a valid server handle and a valid user handle set in svchp.

errhp (IN/OUT)

An error handle which can be passed to OCIErrorGet() for diagnostic information in the event of an error.

admhp (IN) - Optional

An instance administration handle. Currently not used; pass (OCIAdmin *)0.

mode (IN)

OCI_DEFAULT - Further connects are prohibited. Waits for users to disconnect from the database.

OCI_DBSHUTDOWN_TRANSACTIONAL - Further connects are prohibited and no new transactions are allowed. Waits for active transactions to complete.

OCI_DBSHUTDOWN_TRANSACTIONAL_LOCAL - Further connects are prohibited and no new transactions are allowed. Waits only for local transactions to complete.

OCI_DBSHUTDOWN_IMMEDIATE - Does not wait for current calls to complete or users to disconnect from the database. All uncommitted transactions are terminated and rolled back.

OCI_DBSHUTDOWN_FINAL - Shuts down the database. Should be used only in the second call to OCIDBShutdown() after the database is closed and dismounted.

OCI_DBSHUTDOWN_ABORT - Does not wait for current calls to complete or users to disconnect from the database. All uncommitted transactions are terminated and are not rolled back. This is the fastest possible way to shut down the database, but the next database startup may require instance recovery. Therefore, this option should be used only in unusual circumstances: if a background process terminates abnormally.

Comments

To do a shut down, you must be connected to the database as SYSOPER, or SYSDBA. You cannot be connected to a shared server via a dispatcher. When shutting down in any mode other than OCI_DBSHUTDOWN_ABORT, the following procedure should be followed:

  1. Call OCIDBShutdown() in OCI_DEFAULT, OCI_DBSHUTDOWN_TRANSACTIONAL, OCI_DBSHUTDOWN_TRANSACTIONAL_LOCAL, or OCI_DBSHUTDOWN_IMMEDIATE mode to prohibit further connects.

  2. Issue the necessary ALTER DATABASE commands to close and dismount the database.

  3. Call OCIDBShutdown() in OCI_DBSHUTDOWN_FINAL mode to shut down the instance.

Related Functions

OCIAttrSet(), OCIDBStartup()

OCIDBStartup()

Purpose

Starts an Oracle Database instance.

Syntax

sword OCIDBStartup ( OCISvcCtx     *svchp,
                     OCIError      *errhp,
                     OCIAdmin      *admhp,
                     ub4           mode,
                     ub4           flags);

Parameters

svchp (IN)

A handle to a service context. There must be a valid server handle and user handle set in svchp

errhp (IN/OUT)

An error handle which can be passed to OCIErrorGet() for diagnostic information in the event of an error.

admhp (IN) - Optional

An instance administration handle. Use to pass additional arguments to the startup call, or pass (OCIAdmin *)0 if you do not set OCI_ATTR_ADMIN_PFILE.

mode (IN)

OCI_DEFAULT - This is the only supported mode. It starts up the instance, but does not mount or open the database. Same as STARTUP NOMOUNT.

flags (IN)

OCI_DEFAULT - Allows database access to all users.

OCI_DBSTARTUPFLAG_RESTRICT - Allows database access only to users with both the CREATE SESSION and RESTRICTED SESSION privileges (normally, the DBA).

OCI_DBSTARTUPFLAG_FORCE - Shuts down a running instance (if there is any) using ABORT before starting a new one. This mode should be used only in unusual circumstances.

Comments

You must be connected to the database as SYSOPER or SYSDBA in OCI_PRELIM_AUTH mode. You cannot be connected to a shared server via a dispatcher (that is, when you restart a running instance with OCI_DBSTARTUPFLAG_FORCE). To use a client-side parameter file (pfile), OCI_ATTR_ADMIN_PFILE must be set in the administration handle; otherwise, a server-side parameter file (spfile) will be used. A call to OCIDBStartup() starts up one instance on the server.

OCIEnvCreate()

Purpose

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

Syntax

sword OCIEnvCreate   ( OCIEnv        **envhpp,
                       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))
                       size_t         xtramemsz,
                       void           **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_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.

  • OCI_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.

  • OCI_SUPPRESS_NLS_VALIDATION - Suppresses NLS character validation; NLS character validation suppression is on by default beginning with Oracle Database 11g Release 1 (11.1). Use OCI_ENABLE_NLS_VALIDATION to enable NLS character validation. See Comments for more information.

  • OCI_NCHAR_LITERAL_REPLACE_ON - turns on N' substitution.

  • OCI_NCHAR_LITERAL_REPLACE_OFF - turns off N' substitution. If neither this mode or OCI_NCHAR_LITERAL_REPLACE_ON is used, the substitution is determined by the environment variable ORA_NCHAR_LITERAL_REPLACE, which can be set to TRUE or FALSE. When it is set to TRUE, the replacement will be turned on, otherwise it will be turned off, which is the default setting in OCI.

  • OCI_ENABLE_NLS_VALIDATION - Enables NLS character validation. See Comments for more information.

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.

Note:

This call should be invoked before any other OCI call and should be used instead of the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls will be supported for backward compatibility.

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 N' substitution is turned on, OCIStmtPrepare() or OCIStmtPrepare2() will perform the N' substitution on the SQL text and store the resulting SQL text in the statement handle. Thus, if the application uses OCI_ATTR_STATEMENT to retrieve the SQL text from the OCI statement handle, the modified SQL text, instead of the original SQL text, will be returned.

To turn on N' substitution in ksh shell:

export ORA_NCHAR_LITERAL_REPLACE=TRUE

To turn on N' substitution in csh shell:

setenv ORA_NCHAR_LITERAL_REPLACE TRUE

If a remote database is of a release before 10.2, N' substitution is not done.

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.

See Also:

For more information about the xtramemsz parameter and user memory allocation, refer to "User Memory Allocation"

Regarding OCI_SUPPRESS_NLS_VALIDATION and OCI_ENABLE_NLS_VALIDATION modes, by default, when client and server character sets are identical, and client and server releases are both Oracle Database 11g Release 1 (11.1) or higher, OCI does not validate character data in the interest of better performance. This means that if the application inserts a character string with partial multibyte characters (for example, at the end of a bind variable), then such strings could get persisted in the database as is.

Note that if either the client or the server release is older than Oracle Database 11g Release 1 (11.1), then OCI does not allow partial characters.

The OCI_ENABLE_NLS_VALIDATION mode, which was the default until Oracle Database 10g Release 2 (10.2), ensures that partial multibyte characters are not persisted in the database (when client and server character sets are identical). If the application can produce partial multibyte characters, and if the application can run in an environment where the client and server character sets are identical, then Oracle recommends using the OCI_ENABLE_NLS_VALIDATION mode explicitly in order to ensure that such partial characters get stripped out.

Example

OCIEnv *envhp;
...
/* Create a thread-safe OCI environment with N' substitution turned on.  */
if(OCIEnvCreate((OCIEnv **)&envhp,
         (ub4)OCI_THREADED | OCI_NCHAR_LITERAL_REPLACE_ON,
         (void  *)0, (void  * (*)(void  *, size_t))0,
         (void  * (*)(void  *, void  *, size_t))0,
         (void (*)(void  *, void  *))0,
         (size_t)0, (void  **)0))
{
  printf("Failed: OCIEnvCreate()\n");
  return 1;
}
...

OCIEnvInit()

Purpose

Allocates and initializes an OCI environment handle.

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_MUTEX

  • OCI_ENV_NO_UCB

In OCI_DEFAULT mode, the OCI library always mutexes handles. In OCI_ENV_NO_MUTEX modes, there is no mutexing in this environment.

In OCI_ENV_NO_MUTEX mode, all OCI calls done on the environment handle, or on handles derived from the environment handle, must be serialized. This can be done by either doing your own mutexing or by having only one thread operating on the environment handle.

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.

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:

OCIEnvCreate() should be used instead of the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls will be supported for backward compatibility.

This call allocates and initializes an OCI environment handle. No changes are done to an already initialized handle. If OCI_ERROR or OCI_SUCCESS_WITH_INFO is returned, the environment handle can be used 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:

For more information about the xtramemsz parameter and user memory allocation, refer to "User Memory Allocation".

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,
                          void          *ctxp,
                          void          *(*malocfp)
                                             (void  *ctxp,
                                              size_t size),
                          void          *(*ralocfp)
                                             (void  *ctxp,
                                              void  *memptr,
                                              size_t newsize),
                          void          (*mfreefp)
                                             (void  *ctxp,
                                              void  *memptr))
                          size_t        xtramemsz,
                          void          **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_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.

  • OCI_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_SUPPRESS_NLS_VALIDATION - Suppresses NLS character validation; NLS character validation suppression is on by default beginning with Oracle Database 11g Release 1 (11.1). Use OCI_ENABLE_NLS_VALIDATION to enable NLS character validation. See Comments for more information.

  • OCI_NCHAR_LITERAL_REPLACE_ON - turns on N' substitution.

  • OCI_NCHAR_LITERAL_REPLACE_OFF - turns off N' substitution. If neither this mode or OCI_NCHAR_LITERAL_REPLACE_ON is used, the substitution is determined by the environment variable ORA_NCHAR_LITERAL_REPLACE, which can be set to TRUE or FALSE. When it is set to TRUE, the replacement will be turned on, otherwise it will be turned off, the default setting in OCI.

  • OCI_ENABLE_NLS_VALIDATION - Enables NLS character validation. See Comments for more information.

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.

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:

This function enables you to set charset and ncharset ids at environment creation time. It is an enhanced version of the OCIEnvCreate() function.

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 N' substitution is turned on, OCIStmtPrepare() or OCIStmtPrepare2() will perform the N' substitution on the SQL text and store the resulting SQL text in the statement handle. Thus, if the application uses OCI_ATTR_STATEMENT to retrieve the SQL text from the OCI statement handle, the modified SQL text, instead of the original SQL text, will be returned.

To turn on N' substitution in ksh shell:

export ORA_NCHAR_LITERAL_REPLACE=TRUE

To turn on N' substitution in csh shell:

setenv ORA_NCHAR_LITERAL_REPLACE TRUE

If a remote database is of a release before 10.2, N' substitution is not done.

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.

See Also:

  • For more information about the xtramemsz parameter and user memory allocation, refer to "User Memory Allocation".

  • For a code example illustrating setting N' substitution in a related function, see "OCIEnvCreate()"

Regarding OCI_SUPPRESS_NLS_VALIDATION and OCI_ENABLE_NLS_VALIDATION modes, by default, when client and server character sets are identical, and client and server releases are both Oracle Database 11g Release 1 (11.1) or higher, OCI does not validate character data in the interest of better performance. This means that if the application inserts a character string with partial multibyte characters (for example, at the end of a bind variable), then such strings could get persisted in the database as is.

Note that if either the client or the server release is older than Oracle Database 11g Release 1 (11.1), then OCI does not allow partial characters.

The OCI_ENABLE_NLS_VALIDATION mode, which was the default until Oracle Database 10g Release 2 (10.2), ensures that partial multibyte characters are not persisted in the database (when client and server character sets are identical). If the application can produce partial multibyte characters, and if the application can run in an environment where the client and server character sets are identical, then Oracle recommends using the OCI_ENABLE_NLS_VALIDATION mode explicitly in order to ensure that such partial characters get stripped out.

OCIInitialize()

Purpose

Initializes the OCI process environment.

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 - will use object features.

  • 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

Note:

OCIEnvCreate() should be used instead of the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls will be 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 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.

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 );

OCILogoff()

Purpose

This function is used to release a session that was retrieved using OCILogon2() or OCILogon().

Syntax

sword OCILogoff ( OCISvcCtx      *svchp
                  OCIError       *errhp );

Parameters

svchp (IN)

The service context handle which was used in the call to OCILogon() or OCILogon2().

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

Comments

This function is used to release a session that was retrieved using OCILogon2() or OCILogon(). If OCILogon() was used, then this function terminates the connection and session. If OCILogon2() was used, then the exact behavior of this call is determined by the mode in which the corresponding OCILogon2() function was called. In the default case, it will close the session/connection. For connection pooling, it closes the session and returns the connection to the pool. For session pooling, it returns the session/connection pair to the pool.

See Also:

For more information on logging on and off in an application, refer to the section "Application Initialization, Connection, and Session Creation".

Related Functions

OCILogon(),OCILogon2()

OCILogon()

Purpose

This function is used to create a simple logon session.

Syntax

sword OCILogon ( OCIEnv          *envhp,
                 OCIError        *errhp,
                 OCISvcCtx       **svchp,
                 const OraText   *username,
                 ub4             uname_len,
                 const OraText   *password,
                 ub4             passwd_len,
                 const OraText   *dbname,
                 ub4             dbname_len );

Parameters

envhp (IN)

The OCI environment handle.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

svchp (IN/OUT)

The service context pointer.

username (IN)

The user name. Must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

uname_len (IN)

The length of user name, in number of bytes, regardless of the encoding.

password (IN)

The user's password. Must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

passwd_len (IN)

The length of password, in number of bytes, regardless of the encoding.

dbname (IN)

The name of the database to connect to. Must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

dbname_len (IN)

The length of dbname, in number of bytes, regardless of the encoding.

Comments

This function is used to create a simple logon session for an application.

Note:

Users requiring more complex sessions, such as TP monitor applications, should refer to the section "Application Initialization, Connection, and Session Creation".

This call allocates the service context handles that are passed to it. This call also implicitly allocates server and user session handles associated with the session. These handles can be retrieved by calling OCIArrayDescriptorAlloc() on the service context handle.

Related Functions

OCILogoff()

OCILogon2()

Purpose

Get a session. This session may be a new one with a new underlying connection, or one that is started over a virtual connection from an existing connection pool, or one from an existing session pool. The mode that the function is called with determines its behavior.

Syntax

sword OCILogon2 ( OCIEnv          *envhp,
                  OCIError        *errhp,
                  OCISvcCtx       **svchp,
                  const OraText   *username,
                  ub4             uname_len,
                  const OraText   *password,
                  ub4             passwd_len,
                  const OraText   *dbname,
                  ub4             dbname_len );
                  ub4             mode );

Parameters

envhp (IN)

The OCI environment handle. For connection pooling and session pooling, this must be the one that the respective pool was created in.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

svchp (IN/OUT)

Address of an OCI service context pointer. This will be filled with a server and session handle.

In the default case, a new session and server handle will be allocated, the connection and session will be started, and the service context will be populated with these handles.

For connection pooling, a new session handle will be allocated, and the session will be started over a virtual connection from the connection pool.

For session pooling, the service context will be populated with an existing session/server handle pair from the session pool.

Note that the user must not change any attributes of the server and user/session handles associated with the service context pointer. Doing so will result in an error being returned by the OCIAttrSet() call.

The only attribute of the service context that can be altered is OCI_ATTR_STMTCACHESIZE.

username (IN)

The user name used to authenticate the session. Must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

uname_len (IN)

The length of username, in number of bytes, regardless of the encoding.

password (IN)

The user's password. For connection pooling, if this parameter is NULL then OCILogon2() assumes that the logon is for a proxy user. It implicitly creates a proxy connection in such a case, using the pool user to authenticate the proxy user. Must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

passwd_len (IN)

The length of password, in number of bytes, regardless of the encoding.

dbname (IN)

For the default case, this indicates the connect string to use to connect to the Oracle database server.

For connection pooling, it indicates the connection pool to retrieve the virtual connection from, in order to start up the session. This value is returned by the OCIConnectionPoolCreate() call.

For session pooling, it indicates the pool to get the session from. It is returned by the OCISessionPoolCreate() call.

Must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

dbname_len (IN)

The length of dbname. For session pooling and connection pooling, this value is returned by the OCISessionPoolCreate() or OCIConnectionPoolCreate() call respectively.

mode (IN)

The values accepted are

  • OCI_DEFAULT

  • OCI_LOGON2_CPOOL

  • OCI_LOGON2_SPOOL

  • OCI_LOGON2_STMTCACHE

  • OCI_LOGON2_PROXY

For the default (non-pooling case), the following modes are valid:

OCI_DEFAULT - Equivalent to calling OCILogon().

OCI_LOGON2_STMTCACHE - Enable statement caching.

For connection pooling, the following modes are valid:

OCI_LOGON2_CPOOL or OCI_CPOOL - This must be set in order to use connection pooling.

OCI_LOGON2_STMTCACHE - Enable statement caching.

In order to use proxy authentication for connection pooling, the password must be set to NULL. The user will then be given a session that is authenticated by the user name provided in the OCILogon2() call, through the proxy credentials supplied in the OCIConnectionPoolCreate() call.

For session pooling, the following modes are valid:

OCI_LOGON2_SPOOL - This must be set in order to use session pooling.

OCI_LOGON2_STMTCACHE - Enable statement caching.

OCI_LOGON2_PROXY - Use proxy authentication. The user is given a session that is authenticated by the user name provided in the OCILogon2() call, through the proxy credentials supplied in the OCISessionPoolCreate() call.

Comments

None.

OCIServerAttach()

Purpose

Creates an access path to a data source for OCI operations.

Syntax

sword OCIServerAttach ( OCIServer     *srvhp,
                        OCIError      *errhp,
                        const OraText *dblink,
                        sb4           dblink_len,
                        ub4           mode );

Parameters

srvhp (IN/OUT)

An uninitialized server handle, which gets initialized by this call. Passing in an initialized server handle causes an error.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

dblink (IN)

Specifies the database server to use. This parameter points to a character string which specifies a connect string or a service point. If the connect string is NULL, then this call attaches to the default host. The string itself could be in UTF-16 or not, depending on mode or the setting in application's environment handle. The length of dblink is specified in dblink_len. The dblink pointer may be freed by the caller on return.

The name of the connection pool to connect to when mode = OCI_CPOOL. This must be the same as the poolName parameter of the connection pool created by OCIConnectionPoolCreate(). Must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

dblink_len (IN)

The length of the string pointed to by dblink. For a valid connect string name or alias, dblink_len must be nonzero. Its value is in number of bytes.

The length of poolName, in number of bytes, regardless of the encoding, when mode = OCI_CPOOL.

mode (IN)

Specifies the various modes of operation. The valid modes are:

  • OCI_DEFAULT. For encoding, this value tells the server handle to use the setting in the environment handle.

  • OCI_CPOOL - use connection pooling,

Since an attached server handle can be set for any connection session handle, the mode value here does not contribute to any session handle.

Comments

This call is used to create an association between an OCI application and a particular server.

This call assumes that OCIConnectionPoolCreate() has already been called, giving poolName, when connection pooling is in effect.

This call initializes a server context handle, which must have been previously allocated with a call to OCIHandleAlloc(). The server context handle initialized by this call can be associated with a service context through a call to OCIAttrSet(). Once that association has been made, OCI operations can be performed against the server.

If an application is operating against multiple servers, multiple server context handles can be maintained. OCI operations are performed against whichever server context is currently associated with the service context.

When OCIServerAttach() is successfully completed, an Oracle shadow process is started. OCISessionEnd() and OCIServerDetach() should be called to clean up the Oracle shadow process. Otherwise, the shadow processes accumulate and cause the Linux or UNIX system to run out of processes. If the database is restarted and there are not enough processes, the database may not startup.

Example

The following example demonstrates the use of OCIServerAttach(). This code segment allocates the server handle, makes the attach call, allocates the service context handle, and then sets the server context into it.

OCIHandleAlloc( (void  *) envhp, (void  **) &srvhp, (ub4)
     OCI_HTYPE_SERVER, 0, (void  **) 0);
OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
OCIHandleAlloc( (void  *) envhp, (void  **) &svchp, (ub4)
     OCI_HTYPE_SVCCTX, 0, (void  **) 0);
/* set attribute server context in the service context */
OCIAttrSet( (void  *) svchp, (ub4) OCI_HTYPE_SVCCTX, (void  *) srvhp,
     (ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);

Related Functions

OCIServerDetach()

OCIServerDetach()

Purpose

Deletes an access to a data source for OCI operations.

Syntax

sword OCIServerDetach ( OCIServer   *srvhp,
                        OCIError    *errhp,
                        ub4         mode ); 

Parameters

srvhp (IN)

A handle to an initialized server context, which gets reset to uninitialized state. The handle is not de-allocated.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

mode (IN)

Specifies the various modes of operation. The only valid mode is OCI_DEFAULT for the default mode.

Comments

This call deletes an access to data source for OCI operations, which was established by a call to OCIServerAttach().

Related Functions

OCIServerAttach()

OCISessionBegin()

Purpose

Creates a user session and begins a user session for a given server.

Syntax

sword OCISessionBegin ( OCISvcCtx     *svchp,
                        OCIError      *errhp,
                        OCISession    *usrhp,
                        ub4           credt,
                        ub4           mode );

Parameters

svchp (IN)

A handle to a service context. There must be a valid server handle set in svchp.

errhp (IN)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

usrhp (IN/OUT)

A handle to a user session context, which is initialized by this call.

credt (IN)

Specifies the type of credentials to use for establishing the user session. Valid values for credt are:

  • OCI_CRED_RDBMS - authenticate using a database user name and password pair as credentials. The attributes OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD should be set on the user session context before this call.

  • OCI_CRED_EXT - authenticate using external credentials. No user name or password is provided.

mode (IN)

Specifies the various modes of operation. Valid modes are:

  • OCI_DEFAULT - in this mode, the user session context returned may only ever be set with the same server context specified in svchp. For encoding, the server handle uses the setting in the environment handle.

  • OCI_MIGRATE - in this mode, the new user session context may be set in a service handle with a different server handle. This mode establishes the user session context. To create a migratable session, the service handle must already be set with a non-migratable user session, which becomes the "creator" session of the migratable session. That is, a migratable session must have a non-migratable parent session.

    OCI_MIGRATE should not be used when the session uses connection pool underneath. The session migration and multiplexing happens transparently to the user.

  • OCI_SYSDBA - in this mode, the user is authenticated for SYSDBA access.

  • OCI_SYSOPER - in this mode, the user is authenticated for SYSOPER access.

  • OCI_PRELIM_AUTH - this mode may only be used with OCI_SYSDBA or OCI_SYSOPER to authenticate for certain administration tasks.

  • OCI_STMT_CACHE - Enables statement caching with default size on the given service handle. It is optional to pass this mode if the application is going to explicitly set the size later using OCI_ATTR_STMTCACHESIZE on that service handle.

Comments

The OCISessionBegin() call is used to authenticate a user against the server set in the service context handle.

Note:

Check for any errors returned when trying to start a session. For example, if the password for the account has expired, an ORA-28001 error is returned.

For release 8.1 or later, OCISessionBegin() must be called for any given server handle before requests can be made against it. OCISessionBegin() only supports authenticating the user for access to the Oracle server specified by the server handle in the service context. In other words, after OCIServerAttach() is called to initialize a server handle, OCISessionBegin() must be called to authenticate the user for that given server.

When using Unicode, when the mode or the environment handle has the appropriate setting, the user name and password that have been set in the session handle usrhp should already be in Unicode. Before calling this function to start a session with a user name and password, you must have called OCIAttrSet() to set these two Unicode strings into the session handle with corresponding length in bytes, because OCIAttrSet() only takes void pointers. The string buffers then will be interpreted by OCISessionBegin().

When OCISessionBegin() is called for the first time for a given server handle, the user session may not be created in migratable (OCI_MIGRATE) mode.

After OCISessionBegin() has been called for a server handle, the application may call OCISessionBegin() again to initialize another user session handle with different (or the same) credentials and different (or the same) operation modes. If an application wants to authenticate a user in OCI_MIGRATE mode, the service handle must already be associated with a non-migratable user handle. The user ID of that user handle becomes the ownership ID of the migratable user session. Every migratable session must have a non-migratable parent session.

If the OCI_MIGRATE mode is not specified, then the user session context can only be used with the same server handle set in svchp. If OCI_MIGRATE mode is specified, then the user authentication may be set with different server handles. However, the user session context may only be used with server handles which resolve to the same database instance. Security checking is done during session switching. A session can migrate to another process only if there is a non-migratable session currently connected to that process whose userid is the same as that of the creator's userid or its own userid.

Do not set OCI_MIGRATE flag in the call to OCISessionBegin(), when the virtual server handle points to a connection pool(OCIServerAttach() called with mode set to OCI_CPOOL). Oracle supports passing this flag only for compatibility reasons. Do not use the OCI_MIGRATE flag, as the perception that the user gets when using a connection pool is of sessions having their own dedicated (virtual) connections which are transparently multiplexed onto real connections.

OCI_SYSDBA, OCI_SYSOPER, and OCI_PRELIM_AUTH may only be used with a primary user session context.

To provide credentials for a call to OCISessionBegin(), one of two methods are supported. The first is to provide a valid user name and password pair for database authentication in the user session handle passed to OCISessionBegin(). This involves using OCIAttrSet() to set the OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD attributes on the user session handle. Then OCISessionBegin() is called with OCI_CRED_RDBMS.

Note:

When the user session handle is terminated using OCISessionEnd(), the user name and password attributes remain unchanged and thus can be re-used in a future call to OCISessionBegin(). Otherwise, they must be reset to new values before the next OCISessionBegin() call.

The second type of credentials supported are external credentials. No attributes need to be set on the user session handle before calling OCISessionBegin(). The credential type is OCI_CRED_EXT. This is equivalent to the Oracle7 'connect /' syntax. If values have been set for OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD, then these are ignored if OCI_CRED_EXT is used.

Another way of setting credentials is to use the session Id of an already authenticated user with the OCI_MIGSESSION attribute. This Id can be extracted from the session handle of an authenticated user using the OCIAttrGet() call.

Example

The following example demonstrates the use of OCISessionBegin(). This code segment allocates the user session handle, sets the user name and password attributes, calls OCISessionBegin(), and then sets the user session into the service context.

/* allocate a user session handle */
OCIHandleAlloc((void  *)envhp, (void  **)&usrhp, (ub4)
     OCI_HTYPE_SESSION, (size_t) 0, (void  **) 0);
OCIAttrSet((void  *)usrhp, (ub4)OCI_HTYPE_SESSION, (void  *)"hr",
     (ub4)strlen("hr"), OCI_ATTR_USERNAME, errhp);
OCIAttrSet((void  *)usrhp, (ub4)OCI_HTYPE_SESSION, (void  *)"hr",
     (ub4)strlen("hr"), OCI_ATTR_PASSWORD, errhp);
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
     OCI_DEFAULT));
OCIAttrSet((void  *)svchp, (ub4)OCI_HTYPE_SVCCTX, (void  *)usrhp,
     (ub4)0, OCI_ATTR_SESSION, errhp);

Related Functions

OCISessionEnd()

OCISessionEnd()

Purpose

Terminates a user session context created by OCISessionBegin()

Syntax

sword OCISessionEnd ( OCISvcCtx       *svchp,
                      OCIError        *errhp,
                      OCISession      *usrhp,
                      ub4             mode );

Parameters

svchp (IN/OUT)

The service context handle. There must be a valid server handle and user session handle associated with svchp.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

usrhp (IN)

De-authenticate this user. If this parameter is passed as NULL, the user in the service context handle is de-authenticated.

mode (IN)

The only valid mode is OCI_DEFAULT.

Comments

The user security context associated with the service context is invalidated by this call. Storage for the user session context is not freed. The transaction specified by the service context is implicitly committed. The transaction handle, if explicitly allocated, may be freed if not being used. Resources allocated on the server for this user are freed. The user session handle may be reused in a new call to OCISessionBegin().

Related Functions

OCISessionBegin()

OCISessionGet()

Purpose

Get a session. This session may be a new one with a new underlying connection, or one that is started over a virtual connection from an existing connection pool, or one from an existing session pool. The mode that the function is called with determines its behavior.

Syntax

sword OCISessionGet ( OCIenv            *envhp,
                      OCIError          *errhp,
                      OCISvcCtx         **svchp,
                      OCIAuthInfo       *authInfop,
                      OraText           *dbName,
                      ub4               dbName_len,
                      const OraText     *tagInfo,
                      ub4               tagInfo_len,
                      OraText           **retTagInfo,
                      ub4               *retTagInfo_len,
                      boolean           *found,
                      ub4               mode );

Parameters

envhp (IN/OUT)

OCI environment handle. For connection pooling and session pooling, this should be the one that the respective pool was created in.

errhp (IN/OUT)

OCI error handle.

svchp (OUT)

Address of an OCI service context pointer. This will be filled with a server and session handle.

In the default case, a new session and server handle will be allocated, the connection and session will be started, and the service context will be populated with these handles.

For connection pooling, a new session handle will be allocated, and the session will be started over a virtual connection from the connection pool.

For session pooling, the service context will be populated with an existing session and server handle pair from the session pool.

Do not change any attributes of the server and user and session handles associated with the service context pointer. Doing so will result in an error being returned by the OCIAttrSet() call.

The only attribute of the service context that can be altered is OCI_ATTR_STMTCACHESIZE.

authInfop (IN)

Authentication Information handle to be used while getting the session.

In the default and connection pooling cases, this handle can take all the attributes of the session handle.

For session pooling, the authentication information handle is considered only if the session pool mode is not set to OCI_SPC_HOMOGENEOUS.

The attributes that can be set on the OCIAuthInfo handle can be categorized into pre-session-creation attributes and post-session-creation attributes. The pre-session-creation attributes are:

Pre-session-creation attributes

Pre-session-creation attributes are those OCI attributes that must be specified before a session is created. These attributes are used to create a session and cannot be changed after a session is created. The pre-session creation attributes are:

OCI_ATTR_USERNAME

OCI_ATTR_PASSWORD

OCI_ATTR_CONNECTION_CLASS

OCI_ATTR_PURITY

OCI_ATTR_PROXY_CREDENTIALS

OCI_ATTR_DISTINGUISHED_NAME

OCI_ATTR_CERTIFICATE

OCI_ATTR_INITIAL_CLIENT_ROLES

OCI_ATTR_APPCTX_SIZE

OCI_ATTR_DRIVER_NAME

Post-session-creation attributes

Post-session-creation attributes are those that can be specified after a session is created. They can be changed freely after a session is created as many times as desired. The following attributes can be set on the OCISession handle after the session has been created:

OCI_ATTR_CLIENT_IDENTIFIER

OCI_ATTR_CURRENT_SCHEMA

OCI_ATTR_MODULE

OCI_ATTR_ACTION

OCI_ATTR_CLIENT_INFO

OCI_ATTR_COLLECT_CALL_TIME

OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE

See Also:

dbName (IN)

For the default case, this indicates the connect string to use to connect to the Oracle database server.

For connection pooling, it indicates the connection pool to retrieve the virtual connection from, in order to start up the session. This value is returned by the OCIConnectionPoolCreate() call.

For session pooling, it indicates the pool to get the session from. It is returned by the OCISessionPoolCreate() call.

dbname_len (IN)

The length of dbName. For session pooling and connection pooling, this value is returned by the call to OCISessionPoolCreate() or OCIConnectionPoolCreate(), respectively.

tagInfo (IN)

This parameter is only used for session pooling.

This indicates the type of session that the user wants. If the user wants a default session, the user must set this to NULL. Please refer to the Comments for a detailed usage of this parameter.

tagInfo_len (IN)

The length in bytes, of tagInfo. Used for session pooling only.

retTagInfo (OUT)

This parameter is only used for session pooling. This indicates the type of session that is returned to the user. Please refer to the Comments for a detailed usage of this parameter.

retTagInfo_len (OUT)

The length in bytes, of retTagInfo. Used for session pooling only.

found (OUT)

This parameter is only used for session pooling. If the type of session that the user requested was returned (that is, the value of tagInfo and retTagInfo is the same), then found is set to TRUE, else, found is set to FALSE.

mode (IN)

The valid modes are

  • OCI_DEFAULT

  • OCI_SESSGET_CPOOL

  • OCI_SESSGET_SPOOL

  • OCI_SESSGET_CREDPROXY

  • OCI_SESSGET_CREDEXT

  • OCI_SESSGET_PURITY_NEW

  • OCI_SESSGET_PURITY_SELF

  • OCI_SESSGET_SPOOL_MATCHANY

  • OCI_SESSGET_STMTCACHE.

In the default (non-pooling) case, the following modes are valid:

OCI_SESSGET_STMTCACHE - This will enable statement caching in the session.

OCI_SESSGET_CREDEXT - This will return a session authenticated with external credentials.

For connection pooling, the following modes are valid:

OCI_SESSGET_CPOOL - This must be set in order to use connection pooling.

OCI_SESSGET_STMTCACHE - This will enable statement caching in the session.

OCI_SESSGET_CREDPROXY - This will return a proxy session. The user is given a session that is authenticated by the user name provided in the OCISessionGet() call, through the proxy credentials supplied in the OCIConnectionPoolCreate() call.

OCI_SESSGET_CREDEXT - This will return a session authenticated with external credentials.

For session pooling, the following modes are valid:

OCI_SESSGET_SPOOL - This must be set in order to use session pooling.

OCI_SESSGET_CREDPROXY - In this case, the user is given a session that is authenticated by the user name provided in the OCISessionGet() call, through the proxy credentials supplied in the OCISessionPoolCreate() call.

OCI_SESSGET_SPOOL_MATCHANY - This refers to the tagging behavior. If this mode is set, then a session which has a different tag than what was asked for, may be returned. Please refer to the Comments section.

For database resident connection pooling, the following modes are valid:

OCI_SESSGET_PURITY_SELF- the application can use a session that has been used before and that you may also specify application-specific tags.

OCI_SESSGET_PURITY_NEW - the application requires a new session that is not tainted with any prior session state. This is the default.

Comments

The tags provide a way for users to customize sessions in the pool. A client can get a default or untagged session from a pool, set certain attributes on the session (such as Globalization settings), and return the session to the pool, labeling it with an appropriate tag in the OCISessionRelease() call.

The user, or some other user, can request for a session with the same attributes, and can do so by providing the same tag in the OCISessionGet() call.

If a user asks for a session with tag 'A', and a matching session is not available, an appropriately authenticated untagged session (session with a NULL tag) will be returned, if such a session is free. If even an untagged session is not free and OCI_SESSGET_SPOOL_MATCHANY has been specified, then an appropriately authenticated session with a different tag will be returned. If OCI_SESSGET_SPOOL_MATCHANY is not set, then a session with a different tag is never returned.

Restrictions on Attributes Supported for OCI Session Pools

You can use the following pre-session-creation attributes with OCI session pools:

OCI_ATTR_DRIVER_NAME
OCI_ATTR_USERNAME
OCI_ATTR_PASSWORD
OCI_ATTR_CONNECTION_CLASS
OCI_ATTR_PURITY

However, OCI_ATTR_DRIVERNAME can only be specified during OCISessionPoolCreate() by setting them on the OCIAuthInfo handle that is an attribute of OCISPool handle. They cannot be specified on the OCIAuthInfo handle passed into individual OCISessionGet() calls. This ensures that all sessions that are part of an OCI session pool have uniform values for these attributes.

OCISessionPoolCreate()

Purpose

Initializes a session pool for use with OCI session pooling and database resident connection pooling (DRCP). It starts up sessMin number of sessions and connections to the database. Before making this call, make a call to OCIHandleAlloc() to allocate memory for the session pool handle.

Syntax

sword OCISessionPoolCreate ( OCIEnv           *envhp,
                             OCIError         *errhp, 
                             OCISPool         *spoolhp,
                             OraText          **poolName,
                             ub4              *poolNameLen,
                             const OraText    *connStr,
                             ub4              connStrLen,
                             ub4              sessMin, 
                             ub4              sessMax, 
                             ub4              sessIncr,
                             OraText          *userid,
                             ub4              useridLen,
                             OraText          *password,
                             ub4              passwordLen,
                             ub4              mode );

Parameters

envhp (IN)

A pointer to the environment handle in which the session pool needs to be created.

errhp (IN/OUT)

An error handle which can be passed to OCIErrorGet().

spoolhp (IN/OUT)

A pointer to the session pool handle that is initialized.

poolName (OUT)

The name of the session pool returned. It is unique across all session pools in an environment. This value must be passed to the OCISessionGet() call.

poolNameLen (OUT)

Length of poolName in bytes.

connStr (IN)

The TNS alias of the database to connect to.

connStrLen (IN)

The length of connStr in bytes.

sessMin (IN)

Specifies the minimum number of sessions in the session pool.

This number of sessions are started by OCISessionPoolCreate(). After this, sessions are opened only when necessary.

This value is used when mode is set to OCI_SPC_HOMOGENEOUS. In all other cases it is ignored.

sessMax (IN)

Specifies the maximum number of sessions that can be opened in the session pool. Once this value is reached, no more sessions are opened. The valid values are 1 and higher.

sessIncr (IN)

Allows applications to set the next increment for sessions to be started if the current number of sessions are less than sessMax. The valid values are 0 and higher.

sessMin + sessIncr cannot be more than sessMax.

userid (IN)

Specifies the userid with which to start up the sessions.

useridLen (IN)

Length of the userid in bytes.

password (IN)

The password for the corresponding userid.

passwordLen (IN)

The length of the password in bytes.

mode (IN)

The modes supported are

  • OCI_DEFAULT - for a new session pool creation.

  • OCI_SPC_REINITIALIZE - After creating a session pool, if you wish to change the pool attributes dynamically (change the sessMin, sessMax, and sessIncr parameters), call OCISessionPoolCreate() with mode set to OCI_SPC_REINITIALIZE. When mode is set to OCI_SPC_REINITIALIZE, then connStr, userid, and password will be ignored.

  • OCI_SPC_STMTCACHE - an OCI statement cache will be created for the session pool. If the pool is not created with OCI statement caching turned on, server-side statement caching will automatically be used. Please note that in general, client- side statement caching will give better performance.

  • OCI_SPC_HOMOGENEOUS - all sessions in the pool will be authenticated with the user name and password passed to OCISessionPoolCreate(). The authentication handle (parameter authInfo) passed into OCISessionGet() is ignored in this case. Moreover, the sessMin and the SessIncr values are considered only in this case. No proxy session can be created in this mode. This mode can be used in database resident connection pooling (DRCP).

  • OCI_SPC_NO_RLB - By default, the runtime connection load balancing is enabled in the session pool, if the client and the server are capable of supporting it. However, in case you want to turn it off, a new mode, OCI_SPC_NO_RLB, is provided for the mode parameter of OCISessionPoolCreate(). This mode can be used to turn off this feature in case runtime load balancing is not desired. It can be used only at the time of pool creation. If this mode is passed for a pool that has already been created an error, ORA-24411, is thrown.

Comments

Authentication Note.

Note that a session pool may contain two types of connections to the database: direct connections and proxy connections. To make a proxy connection, a user must have Connect through Proxy privilege.

When the session pool is created, the userid and password may or may not be specified. If these values are NULL, no proxy connections can exist in this pool. If mode is set to OCI_SPC_HOMOGENEOUS, no proxy connection can exist.

A userid and password pair may also be specified through the authentication handle in the OCISessionGet() call. If this call is made with mode set to OCI_SESSGET_CREDPROXY, then the user is given a session that is authenticated by the userid provided in the OCISessionGet() call, through the proxy credentials supplied in the OCISessionPoolCreate() call. In this case, the password in the OCISessionGet() call is ignored.

If OCISessionGet() is called with mode not set to OCI_SESSGET_CREDPROXY, then the user gets a direct session which is authenticated by the credentials provided in the OCISessionGet() call. If none have been provided in this call, the user gets a session authenticated by the credentials in the OCISessionPoolCreate() call.

Example

In the following code runtime load balancing is disabled:

OCISessionPoolCreate(envhp, errhp, poolhp, (OraText **)&poolName, 
                     (ub4 *)&poolNameLen,
                     database, (ub4) strlen ((const signed char *) database),
                     sessMin, sessMax, sessIncr, (OraText *) appusername,
                     (ub4) strlen ((const signed char *) appusername),
                     (OraText *) apppassword,
                     (ub4) strlen ((const signed char *) apppassword),
                     OCI_SPC_HOMOGENEOUS | OCI_SPC_NO_RLB);

OCISessionPoolDestroy()

Purpose

Destroys a session pool.

Syntax

sword OCISessionPoolDestroy ( OCISPool     *spoolhp, 
                              OCIError     *errhp,
                              ub4          mode );
spoolhp (IN/OUT)

The session pool handle for the session pool to be destroyed.

errhp (IN/OUT)

An error handle which can be passed to OCIErrorGet().

mode (IN)

Currently, OCISessionPoolDestroy() will support modes OCI_DEFAULT and OCI_SPD_FORCE.

If this call is made with mode set to OCI_SPD_FORCE, and there are active sessions in the pool, the sessions will be closed and the pool will be destroyed. However, if this mode is not set, and there are busy sessions in the pool, an error will be returned.

OCISessionRelease()

Purpose

This function is used to release a session that was retrieved using OCISessionGet(). The exact behavior of this call is determined by the mode in which the corresponding OCISessionGet() function was called. In the default case, it will close the session/connection. For connection pooling, it closes the session and returns the connection to the pool. For session pooling, it returns the session/connection pair to the pool, and any pending transaction is committed.

Syntax

sword OCISessionRelease ( OCISvcCtx       *svchp,
                          OCIError        *errhp,
                          OraText         *tag,
                          ub4             tag_len,
                          ub4             mode );

Parameters

svchp (IN)

The service context that was populated during the corresponding OCISessionGet() call.

In the default case, the session and connection associated with this handle will be closed.

In the connection pooling case, the session will be closed and the connection released to the pool.

For session pooling, the session/connection pair associated with this service context will be released to the pool.

errhp (IN/OUT)

The OCI error handle.

tag (IN)

This parameter is only used for session pooling.

This parameter will be ignored unless mode OCI_SESSRLS_RETAG is specified. In this case, the session is labelled with this tag and returned to the pool. If this is NULL, then the session is not tagged.

tag_len (IN)

This parameter is only used for session pooling.

Length of the tag. This is ignored unless mode OCI_SESSRLS_RETAG is set.

mode (IN)

The supported modes are

  • OCI_DEFAULT

  • OCI_SESSRLS_DROPSESS

  • OCI_SESSRLS_RETAG

For the default case and for connection pooling, only OCI_DEFAULT can be used.

OCI_SESSRLS_DROPSESS and OCI_SESSRLS_RETAG are only used for session pooling.

When OCI_SESSRLS_DROPSESS is specified, the session will be removed from the session pool.

If and only if OCI_SESSRLS_RETAG is set, will the tag on the session be altered. If this mode is not set, the tag and tag_len parameters will be ignored.

Comments

Be careful to pass in the correct tag. If a default session is requested and the user sets certain properties on this session (probably through an ALTER SESSION command), then the user must label this session appropriately by tagging it as such.

If on the other hand, the user requested a tagged session and got one, and has changed the properties on the session, then the user must pass in a different tag if appropriate.

For the correct working of the session pool layer the application developer must be very careful to pass in the correct tag to the OCISessionGet() and OCISessionRelease() calls.

OCITerminate()

Purpose

Detaches the process from the shared memory subsystem and releases the shared memory.

Syntax

sword OCITerminate ( ub4    mode);

Parameters

mode (IN)

Call-specific mode. Valid value:

  • OCI_DEFAULT - executes the default call

Comments

OCITerminate() should be called only once for each process and is the counterpart of OCIInitialize() call. The call will try to detach the process from the shared memory subsystem and shut it down. It also performs additional process cleanup operations. When two or more processes connecting to the same shared memory are calling OCITerminate() simultaneously, the fastest one will release the shared memory subsystem completely and the slower ones will have to terminate.

Related Functions

OCIInitialize()