Oracle® C++ Call Interface Programmer's Guide 10g Release 2 (10.2) Part Number B14294-02 |
|
|
View PDF |
The Connection class represents a connection with a specific database. Within the context of a connection, SQL statements are executed and results are returned.
Table 12-11 Enumerated Values Used by Connection Class
Attribute | Options |
---|---|
ProxyType |
|
FailOverType |
|
FailOverEventType |
|
Table 12-12 Summary of Connection Methods
Method | Summary |
---|---|
|
Changes the password for the current user. |
|
Commits changes made since the previous commit or rollback and release any database locks held by the session. |
|
Creates a |
|
Flushes the object cache associated with the connection. |
|
Returns the default client character set. |
|
Returns the globalization enabled client character set in |
|
Returns the default client |
getClientNCHARCharSetUString() |
Returns the globalization enabled client |
|
Returns the version of the client used. |
|
Returns the metadata for an object accessible from the connection. |
|
Returns the OCI server context associated with the connection. |
|
Returns the OCI service context associated with the connection. |
|
Returns the OCI session context associated with the connection. |
|
Returns the version of the Oracle server used, as |
|
Returns the version of the Oracle server used, as a |
|
Retrieves the size of the statement cache. |
|
Returns the tag associated with the connection. |
|
Determines if the specified statement is cached. |
|
Pins an entire vector of |
|
Posts notifications to subscriptions. |
|
Reads multiple |
|
Reads multiple |
|
Reads multiple |
|
Registers several |
|
Rolls back all changes made since the previous commit or rollback and release any database locks held by the session. |
|
Enables or disables statement caching. |
|
Registers failover callback function on the |
|
Closes a |
|
Unregisters a |
|
Writes multiple |
|
Writes multiple |
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. |
Commits all changes made since the previous commit or rollback, and releases any database locks currently held by the session.
Syntax
void commit()=0;
Creates a Statement
object with the SQL statement specified.
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 needs to be retrieved from the cache. Ignored if statement caching is disabled. |
Note:
|
Flushes the object cache associated with the connection.
Syntax
void flushCache()=0;
Returns the session's character set.
Syntax
string getClientCharSet() const=0;
Returns the globalization enabled client character set in UString
.
Syntax
UString getClientCharSetUString() const=0;
Returns the session's NCHAR
character set.
Syntax
string getClientNCHARCharSet() const=0;
Returns the globalization enabled client NCHAR
character set in UString
.
Syntax
UString getClientNCHARCharSetUString() const=0;
Returns the version of the client library the application is using at runtime.
This is used by applications to determine the version of the OCCI client at runtime, and if the application uses several separate codepaths 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 mahor 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. |
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 12-26 |
ref | A REF to the Type Descriptor Object (TDO) of the type to be described. |
Returns the OCI server context associated with the connection.
Syntax
OCIServer* getOCIServer() const=0;
Returns the OCI service context associated with the connection.
Syntax
OCISvcCtx* getOCIServiceContext() const=0;
Returns the OCI session context associated with the connection.
Syntax
OCISession* getOCISession() const=0;
Returns the version of the databse server, as a string
, used by the current Connection
object. This can be used when an application uses several separate codepaths and connects to several different server versions.
Syntax
string getServerVersion() const;
Returns the version of the databse server, as a UString
, used by the current Connection
object. This can be used when an application uses several separate codepaths and connects to several different server versions.
Syntax
UString getServerVersionUString() const;
Retrieves the size of the statement cache.
Syntax
unsigned int getStmtCacheSize() const=0;
Returns the tag associated with the connection. Valid only for connections from a stateless connection pool.
Syntax
string getTag() const=0;
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 needs to be retrieved from the cache. Ignored if statement caching is disabled. |
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 needs to 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 will be pinned. |
vectObj |
Vector that will contain 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 12-2. The only supported value is OCCI_LOCK_NONE . |
Posts notifications to subscriptions.
The Subscription
object needs to have a valid subscription name, and the namespace should be set to NS_ANONYMOUS
. The payload needs to 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 in the case of 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. |
Reads multiple Bfile
s in a single server round-trip. All Bfile
s must already 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 Bfile s. The actual number of bytes read from each Bfile is returned in this array. |
offsets |
Array of offsets, starting position where reading from the Bfile s starts. |
buffers |
Array of pointers to buffers into which the data is read. |
bufferLengths |
Array of sizes of each buffer, in bytes. |
Reads multiple BLOB
s 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 Blob s. The actual number of bytes read from each Blob is returned in this array. |
offsets |
Array of offsets, starting position where reading from the Blob s starts. |
buffers |
Array of pointers to buffers into which the data is read. |
bufferLengths |
Array of sizes of each buffer, in bytes. |
Reads multiple Clob
s in a single server round-trip. All Clob
s 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 Clob s. 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 Clob s. Returns the number of characters read for each Clob . |
offsets |
Array of offsets, starting position where reading from the Clob s starts, in characters. |
buffers |
Array of pointers to buffers into which the data is read. |
bufferLengths |
Array of sizes of each buffer, in bytes. |
Registers Subscription
s 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 will continue 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 will be registered for notification. |
Drops all changes made since the previous commit or rollback, and releases any database locks currently held by the session.
Syntax
void rollback()=0;
Enables or disables statement caching. A nonzero value will enable statement caching, with a cache of specified size. A zero value will disable caching.
Syntax
void setStmtCacheSize( unsigned int cacheSize)=0;
Parameter | Description |
---|---|
cacheSize |
The maximum number of statements in the cache. |
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 12-11. When the foEvent
is FO_ERROR
, the callback function may return eiher 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 difined 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 12-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 12-11. |
ctxTAF |
User context passed back to the callback function at invocation. |
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 . |
Unregisters a Subscription
, turning off its notifications.
Syntax
void unregisterSubscription( const aq::Subscription& sub)=0;
Parameter | Description |
---|---|
sub |
Subscription whose notifications will be turned off. |
Writes multiple Blob
s 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 Blob s. |
offsets |
Array of offsets, starting position where writing to the Blob s starts. |
buffers |
Array of pointers to buffers from which the data is written. |
bufferLengths |
Array of sizes of each buffer, in bytes. |
Writes multiple Clob
s in a single server round-trip. All Clob
s 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 Clob s. 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 Clob s. Returns the number of characters read for each Clob . |
offsets |
Array of offsets, starting position where writing to the Clob s starts, in characters. |
buffers |
Array of pointers to buffers from which the data is written. |
bufferLengths |
Array of sizes of each buffer, in bytes. |