Connection Class

The Connection class represents a connection with a specific database. Inside the connection, SQL statements are executed and results are returned.

Table 13-11 Enumerated Values Used by Connection Class

Attribute Options
FailOverEventType
  • FO_BEGIN indicates that a lost connection has been detected; failover is starting.

  • FO_END indicates that a failover completed successfully; the Connection is ready for use.

  • FO_ABORT indicates that the failover was unsuccessful; it is not be attempted again.

  • FO_REAUTH indicates that the user session has been reauthenticated.

  • FO_ERROR indicates that a failover was unsuccessful; the application can handle the error and retry failover.

FailOverType
  • FO_NONE indicates that the user requested no protection for failover.

  • FO_SESSION indicates that the user requested only session failover.

  • FO_SELECT indicates that the use requested select failover.

ProxyType
  • PROXY_DEFAULT is the database user name.

Table 13-12 Summary of Connection Methods

Method Summary

changePassword()

Changes the password for the current user.

commit()

Commits changes made since the previous commit or rollback and release any database locks held by the session.

createStatement()

Creates a Statement object to execute SQL statements.

flushCache()

Flushes the object cache associated with the connection.

getClientCharSet()

Returns the default client character set.

getClientCharSetUString()

Returns the globalization enabled client character set in UString.

getClientNCHARCharSet()

Returns the default client NCHAR character set.

getClientNCHARCharSetUString()

Returns the globalization enabled client NCHAR character set in UString.

getClientVersion()

Returns the version of the client used.

getLTXID()

Returns logical transaction id that may be used in various calls of package DBMS_APP_CONT.

getMetaData()

Returns the metadata for an object accessible from the connection.

getOCIServer()

Returns the OCI server context associated with the connection.

getOCIServiceContext()

Returns the OCI service context associated with the connection.

getOCISession()

Returns the OCI session context associated with the connection.

getServerVersion()

Returns the version of the Oracle server used, as string.

getServerVersionUString()

Returns the version of the Oracle server used, as a UString.

getStmtCacheSize()

Retrieves the size of the statement cache.

getTag()

Returns the tag associated with the connection.

isCached()

Determines if the specified statement is cached.

pinVectorOfRefs()

Pins an entire vector of Ref objects into object cache in a single round trip; pinned objects are available through an OUT parameter vector.

postToSubscriptions()

Posts notifications to subscriptions.

readVectorOfBfiles()

Reads multiple Bfiles in a single server round-trip.

readVectorOfBlobs()

Reads multiple Blobs in a single server round-trip.

readVectorOfClobs()

Reads multiple Clobs in a single server round-trip.

registerSubscriptions()

Registers several Subscriptions for notification.

rollback()

Rolls back all changes made since the previous commit or rollback and release any database locks held by the session.

setStmtCacheSize()

Enables or disables statement caching.

setTAFNotify()

Registers failover callback function on the Connection object.

terminateStatement()

Closes a Statement object and free all resources associated with it.

unregisterSubscription()

Unregisters a Subscription, turns off its notifications.

writeVectorOfBlobs()

Writes multiple Blobs in a single server round-trip.

writeVectorOfClobs()

Writes multiple Clobs in a single server round-trip.

changePassword()

Changes the password of the user currently connected to the database.

Syntax Description
void changePassword(
   const string &user,
   const string &oldPassword,
   const string &newPassword)=0;

Changes the password of the user.

void changePassword(
   const UString &user,
   const UString &oldPassword,
   const UString &newPassword)=0;

Changes the password of the user (Unicode support). The client Environment should be initialized in OCCIUTIF16 mode.

Parameter Description
user

The user currently connected to the database.

oldPassword

The current password of the user.

newPassword

The new password of the user.

commit()

Commits all changes made since the previous commit or rollback, and releases any database locks currently held by the session.

Syntax

void commit()=0;

createStatement()

Creates a Statement object with the SQL statement specified.

Note that for the caching-enabled version of this method, the cache is initially searched for a statement with a matching tag, which is returned. If no match is found, the cache is searched again for a statement that matches the sql parameter, which is returned. If no match is found, a new statement with a NULL tag is created and returned. If the sql parameter is empty and the tag search fails, this call generates an ERROR.

Also note that non-caching versions of this method always create and return a new statement.

Syntax Description
Statement* createStatement(
   const string &sql="")=0;

Searches the cache for a specified SQL statement and returns it; if not found, creates a new statement.

Statement* createStatement(
   const string &sql,
   const string &tag)=0;

