8 Managing Scalable Platforms

Simple Local Transactions

Many applications work with only simple local transactions. In these applications, an implicit transaction is created when the application makes database changes. The only transaction-specific calls needed by such applications are:

• OCITransCommit() to commit the transaction

• OCITransRollback() to roll back the transaction

As soon as one transaction has been committed or rolled back, the next modification to the database creates a new implicit transaction for the application.

Only one implicit transaction can be active at any time on a service context. Attributes of the implicit transaction are opaque to the user.

If an application creates multiple sessions, each one can have an implicit transaction associated with it.

Serializable or Read-Only Local Transactions

Applications requiring serializable or read-only transactions require an additional OCI OCITransStart() call to start the transaction.

The OCITransStart() call must specify OCI_TRANS_SERIALIZABLE or OCI_TRANS_READONLY, as appropriate, for the flags parameter. If no flag is specified, the default value is OCI_TRANS_READWRITE for a standard read/write transaction.

Specifying the read-only option in the OCITransStart() call saves the application from performing a server round-trip to execute a SET TRANSACTION READ ONLY statement.

Global Transactions

Global transactions are necessary only in more sophisticated transaction-processing applications.

Transaction Branches

Within a single global transaction, Oracle Database supports both tightly coupled and loosely coupled relationships between a pair of branches.

• Tightly coupled branches share the same local transaction. The gtrid references a unique local transaction, and multiple branches point to that same transaction. The owner of the transaction is the branch that was created first.

• Loosely coupled branches use different local transactions. The gtrid and bqual together map to a unique local transaction. Each branch points to a different transaction.

The flags parameter of OCITransStart() allows applications to pass OCI_TRANS_TIGHT or OCI_TRANS_LOOSE values to specify the type of coupling.

A session corresponds to a user session, created with OCISessionBegin().

Figure 8-1 illustrates tightly coupled branches within an application. The XIDs of the two branches (B1 and B2) share the same gtrid, because they are operating on the same transaction (T), but they have a different bqual, because they are on separate branches.

Figure 8-1 Multiple Tightly Coupled Branches

Description of "Figure 8-1 Multiple Tightly Coupled Branches"

Figure 8-2 illustrates how a single session operates on different branches. The gtrid components of the XIDs are different, because they represent separate global transactions.

Figure 8-2 Session Operating on Multiple Branches

Description of "Figure 8-2 Session Operating on Multiple Branches"

It is possible for a single session to operate on multiple branches that share the same transaction, but this scenario does not have much practical value.

See Also:

"OCITransStart()" for sample code demonstrating this scenario

Transaction Examples

Table 8-1 through Table 8-5 illustrate how to use the transaction OCI calls.

They show a series of OCI calls and other actions, along with their resulting behavior. For simplicity, not all parameters to these calls are listed; rather, it is the flow of calls that is being demonstrated.

The OCI Action column indicates what the OCI application is doing, or what call it is making. The XID column lists the transaction identifier, when necessary. The Flags column lists the values passed in the flags parameter. The Result column describes the result of the call.

Initialization Parameters

Two initialization parameters relate to the use of global transaction branches and migratable open connections:

• TRANSACTIONS - This parameter specifies the maximum number of global transaction branches in the entire system. In contrast, the maximum number of branches on a single global transaction is 8.

• OPEN_LINKS_PER_INSTANCE - This parameter specifies the maximum number of migratable open connections. Migratable open connections are used by global transactions to cache connections after committing a transaction. Contrast this with the OPEN_LINKS parameter, which controls the number of connections from a session and is not applicable to applications that use global transactions.

OCITransStart()

SQL UPDATE

OCITransCommit()

OCITransStart()

SQL UPDATE

OCITransDetach()

OCITransStart()

SQL UPDATE

OCITransPrepare()

OCITransCommit()

OCITransStart()

SQL UPDATE

OCITransCommit()

OCITransStart()

SQL SELECT

OCITransCommit()

OCI Authentication Management

The OCISessionBegin() call authenticates a user against the server set in the service context handle. It must be the first call for any given server handle. OCISessionBegin() authenticates the user for access to the Oracle database specified by the server handle and the service context of the call: after OCIServerAttach() initializes a server handle, OCISessionBegin() must be called to authenticate the user for that server.

