|Oracle Call Interface Programmer's Guide
Release 2 (9.2)
Part Number A96584-01
OCI Relational Functions, 13 of 38
Creates a user session and begins a user session for a given server.
sword OCISessionBegin ( OCISvcCtx *svchp, OCIError *errhp, OCISession *usrhp, ub4 credt, ub4 mode );
A handle to a service context. There must be a valid server handle set in svchp.
An error handle you can pass to
OCIErrorGet() for diagnostic information in the event of an error.
A handle to an user session context, which is initialized by this call.
Specifies the type of credentials to use for establishing the user session. Valid values for credt are:
Specifies the various modes of operation. Valid modes are:
svchp. For encoding, the server handle uses the setting in the environment handle.
OCISessionBegin() call is used to authenticate a user against the server set in the service context handle.
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 username 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 username 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 dvoid pointers. The string buffers then will be interpreted by
OCISessionBegin() is called for the first time for a given server handle, the user session may not be created in migratable (OCI_MIGRATE) mode.
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.
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 username 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.
When the user session handle is terminated using
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
The following example demonstrates the use of
OCISessionBegin(). This code segment allocates the user session handle, sets the username and password attributes, calls
OCISessionBegin(), and then sets the user session into the service context.
/* allocate a user session handle */ OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, (ub4) OCI_HTYPE_SESSION, (size_t) 0, (dvoid **) 0); OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"jessica", (ub4)strlen("jessica"), OCI_ATTR_USERNAME, errhp); OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"doogie", (ub4)strlen("doogie"), OCI_ATTR_PASSWORD, errhp); checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS, OCI_DEFAULT)); OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX, (dvoid *)usrhp, (ub4)0, OCI_ATTR_SESSION, errhp);