Searches the cache for a statement with a matching tag; if not found, creates a new statement with the specified SQL content.

Statement* createStatement(
   const UString &sql)=0;

Searches the cache for a specified SQL statement and returns it; if not found, creates a new statement. Globalization enabled.

Statement* createStatement(
   const Ustring &sql,
   const Ustring &tag)=0;

Searches the cache for a matching tag and returns it; if not found, creates a new statement with the specified SQL content. Globalization enabled.

Parameter Description
sql

The SQL string to be associated with the statement object.

tag

The tag whose associated statement must be retrieved from the cache. Ignored if statement caching is disabled.

flushCache()

Flushes the object cache associated with the connection.

Syntax

void flushCache()=0;

getClientCharSet()

Returns the session's character set.

Syntax

string getClientCharSet() const=0;

getClientCharSetUString()

Returns the globalization enabled client character set in UString.

Syntax

UString getClientCharSetUString() const=0;

getClientNCHARCharSet()

Returns the session's NCHAR character set.

Syntax

string getClientNCHARCharSet() const=0;

getClientNCHARCharSetUString()

Returns the globalization enabled client NCHAR character set in UString.

Syntax

UString getClientNCHARCharSetUString() const=0;

getClientVersion()

Returns the version of the client library the application is using at run time.

This is used by applications to determine the version of the OCCI client at run time, and if the application uses several separate code paths that use several different client patchsets.

The values of parameters majorVersion and minorVersion use macros OCCI_MAJOR_VERSION and OCCI_MINOR_VERSION, respectively. These macros define the major and minor versions of the OCCI client library. Compares the versions returned.

Syntax

void getClientVersion(
   int &majorVersion,
   int &minorVersion,
   int &updateNum,
   int &patchNumber,
   int &portUpdateNum)
Parameter Description
majorVersion

The major version of the client library.

minorVersion

The minor version of the client library.

updateNum

The update number.

patchNumber

The number of the patch applied to the library.

portUpdateNumber

The number of the port-specific port update applied to the library.

getLTXID()

Returns logical transaction id that may be used in various calls of package DBMS_APP_CONT.

Syntax

Bytes getLTXID() const = 0

getMetaData()

Returns metadata for an object in the database.

Syntax Description
MetaData getMetaData(
   const string &object,
   MetaData::ParamType prmtyp=MetaData::PTYPE_UNK) const=0;

Returns metadata for an object in the database.

MetaData getMetaData(
   const UString &object,
   MetaData::ParamType prmtyp=MetaData::PTYPE_UNK) const=0;

Returns metadata for a globalization enabled object in the database.

MetaData getMetaData(
   const RefAny &ref) const=0;

Returns metadata for an object in the database through a reference.

Parameter Description

object

The SQL string to be associated with the statement object.

prmtyp

The type of the schema object being described, as defined by the enumerated ParamType of the MetaData class, Table 13-27

ref

A REF to the Type Descriptor Object (TDO) of the type to be described.

getOCIServer()

Returns the OCI server context associated with the connection.

Syntax

OCIServer* getOCIServer() const=0;

getOCIServiceContext()

Returns the OCI service context associated with the connection.

Syntax

OCISvcCtx* getOCIServiceContext() const=0;

getOCISession()

Returns the OCI session context associated with the connection.

Syntax

OCISession* getOCISession() const=0;

getServerVersion()

Returns the version of the database server, as a string, used by the current Connection object. This can be used when an application uses several separate code paths and connects to several different server versions.

Syntax

string getServerVersion() const;

getServerVersionUString()

Returns the version of the database server, as a UString, used by the current Connection object. This can be used when an application uses several separate code paths and connects to several different server versions.

Syntax

UString getServerVersionUString() const;

getStmtCacheSize()

Retrieves the size of the statement cache.

Syntax

unsigned int getStmtCacheSize() const=0;

getTag()

Returns the tag associated with the connection. Valid only for connections from a stateless connection pool.

Syntax

string getTag() const=0;

isCached()

Determines if the specified statement is cached.

Syntax Description
bool isCached(
   const string &sql,
   const string &tag="")=0;

Searches the cache for a statement with a matching tag. If the tag is not specified, the cache is searched for a matching SQL statement.

bool isCached(
   const Ustring &sql,
   const Ustring &tag)=0;

Searches the cache for a statement with a matching tag. If the tag is not specified, the cache is searched for a matching SQL statement. Globalization enabled.

Parameter Description
sql