When OCISessionBegin() is called for the first time on a server handle, the user session may not be created in migratable mode (OCI_MIGRATE). After OCISessionBegin() has been called for a server handle, the application can call OCISessionBegin() again to initialize another user session handle with different or the same credentials and different or the same operation modes. For an application to authenticate a user in OCI_MIGRATE mode, the service handle must already be associated with a nonmigratable user handle. The userid of that user handle becomes the ownership ID of the migratable user session. Every migratable session must have a nonmigratable parent session.

• If OCI_MIGRATE mode is not specified, then the user session context can be used only with the server handle specified with the OCISessionBegin().

• If OCI_MIGRATE mode is specified, then the user authentication can be set with other server handles. However, the user session context can only be used with server handles that resolve to the same database instance. Security checking is performed during session switching.

A migratable session can switch to a different server handle only if the ownership ID of the session matches the userid of a nonmigratable session currently connected to that same server.

OCI_SYSDBA, OCI_SYSOPER, and OCI_PRELIM_AUTH settings can only be used with a primary user session context.

A migratable session can be switched, or migrated, to a server handle within an environment represented by an environment handle. It can also migrate or be cloned to a server handle in another environment in the same process, or in a different process in a different mode. To perform this migration or cloning, you must do the following:

1. Extract the session ID from the session handle using OCI_ATTR_MIGSESSION. This is an array of bytes that must not be modified by the caller.

   See Also:

   "User Session Handle Attributes"

2. Transport this session ID to another process.

3. In the new environment, create a session handle and set the session ID using OCI_ATTR_MIGSESSION.

4. Execute OCISessionBegin(). The resulting session handle is fully authenticated.

To provide credentials for a call to OCISessionBegin(), you must provide a valid user name and password pair for database authentication in the user session handle parameter. 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 OCISessionEnd(), the user name and password attributes are changed and thus cannot be reused in a future call to OCISessionBegin(). They must be reset to new values before the next OCISessionBegin() call.

Or, you can supply external credentials. No attributes need to be set on the user session handle before calling OCISessionBegin(). The credential type is OCI_CRED_EXT. If values have been set for OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD, these are ignored if OCI_CRED_EXT is used.

OCI Password Management

The OCIPasswordChange() call enables an application to modify a user's database password as necessary. This is particularly useful if a call to OCISessionBegin() returns an error message or warning indicating that a user's password has expired.

Applications can also use OCIPasswordChange() to establish a user authentication context and to change the password. If OCIPasswordChange() is called with an uninitialized service context, it establishes a service context and authenticates the user's account using the old password, and then changes the password to the new password. If the OCI_AUTH flag is set, the call leaves the user session initialized. Otherwise, the user session is cleared.

If the service context passed to OCIPasswordChange() is already initialized, then OCIPasswordChange() authenticates the given account using the old password and changes the password to the new password. In this case, no matter how the flag is set, the user session remains initialized.

Secure External Password Store

For large-scale deployments where applications use password credentials to connect to databases, it is possible to store such credentials in a client-side Oracle wallet. An Oracle wallet is a secure software container that is used to store authentication and signing credentials.

Storing database password credentials in a client-side Oracle wallet eliminates the need to embed user names and passwords in application code, batch jobs, or scripts. This reduces the risk of exposing passwords in the clear in scripts and application code, and simplifies maintenance because you need not change your code each time user names and passwords change. In addition, not having to change application code makes it easier to enforce password management policies for these user accounts.

When you configure a client to use the external password store, applications can use the following syntax to connect to databases that use password authentication:

CONNECT /@database_alias

Note that you need not specify database login credentials in this CONNECT statement. Instead your system looks for database login credentials in the client wallet.

OCI Session Management

Transaction servers that actively balance user load by multiplexing user sessions over a few server connections must group these connections into a server group. Oracle Database uses server groups to identify these connections so that sessions can be managed effectively and securely.

The attribute OCI_ATTR_SERVER_GROUP must be defined to specify the server group name by using the OCIAttrSet() call, as shown in Example 8-1.

