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.

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

In this call the user 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.

Related Functions

OCISessionGet(), OCISessionPoolCreate(), OCISessionPoolDestroy(),OCILogon2()