The SQL string to be associated with the statement object.

tag

The tag whose associated statement must be retrieved from the cache. Ignored if statement caching is disabled.

pinVectorOfRefs()

Pins an entire vector of Ref objects into object cache in a single round-trip. Pinned objects are available through an OUT parameter vector.

Syntax Description
template <class T> void pinVectorOfRefs(
   const Connection *conn,
   vector <Ref<T>> & vect,
   vector <T*> &vectObj,
   LockOptions lockOpt=OCCI_LOCK_NONE);

Returns the objects.

template <class T> void pinVectorOfRefs(
   const Connection *conn,
   vector <Ref<T>> & vect,
   LockOptions lockOpt=OCCI_LOCK_NONE);

Does not explicitly return the objects; an application must dereference a particular Ref object by a ptr() call, which returns a previously pinned object.

Parameter Description
conn

Connection

vect

Vector of Ref objects that are pinned.

vectObj

Vector that contains objects after the pinning operation is complete; an OUT parameter.

lockOpt

Lock option used during the pinning of the array, as defined by LockOptions in Table 13-2. The only supported value is OCCI_LOCK_NONE.

postToSubscriptions()

Posts notifications to subscriptions.

The Subscription object must have a valid subscription name, and the namespace should be set to NS_ANONYMOUS. The payload must be set before invoking this call; otherwise, the payload is assumed to be NULL and is not delivered.

The caller has to preserve the payload until the posting call is complete. This call provides a best-effort guarantee; a notification is sent to registered clients at most once.This call is primarily used for light-weight notification and is useful for dealing with several system events. If the application needs more rigid guarantees, it can use the Oracle Streams Advanced Queuing functionality.

Syntax

void postToSubscriptions(
   const vector<aq::Subscription>& sub)=0;
Parameter Description
sub

The vector of subscriptions that receive postings.

readVectorOfBfiles()

Reads multiple Bfiles in a single server round-trip. All Bfiles must be open for reading.

Syntax

void readVectorOfBfiles(
   const Connection *conn,
   vector<Bfile> &vec,
   oraub8 *byteAmts, 
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);
Parameter Description
conn

Connection.

vec

Vector of Bfile objects; each Bfile must be open for reading.

byteAmts

Array of amount of bytes to read from the individual Bfiles. The actual number of bytes read from each Bfile is returned in this array.

offsets

Array of offsets, starting position where reading from the Bfiles starts.

buffers

Array of pointers to buffers into which the data is read.

bufferLengths

Array of sizes of each buffer, in bytes.

readVectorOfBlobs()

Reads multiple BLOBs in a single server round-trip.

Syntax

void readVectorOfBlobs(
   const Connection *conn,
   vector<Blob> &vec,
   oraub8 *byteAmts, 
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);
Parameter Description
conn

Connection.

vec

Vector of Blob objects.

byteAmts

Array of amount of bytes to read from the individual Blobs. The actual number of bytes read from each Blob is returned in this array.

offsets

Array of offsets, starting position where reading from the Blobs starts.

buffers

Array of pointers to buffers into which the data is read.

bufferLengths

Array of sizes of each buffer, in bytes.

readVectorOfClobs()

Reads multiple Clobs in a single server round-trip. All Clobs should be in the same characterset form and belong to the same characterset ID.

Syntax Description
void readVectorOfClobs(
   const Connection *conn,
   vector<Clob> &vec,
   oraub8 *byteAmts, 
   araub8 *charAmts,
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);

General form of the method.

void readVectorOfClobs(
   const Connection *conn,
   vector<Clob> &vec,
   oraub8 *byteAmts, 
   araub8 *charAmts,
   oraub8 *offsets, 
   utext *buffers[], 
   oraub8 *bufferLengths);

Form of the method used with utext buffers, when data is in UTF16 characterset encoding.

Parameter Description
conn

Connection.

vec

Vector of Clob objects.

byteAmts

Array of amount of bytes to read from the individual Clobs. Only used if the charAmts is NULL, or 0 for any Clob index. Returns the number of bytes read for each Clob.

charAmts

Array of amount of characters to read from individual Clobs. Returns the number of characters read for each Clob.

offsets

Array of offsets, starting position where reading from the Clobs starts, in characters.

buffers

Array of pointers to buffers into which the data is read.

bufferLengths

Array of sizes of each buffer, in bytes.

registerSubscriptions()

Registers Subscriptions for notification.