OCIAttrSet ((void *) srvhp, (ub4) OCI_HTYPE_SERVER, (void *) group_name, 
            (ub4) strlen ((CONST char *) group_name), 
            (ub4) OCI_ATTR_SERVER_GROUP, errhp);

The server group name is an alphanumeric string not exceeding 30 characters. This attribute can only be set after calling OCIServerAttach(). OCI_ATTR_SERVER_GROUP attribute must be set in the server context before creating the first nonmigratable session that uses that context. After the session is created successfully and the connection to the server is established, the server group name cannot be changed.

All migratable sessions created on servers within a server group can only migrate to other servers in the same server group. Servers that terminate are removed from the server group. New servers can be created within an existing server group at any time.

The use of server groups is optional. If no server group is specified, the server is created in a server group called DEFAULT.

The owner of the first nonmigratable session created in a nondefault server group becomes the owner of the server group. All subsequent nonmigratable sessions for any server in this server group must be created by the owner of the server group.

The server group feature is useful when dedicated servers are used. It has no effect on shared servers. All shared servers effectively belong to the server group DEFAULT.

OCI Attributes for Middle-Tier Applications

The following attributes enable you to specify the external name and initial privileges of a client. These credentials are used by applications as alternative means of identifying or authenticating the client.

OCISession *session_handle;
OCISvcCtx  *application_server_session_handle;
OCIError   *error_handle;
...
OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION, 
           (void *)application_server_session_handle, (ub4) 0, 
            OCI_ATTR_PROXY_CREDENTIALS, error_handle);

/* Declarations */
...
OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION,
           (void *)distinguished_name, (ub4) 0,
           OCI_ATTR_DISTINGUISHED_NAME, error_handle);

OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION, 
           (void *)certificate, ub4 certificate_length, 
           OCI_ATTR_CERTIFICATE, error_handle);

OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION, 
           (void *)role_array, (ub4) number_of_strings,
           OCI_ATTR_INITIAL_CLIENT_ROLES, error_handle);

OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION, 
           (void *)"janedoe", (ub4)strlen("janedoe"),
           OCI_ATTR_CLIENT_IDENTIFIER, error_handle);

SELECT SYS_CONTEXT('userenv', 'client_identifier') FROM DUAL;

OCIAttrSet((void *)session_handle, (ub4) OCI_HTYPE_SESSION, (void *)password,
           (ub4)0, OCI_ATTR_PASSWORD, error_handle);

...
*OCIEnv *environment_handle; 
OCIServer *data_server_handle; 
OCIError *error_handle; 
OCISvcCtx *application_server_service_handle; 
OraText *client_roles[2]; 
OCISession *first_client_session_handle, second_client_session_handle; 
...
/*
** General initialization and allocation of contexts. 
*/
 
(void) OCIInitialize((ub4) OCI_DEFAULT, (void *)0,
                     (void * (*)(void *, size_t)) 0, 
                     (void * (*)(void *, void *, size_t))0, 
                     (void (*)(void *, void *)) 0 ); 
(void) OCIEnvInit( (OCIEnv **) &environment_handle, OCI_DEFAULT, (size_t) 0,
                  (void **) 0 ); 
(void) OCIHandleAlloc( (void *) environment_handle, (void **) &error_handle,
     OCI_HTYPE_ERROR, (size_t) 0, (void **) 0); 
/* 
** Allocate and initialize the server and service contexts used by the
** application server. 
*/ 

(void) OCIHandleAlloc( (void *) environment_handle, 
     (void **)&data_server_handle, OCI_HTYPE_SERVER, (size_t) 0, (void **) 0); 
(void) OCIHandleAlloc( (void *) environment_handle, (void **)
     &application_server_service_handle, OCI_HTYPE_SVCCTX, (size_t) 0, 
     (void **) 0);  
(void) OCIAttrSet((void *) application_server_service_handle,
     OCI_HTYPE_SVCCTX, (void *) data_server_handle, (ub4) 0, OCI_ATTR_SERVER,
     error_handle); 
/* 
** Authenticate the application server. In this case, external authentication is
** being used. 
*/

