OCISessionPoolCreate()

Purpose

Initializes a session pool. 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 above.

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 above.

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 username 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.

Comments

Authentication Note

Please 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.

Related Functions

OCISessionRelease(), OCISessionGet(), OCISessionPoolDestroy()