Connection Class

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

FailOverEventType

FailOverType

ProxyType

changePassword()

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

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

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

user

oldPassword

newPassword

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.

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

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

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

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

sql

tag

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)

majorVersion

minorVersion

updateNum

patchNumber

portUpdateNumber

getCollectionAccessMode()

Returns the collection access mode, CollectionAccessMode, defined in Table 13-11, "Enumerated Values Used by Connection Class".

Syntax

CollectionAccessMode getCollectionAccessMode() cosnt;

getDefaultPinOption()

Returns the default pin option, PinOption, defined in Table 13-11, "Enumerated Values Used by Connection Class".

Syntax

PinOption getDefaultPinOption() const;

getMetaData()

Returns metadata for an object in the database.

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

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

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

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.

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

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

sql

tag

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.

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

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

conn

vect

vectObj

lockOpt

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;

sub

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);

conn

vec

byteAmts

offsets

buffers

bufferLengths

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);

conn

vec

byteAmts

offsets

buffers

bufferLengths

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.

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

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

conn

vec

byteAmts

charAmts

offsets

buffers

bufferLengths

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;

sub

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;

setCollectionAccessMode()

Disables or enables caching of collections on demand.

Syntax

void setCollectionAccessMode(
   CollectionAccessMode mode);

mode

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;

cacheSize

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)

notifyFn

env

conn

ctx

foType

ctxTAF

terminateStatement()

Closes a Statement object.

void terminateStatement(
   Statement *stmt)=0;

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

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

stmt

tag

unregisterSubscription()

Unregisters a Subscription, turning off its notifications.

Syntax

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

sub

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);

conn

vec

byteAmts

offsets

buffers

bufferLengths

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.

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

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

conn

vec

byteAmts

charAmts

offsets

buffers

bufferLengths