(void) OCIHandleAlloc((void *) environment_handle, 
     (void **)&application_server_session_handle, (ub4) OCI_HTYPE_SESSION,
     (size_t) 0, (void **) 0); 
checkerr(error_handle, OCISessionBegin(application_server_service_handle,
     error_handle, application_server_session_handle, OCI_CRED_EXT,
     OCI_DEFAULT)); 
/* 
** Authenticate the first client. 
** Note that no password is specified by the 
** application server for the client as it is trusted. 
*/ 

(void) OCIHandleAlloc((void *) environment_handle, 
     (void **)&first_client_session_handle, (ub4) OCI_HTYPE_SESSION, 
     (size_t) 0,(void **) 0); 
(void) OCIAttrSet((void *) first_client_session_handle, 
     (ub4) OCI_HTYPE_SESSION, (void *) "jeff", (ub4) strlen("jeff"),
     OCI_ATTR_USERNAME, error_handle); 
/* 
** In place of specifying a password, pass the session handle of the application
** server instead. 
*/ 

(void) OCIAttrSet((void *) first_client_session_handle, 
     (ub4) OCI_HTYPE_SESSION, (void *) application_server_session_handle, 
     (ub4) 0, OCI_ATTR_PROXY_CREDENTIALS, error_handle); 
(void) OCIAttrSet((void *) first_client_session_handle, 
     (ub4) OCI_HTYPE_SESSION, (void *) "jeff@VeryBigBank.com", 
     (ub4) strlen("jeff@VeryBigBank.com"), OCI_ATTR_EXTERNAL_NAME,
     error_handle); 
/* 
** Establish the roles that the application server can use as the client. 
*/
 
client_roles[0] = (OraText *) "TELLER"; 
client_roles[1] = (OraText *) "SUPERVISOR";
(void) OCIAttrSet((void *) first_client_session_handle, 
     OCI_ATTR_INITIAL_CLIENT_ROLES, error_handle); 
checkerr(error_handle, OCISessionBegin(application_server_service_handle,
     error_handle, first_client_session_handle, OCI_CRED_PROXY, OCI_DEFAULT)); 
/* 
** To start a session as another client, the application server does the 
** following.
** This code is unchanged from the current way of doing session switching. 
*/

(void) OCIHandleAlloc((void *) environment_handle, 
     (void **)&second_client_session_handle, (ub4) OCI_HTYPE_SESSION, 
     (size_t) 0, (void **) 0); 
(void) OCIAttrSet((void *) second_client_session_handle, 
     (ub4) OCI_HTYPE_SESSION, (void *) "mutt", (ub4) strlen("mutt"),
     OCI_ATTR_USERNAME, error_handle); 
(void) OCIAttrSet((void *) second_client_session_handle, 
     (ub4) OCI_HTYPE_SESSION, (void *) application_server_session_handle, 
     (ub4) 0, OCI_ATTR_PROXY_CREDENTIALS, error_handle); 
(void) OCIAttrSet((void *) second_client_session_handle, 
     (ub4) OCI_HTYPE_SESSION, (void *) "mutt@VeryBigBank.com", 
     (ub4) strlen("mutt@VeryBigBank.com"), OCI_ATTR_EXTERNAL_NAME,
     error_handle); 
/* 
** Note that the application server has not specified any initial roles to have
** as the second client. 
*/
 
checkerr(error_handle, OCISessionBegin(application_server_service_handle,
     error_handle, second_client_session_handle, OCI_CRED_PROXY, OCI_DEFAULT)); 
/* 
** To switch to the first user, the application server applies the session
** handle obtained by the first 
** OCISessionBegin() call. This is the same as is currently done. 
*/ 

(void) OCIAttrSet((void *)application_server_service_handle, 
     (ub4) OCI_HTYPE_SVCCTX, (void *)first_client_session_handle, 
     (ub4)0, (ub4)OCI_ATTR_SESSION, error_handle); 
/* 
** After doing some operations, the application server can switch to
** the second client. That 
** is be done by the following call: 
*/

(void) OCIAttrSet((void *)application_server_service_handle, 
     (ub4) OCI_HTYPE_SVCCTX, 
     (void *)second_client_session_handle, (ub4)0, (ub4)OCI_ATTR_SESSION,
     error_handle); 
