|Oracle Call Interface Programmer's Guide
Release 2 (9.2)
Part Number A96584-01
OCI Relational Functions, 11 of 38
Creates an access path to a data source for OCI operations.
sword OCIServerAttach ( OCIServer *srvhp, OCIError *errhp, CONST text *dblink, sb4 dblink_len, ub4 mode );
An uninitialized server handle, which gets initialized by this call. Passing in an initialized server handle causes an error.
An error handle you can pass to
OCIErrorGet() for diagnostic information in the event of an error.
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 pointer may be freed by the caller on return.
The name of the connection pool to connect to when
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.
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
Specifies the various modes of operation. The valid modes are:
Since an attached server handle can be set for any connection session handle, the
mode value here does not contribute to any session handle.
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.
OCIServerAttach() is successfully completed, an Oracle shadow process is started.
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.
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);