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. In this case, this handle can have the following attributes set:

OCI_ATTR_USERNAME

OCI_ATTR_PASSWORD

OCI_ATTR_INITIAL_CLIENT_ROLES

Please refer to user handle attributes for more information.

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_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 username provided in the OCISessionGet() call, via 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 username provided in the OCISessionGet() call, via 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 below.

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.

Related Functions

OCISessionRelease(), OCISessionPoolCreate(), OCISessionPoolDestroy()