/* 
** and then do operations as that client 
*/
...

Externally Initialized Context Attributes in OCI

The client applications you develop can set application contexts explicitly in the session handle before authentication, using the following attributes in OCI functions:

OCIAttrSet(session, (ub4) OCI_HTYPE_SESSION, 
           (void *)&size, (ub4)0, OCI_ATTR_APPCTX_SIZE, error_handle); 

OCIAttrGet(session, (ub4) OCI_HTYPE_SESSION, 
           (void *)&ctxl_desc, (ub4)0, OCI_ATTR_APPCTX_LIST, error_handle);

OCIParamGet(ctxl_desc, OCI_DTYPE_PARAM, error_handle,(void **)&ctx_desc, i);

OCIAttrSet(ctx_desc, OCI_DTYPE_PARAM,
     (void *)ctx_name, sizeof(ctx_name), OCI_ATTR_APPCTX_NAME, error_handle);
  
OCIAttrSet(ctx_desc, OCI_DTYPE_PARAM,
     (void *)attr_name, sizeof(attr_name), OCI_ATTR_APPCTX_ATTR, error_handle);  
  
OCIAttrSet(ctx_desc, OCI_DTYPE_PARAM,
     (void *)value, sizeof(value), OCI_ATTR_APPCTX_VALUE, error_handle);  

End-to-End Application Tracing

Use the following attributes to measure server call time, not including server round-trips. These attributes can also be set by using the PL/SQL package DBMS_APPLICATION_INFO, which incurs one round-trip to the server. Using OCI to set the attributes does not incur a round-trip.

boolean enable_call_time;
ub8 call_time;
...
enable_call_time = TRUE;
OCIAttrSet(session, OCI_HTYPE_SESSION, (void *)&enable_call_time,
           (ub4)0, OCI_ATTR_COLLECT_CALL_TIME,
           (OCIError *)error_handle);
OCIStmtExecute(...);
OCIAttrGet(session, OCI_HTYPE_SESSION, (void *)&call_time,
           (ub4)0, OCI_ATTR_CALL_TIME, 
           (OCIError *)error_handle);
...

Using OCISessionBegin() with an Externally Initialized Context

When you call OCISessionBegin(), the context set in the session handle is pushed to the server. No additional contexts are propagated to the server session. Example 8-14 illustrates the use of these calls and attributes.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <oci.h>

static OraText *username = (OraText *) "HR";
static OraText *password = (OraText *) "HR";

static OCIEnv *envhp;
static OCIError *errhp;

int main(/*_ int argc, char *argv[] _*/);

static sword status;

