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 username used to authenticate the session. It must be in UTF-16 encoding in OCI_UTF16 environment mode.

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. It must be in UTF-16 encoding in OCI_UTF16 environment mode.

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 UTF-16 encoding in OCI_UTF16 environment mode.

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 username provided in the OCILogon2() call, via 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 username provided in the OCILogon2() call, via the proxy credentials supplied in the OCISessionPoolCreate() call.

Comments

None.

Related Functions

OCILogon(),OCILogoff(),OCISessionGet(),OCISessionRelease()