New client processes and existing processes that restart after a shut down must register for all subscriptions of interest. If the client stays up during a server shut down and restart, this client continues to receive notifications for DISCONNECTED registrations, but not for CONNECTED registrations because they are lost during the server down time.

Syntax

void registerSubscriptions(
   const vector<aq::Subscription>& sub)=0;
Parameter Description
sub

Vector of subscriptions that are registered for notification.

rollback()

Drops all changes made since the previous commit or rollback, and releases any database locks currently held by the session.

Syntax

void rollback()=0;

setStmtCacheSize()

Enables or disables statement caching. A nonzero value enables statement caching, with a cache of specified size. A zero value disables caching.

Syntax

void setStmtCacheSize(
   unsigned int cacheSize)=0;
Parameter Description
cacheSize

The maximum number of statements in the cache.

setTAFNotify()

Registers the failover callback function on the Connection object for which failover is configured and must be detected.

The failover callback should return OCCI_SUCCESS to indicate that OCCI can continue with default processing. The failover event, foEvent, is defined in Table 13-11. When the foEvent is FO_ERROR, the callback function may return either FO_RETRY to indicate that failover must be attempted again, or OCCI_SUCCESS to end failover attempts.

Syntax

void setTAFNotify(
   int (*notifyFn)(
      Environment *env,
      Connection *conn,
      void *ctx,
      FailOverType foType,
      FailOverEventType foEvent),
   void *ctxTAF)
Parameter Description
notifyFn

The user defined callback function invoked during failover events.

env

Environment object from which the failing Connection was created.

conn

The failing Connection on which the callback function is registered.

ctx

Context supplied by the user when registering the callback.

foType

The configured FailOverType, values FO_SESSION or FO_SELECT, as defined in Table 13-11.

foEvent

Failover event type that is triggering the callback; the FailOverEventType, values FO_BEGIN, FO_END, FO_ABORT and FO_ERROR as defined in Table 13-11.

ctxTAF

User context passed back to the callback function at invocation.

terminateStatement()

Closes a Statement object.

Syntax Description
void terminateStatement(
   Statement *stmt)=0;

Closes a Statement object and frees all resources associated with it.

void terminateStatement(
   Statement *stmt,
   const string &tag)=0;

Releases statement back to the cache after adding an optional tag, a string.

void terminateStatement(
   Statement* stmt,
   const UString &tag) = 0;

Releases statement back to the cache after adding an optional tag, a UString.

Parameter Description
stmt

The Statement to be closed.

tag

The tag associated with the statement, either a string or a UString.

unregisterSubscription()

Unregisters a Subscription, turning off its notifications.

Syntax

void unregisterSubscription(
   const aq::Subscription& sub)=0;
Parameter Description
sub

Subscription whose notifications is turned off.

writeVectorOfBlobs()

Writes multiple Blobs in a single server round-trip.

Syntax

void writeVectorOfBlobs(
   const Connection *conn,
   vector<Blob> &vec,
   oraub8 *byteAmts, 
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);
Parameter Description
conn

Connection.

vec

Vector of Blob objects.

byteAmts

Array of amount of bytes to write to the individual Blobs.

offsets

Array of offsets, starting position where writing to the Blobs starts.

buffers

Array of pointers to buffers from which the data is written.

bufferLengths

Array of sizes of each buffer, in bytes.

writeVectorOfClobs()

Writes multiple Clobs in a single server round-trip. All Clobs should be in the same characterset form and belong to the same characterset ID.

Syntax Description
void writeVectorOfClobs(
   const Connection *conn,
   vector<Clob> &vec,
   oraub8 *byteAmts, 
   araub8 *charAmts,
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);

General form of the method.

void writeVectorOfClobs(
   const Connection *conn,
   vector<Clob> &vec,
   oraub8 *byteAmts, 
   araub8 *charAmts,
   oraub8 *offsets, 
   utext *buffers[], 
   oraub8 *bufferLengths);

Form of the method used with utext buffers, when data is in UTF16 characterset encoding.

Parameter Description
conn

Connection.

vec

Vector of Clob objects.

byteAmts

Array of amount of bytes to write to the individual Clobs. Only used if the charAmts is NULL or 0 for any Clob index. Returns the number of bytes written for each Clob.

charAmts

Array of amount of characters to write to individual Clobs. Returns the number of characters read for each Clob.

offsets

Array of offsets, starting position where writing to the Clobs starts, in characters.

buffers

Array of pointers to buffers from which the data is written.

bufferLengths

Array of sizes of each buffer, in bytes.