int main(argc, argv)
int argc;
char *argv[];
{

  OCISession *authp = (OCISession *) 0;
  OCIServer *srvhp;
  OCISvcCtx *svchp;
  OCIDefine *defnp = (OCIDefine *) 0;
  void     *parmdp;
  ub4        ctxsize;
  OCIParam  *ctxldesc;
  OCIParam  *ctxedesc;

  OCIEnvCreate(&envhp, OCI_DEFAULT, (void *)0, 0, 0, 0,
                            (size_t)0, (void *)0);

  (void) OCIHandleAlloc( (void *) envhp, (void **) &errhp, OCI_HTYPE_ERROR,
                   (size_t) 0, (void **) 0);

  /* server contexts */
  (void) OCIHandleAlloc( (void *) envhp, (void **) &srvhp, OCI_HTYPE_SERVER,
                   (size_t) 0, (void **) 0);

  (void) OCIHandleAlloc( (void *) envhp, (void **) &svchp, OCI_HTYPE_SVCCTX,
                   (size_t) 0, (void **) 0);

  (void) OCIServerAttach( srvhp, errhp, (OraText *)"", strlen(""), 0);

  /* set attribute server context in the service context */
  (void) OCIAttrSet( (void *) svchp, OCI_HTYPE_SVCCTX, (void *)srvhp,
                    (ub4) 0, OCI_ATTR_SERVER, (OCIError *) errhp);

  (void) OCIHandleAlloc((void *) envhp, (void **)&authp,
                        (ub4) OCI_HTYPE_SESSION, (size_t) 0, (void **) 0);
/****************************************/
  /* set app ctx size to 2 because you want to set up 2 application contexts */
  ctxsize = 2;

  /* set up app ctx buffer */
  (void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
                 (void *) &ctxsize, (ub4) 0,
                 (ub4) OCI_ATTR_APPCTX_SIZE, errhp);

  /* retrieve the list descriptor */
  (void) OCIAttrGet((void *)authp, (ub4) OCI_HTYPE_SESSION,
                    (void *)&ctxldesc, 0, OCI_ATTR_APPCTX_LIST, errhp );

  /* retrieve the 1st ctx element descriptor */
  (void) OCIParamGet(ctxldesc, OCI_DTYPE_PARAM, errhp, (void**)&ctxedesc, 1);

  (void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
                 (void *) "HR", (ub4) strlen((char *)"HR"),
                 (ub4) OCI_ATTR_APPCTX_NAME, errhp);

  (void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
                 (void *) "ATTR1", (ub4) strlen((char *)"ATTR1"),
                 (ub4) OCI_ATTR_APPCTX_ATTR, errhp);

  (void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
                 (void *) "VALUE1", (ub4) strlen((char *)"VALUE1"),
                 (ub4) OCI_ATTR_APPCTX_VALUE, errhp);

  /* set second context */
  (void) OCIParamGet(ctxldesc, OCI_DTYPE_PARAM, errhp, (void**)&ctxedesc, 2);

  (void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
                 (void *) "HR", (ub4) strlen((char *)"HR"),
                 (ub4) OCI_ATTR_APPCTX_NAME, errhp);

  (void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
                 (void *) "ATTR2", (ub4) strlen((char *)"ATTR2"),
                 (ub4) OCI_ATTR_APPCTX_ATTR, errhp);

  (void) OCIAttrSet((void *) ctxedesc, (ub4) OCI_DTYPE_PARAM,
                 (void *) "VALUE2", (ub4) strlen((char *)"VALUE2"),
                 (ub4) OCI_ATTR_APPCTX_VALUE, errhp);
/****************************************/
  (void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
                 (void *) username, (ub4) strlen((char *)username),
                 (ub4) OCI_ATTR_USERNAME, errhp);

  (void) OCIAttrSet((void *) authp, (ub4) OCI_HTYPE_SESSION,
                 (void *) password, (ub4) strlen((char *)password),
                 (ub4) OCI_ATTR_PASSWORD, errhp);

  OCISessionBegin ( svchp,  errhp, authp, OCI_CRED_EXT, (ub4) OCI_DEFAULT);

}

Multiple SET Operations

Use the OCIAppCtxSet() function to perform a series of set operations on the "responsibility" attribute in the CLIENTCONTEXT namespace. When this information is sent to the server, the latest value prevails for that particular attribute in a namespace. To change the value of the "responsibility" attribute in the CLIENTCONTEXT namespace from "manager" to "vp", use the code fragment shown in Example 8-15, on the client side. When this information is transported to the server, the server shows the latest value "vp" for the "responsibility" attribute in the CLIENTCONTEXT namespace.

err = OCIAppCtxSet((void *) sesshndl,(void *)"CLIENTCONTEXT",(ub4) 13,
                   (void *)"responsibility", 14
                   (void *)"manager", 7, errhp, OCI_DEFAULT);
err = OCIAppCtxSet((void *) sesshndl, (void*)"CLIENTCONTEXT", 13,
                   (void *)"responsibility", 14,(void *)"vp",2, errhp,
                   OCI_DEFAULT);

You can clear specific attribute information in a client namespace. This can be done by setting the value of an attribute to NULL or to an empty string, as shown in Example 8-16 using the OCIAppCtxSet() function.

(void) OCIAppCtxSet((void *) sesshndl, (void *)"CLIENTCONTEXT", 13,
                    (void *)"responsibility", 14, (void *)0, 0,errhp,
                    OCI_DEFAULT);

(void) OCIAppCtxSet((void *) sesshndl, (void *)"CLIENTCONTEXT", 13
                    (void *)"responsibility", 14, (void *)"", 0,errhp,
                     OCI_DEFAULT);

