OCIServerAttach()

Purpose

Creates an access path to a data source for OCI operations.

Syntax

sword OCIServerAttach ( OCIServer     *srvhp,
                        OCIError      *errhp,
                        CONST text    *dblink,
                        sb4           dblink_len,
                        ub4           mode );

Parameters

srvhp (IN/OUT)

An uninitialized server handle, which gets initialized by this call. Passing in an initialized server handle causes an error.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

dblink (IN)

Specifies the database server to use. This parameter points to a character string which specifies a connect string or a service point. If the connect string is null, then this call attaches to the default host. The string itself could be in UTF-16 or not, depending on mode or the setting in application's environment handle. The length of dblink is specified in dblink_len. The dblink pointer may be freed by the caller on return.

The name of the connection pool to connect to when mode = OCI_CPOOL. This must be the same as the poolName parameter of the connection pool created by OCIConnectionPoolCreate(). Must be in UTF-16 encoding in OCI_UTF16 environment mode.

dblink_len (IN)

The length of the string pointed to by dblink. For a valid connect string name or alias, dblink_len must be nonzero. Its value is in number of bytes.

The length of poolName, in number of bytes, regardless of the encoding, when mode = OCI_CPOOL.

mode (IN)

Specifies the various modes of operation. The valid modes are:

• OCI_DEFAULT. For encoding, this value tells the server handle to use the setting in the environment handle.
• OCI_CPOOL - use connection pooling,

Since an attached server handle can be set for any connection session handle, the mode value here does not contribute to any session handle.

Comments

This call is used to create an association between an OCI application and a particular server.

This call assumes that OCIConnectionPoolCreate() has already been called, giving poolName, when connection pooling is in effect.

This call initializes a server context handle, which must have been previously allocated with a call to OCIHandleAlloc(). The server context handle initialized by this call can be associated with a service context through a call to OCIAttrSet(). Once that association has been made, OCI operations can be performed against the server.

If an application is operating against multiple servers, multiple server context handles can be maintained. OCI operations are performed against whichever server context is currently associated with the service context.

When OCIServerAttach() is successfully completed, an Oracle shadow process is started. OCISessionEnd() and OCIServerDetach() should be called to clean up the Oracle shadow process. Otherwise, the shadow processes accumulate and cause the Unix system to run out of processes. If the database is restarted and there are not enough processes, the database may not startup.

Example

The following example demonstrates the use of OCIServerAttach(). This code segment allocates the server handle, makes the attach call, allocates the service context handle, and then sets the server context into it.

OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) 
     OCI_HTYPE_SERVER, 0, (dvoid **) &tmp);
OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) 
     OCI_HTYPE_SVCCTX, 0, (dvoid **) &tmp);
/* set attribute server context in the service context */
OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *) srvhp, 
     (ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);

Related Functions

OCIServerDetach()