CLEAR-ALL Operations Between SET Operations

You can clear all the context information in a specific client namespace, using the OCIAppCtxClearAll() function, and it will also be cleared on the server-side user session, during the next network transport.

If the client application performs a clear-all operation in a namespace after several set operations, then values of all attributes in that namespace that were set before this clear-all operation are cleaned up on the client side and the server side. Only the set operations that were done after the clear-all operation are reflected on the server side. On the client side, the code appears, as shown in Example 8-17.

err = OCIAppCtxSet((void *) sesshndl,(void *)"CLIENTCONTEXT", 13,
                   (void *)"responsibility", 14,
                   (void *)"manager", 7,errhp, OCI_DEFAULT);
err = OCIAppCtxClearAll((void *) sesshndl, (void *)"CLIENTCONTEXT", 13, errhp,
                        OCI_DEFAULT);
err = OCIAppCtxSet((void *) sesshndl, (void*)"CLIENTCONTEXT",13
                   (void *)"office",6, (void *)"2op123", 5, errhp, OCI_DEFAULT);

The clear-all operation clears any information set by earlier operations in the namespace CLIENTCONTEXT: "responsibility" = "manager" is removed. The information that was set subsequently will not be reflected on the server side.

Network Transport and PL/SQL on Client Namespace

It is possible that an application could send application context information on an OCIStmtExecute() call to the server, and also attempt to change the same context information during that call by executing the DBMS_SESSION package.

In general, on the server side, the transported information is processed first and the main call is processed later. This behavior applies to the application context network transports as well.

If they are both writing to the same client namespace and attribute set, then the main call's information overwrites the information set provided by the fast network transport mechanism. If an error occurs in the network transport call, the main call is not executed.

However, an error in the main call does not affect the processing of the network transport call. Once the network transport call is processed, then there is no way to undo it. When the error is reported to the caller (by an OCI function), it is reported as a generic ORA error. Currently, there is no easy way to distinguish an error in the network transport call from an error in the main call. The client should not assume that an error from the main call will undo the round-trip network processing and should implement appropriate exception-handling mechanisms to prevent any inconsistencies.

Controlling the Database Version Banner Displayed

The OCIServerVersion() function can be issued before authentication (on a connected server handle after calling OCIServerAttach()) to get the database version. To avoid disclosing the database version string before authentication, set the SEC_RETURN_SERVER_RELEASE_BANNER initialization parameter to NO. For example:

SEC_RETURN_SERVER_RELEASE_BANNER = NO

This displays the following string for Oracle Database Release 11.1 and all subsequent 11.1 releases and patch sets:

Oracle Database 11g Release 11.1.0.0.0 - Production

Set SEC_RETURN_SERVER_RELEASE_BANNER to YES and then the current banner is displayed. If you have installed Oracle Database Release 11.2.0.2, the banner displayed is:

Oracle Database 11g Enterprise Edition Release 11.2.0.2 - Production

This feature works with an Oracle Database Release 11.1 or later server, and any version client.

Banners for Unauthorized Access and User Actions Auditing

The following systemwide parameters are in sqlnet.ora and warn users against unauthorized access and possible auditing of user actions. These features are available in Oracle Database Release 11.1 and later servers and clients. The content of the banners is in text files that the database administrator creates. There is a 512 byte buffer limit for displaying the banner content. If this buffer limit is exceeded, the banner content will appear to be cut off. The access banner syntax is:

SEC_USER_UNAUTHORIZED_ACCESS_BANNER = file_path1

In this syntax, file_path1 is the path of a text file. To retrieve the banner, get the value of the attribute OCI_ATTR_ACCESS_BANNER from the server handle after calls to either OCIServerAttach() or OCISessionGet().

The audit banner syntax is:

SEC_USER_AUDIT_ACTION_BANNER = file_path2

In this syntax, file_path2 is the path of a text file. To retrieve the banner, get the value of the attribute OCI_ATTR_AUDIT_BANNER from the session handle after calls to either OCISessionBegin(), OCISessionGet(), OCILogon(), or OCILogon2().

Non-Deferred Linkage

Non-deferred linkage of applications is no longer supported and the Makefile is modified to remove it. This method of linking was used before OCI V7.

Advantages of OCI Thread Safety

The implementation of thread safety in OCI has the following advantages:

• Multiple threads of execution can make OCI calls with the same result as successive calls made by a single thread.

• When multiple threads make OCI calls, there are no side effects between threads.

• Users who do not write multithreaded programs do not pay a performance penalty for using thread-safe OCI calls.

• Use of multiple threads can improve program performance. Gains may be seen on multiprocessor systems where threads run concurrently on separate processors, and on single processor systems where overlap can occur between slower operations and faster operations.

OCI Thread Safety and Three-Tier Architectures

In addition to client/server applications, where the client can be a multithreaded program, a typical use of multithreaded applications is in three-tier (client-agent-server) architectures. In this architecture, the client is concerned only with presentation services. The agent (application server) processes the application logic for the client application. Typically, this relationship is a many-to-one relationship, with multiple clients sharing the same application server.

The server tier in this scenario is a database. The application server (agent) is very well suited to being a multithreaded application server, with each thread serving a single client application. In an Oracle Database environment, this application server is an OCI or precompiler program.

Implementing Thread Safety

To take advantage of thread safety, an application must be running on a thread-safe operating system. The application specifies that it is running in a multithreaded environment by making an OCIEnvNlsCreate() call with OCI_THREADED as the value of the mode parameter.

All subsequent calls to OCIEnvNlsCreate() must also be made with OCI_THREADED.

If an application is single-threaded, whether or not the operating system is thread-safe, the application must pass a value of OCI_DEFAULT to OCIEnvCreate() or OCIEnvNlsCreate(). Single-threaded applications that run in OCI_THREADED mode may incur lower performance.

If a multithreaded application is running on a thread-safe operating system, the OCI library manages mutexes for the application for each environment handle. An application can override this feature and maintain its own mutex scheme by specifying a value of OCI_ENV_NO_MUTEX in the mode parameter of either the OCIEnvCreate() or OCIEnvNlsCreate() calls.

The following scenarios are possible, depending on how many connections exist in each environment handle, and how many threads are spawned in each connection.

• If an application has multiple environment handles, with a single thread in each, mutexes are not required.

• If an application running in OCI_THREADED mode maintains one or more environment handles, with multiple connections, it has these options:

  • Pass a value of OCI_ENV_NO_MUTEX for the mode of OCIEnvNlsCreate(). The application must set mutual exclusion locks (mutex) for OCI calls made on the same environment handle. This has the advantage that the mutex scheme can be optimized to the application design. The programmer must also ensure that only one OCI call is in process on the environment handle connection at any given time.

  • Pass a value of OCI_DEFAULT for the mode of OCIEnvNlsCreate(). The OCI library automatically gets a mutex on every OCI call on the same environment handle.

    Note:

    Most processing of an OCI call happens on the server, so if two threads using OCI calls go to the same connection, then one of them can be blocked while the other finishes processing at the server.

    Use one error handle for each thread in an application, because OCI errors can be overwritten by other threads.

Initialization and Termination

The types and functions described in this section are associated with the initialization and termination of the OCIThread package. OCIThread must be initialized before you can use any of its functionality.

The observed behavior of the initialization and termination functions is the same regardless of whether OCIThread is in a single-threaded or a multithreaded environment. Table 8-6 lists functions for thread initialization and termination.

Passive Threading Primitives

The passive threading primitives deal with the manipulation of mutex, thread IDs, and thread-specific data. Because the specifications of these primitives do not require the existence of multiple threads, they can be used both in multithreaded and single-threaded operating systems. Table 8-7 lists functions used to implement passive threading.

Active Threading Primitives

The active threading primitives deal with manipulation of actual threads. Because specifications of most of these primitives require multiple threads, they work correctly only in the enabled OCIThread. In the disabled OCIThread, they always return an error. The exception is OCIThreadHandleGet(); it may be called in a single-threaded environment and has no effect.

Active primitives can only be called by code running in a multithreaded environment. You can call OCIThreadIsMulti() to determine whether the environment is multithreaded or single-threaded. Table 8-8 lists functions used to implement active threading.