Conne ction Class

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 10-9 Summary of Connection Methods

Method	Summary
changePassword()	Change the password for the current user.
commit()	Commit changes made since the previous commit or rollback and release any database locks held by the session.
createStatement()	Create a `Statement` object to execute SQL statements.
flushCache()	Flush the object cache associated with the connection.
getClientCharSet()	Return the default client character set.
getClientCharSetUString()	Return the globalization enabled client character set in `UString`.
getClientNCHARCharSet()	Return the default client NCHAR character set.
getClientNCHARCharSetUString()	Return the globalization enabled client NCHAR character set in `UString`.
getMetaData()	Return the metadata for an object accessible from the connection.
getOCIServer()	Return the OCI server context associated with the connection.
getOCIServiceContext()	Return the OCI service context associated with the connection.
getOCISession()	Return the OCI session context associated with the connection.
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.
registerSubscriptions()	Register several `Subscription`s for notification.
rollback()	Roll back all changes made since the previous commit or rollback and release any database locks held by the session.
postToSubscriptions()	Posts notifications to subscriptions.
setStmtCacheSize()	Enables or disables statement caching.
terminateStatement()	Close a `Statement` object and free all resources associated with it.
unregisterSubscription()	Unregisters a `Subscription`, turning off its notifications

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);	Changes the password of the user.
void changePassword( const UString &user, const UString &oldPassword, const UString &newPassword);	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();

createStatement()

Creates a Statement object with the SQL statement specified.

Syntax	Description
Statement* createStatement( const string &sql);	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);	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);	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);	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:

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.
Non-caching versions of this method always create and return a new statement

flushCache()

Flushes the object cache associated with the connection.

Syntax

void flushCache();

getClientCharSet()

Returns the session's character set.

Syntax

string getClientCharSet() const;

getClientCharSetUString()

Returns the globalization enabled client character set in UString.

Syntax

UString getClientCharSetUString() const;

getClientNCHARCharSet()

Returns the session's NCHAR character set.

Syntax

string getClientNCHARCharSet() const;

getClientNCHARCharSetUString()

Returns the globalization enabled client NCHAR character set in UString.

Syntax

UString getClientNCHARCharSetUString() const;

getMetaData()

Returns metadata for an object in the database.

Syntax	Description
MetaData getMetaData( const string &object, MetaData::ParamType prmtyp=MetaData::PTYPE_UNK) const;	Returns metadata for an object in the database.
MetaData getMetaData( const UString &object, MetaData::ParamType prmtyp=MetaData::PTYPE_UNK) const;	Returns metadata for a globalization enabled object in the database.
MetaData getMetaData( const RefAny &ref);	Returns metadata for an object in the database through a reference.

Syntax

Description

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

Returns metadata for an object in the database.

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

Returns metadata for a globalization enabled object in the database.

MetaData getMetaData(
   const RefAny &ref);

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

Parameter	Description
obj	The SQL string to be associated with the statement object.
prmtyp	The type of the schema object being described. The possible values for this are enumerated by `MetaData::ParamType`. Valid values are: `PTYPE_TABLE`—table `PTYPE_VIEW`—view `PTYPE_PROC`—procedure `PTYPE_FUNC`—function `PTYPE_PKG`—package `PTYPE_TYPE`—type `PTYPE_TYPE_ATTR`—attribute of a type `PTYPE_TYPE_COLL`—collection type information `PTYPE_TYPE_METHOD`—a method of a type `PTYPE_SYN`—synonym `PTYPE_SEQ`—sequence `PTYPE_COL`—column of a table or view `PTYPE_ARG`—argument of a function or procedure `PTYPE_TYPE_ARG`—argument of a type method `PTYPE_TYPE_RESULT`—the results of a method `PTYPE_SCHEMA`—schema `PTYPE_DATABASE`—database `PTYPE_UNK`—type unknown
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

LNOCIServer* getOCIServer() const;

getOCIServiceContext()

Returns the OCI service context associated with the connection.

Syntax

LNOCISvcCtx* getOCIServiceContext() const;

getOCISession()

Returns the OCI session context associated with the connection.

Syntax

LNOCISession* getOCISession() const;

getStmtCacheSize()

Retrieves the size of the statement cache.

Syntax

unsigned int getStmtCacheSize() const;

getTag()

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

Syntax

string getTag() const;

isCached()

Determines if the specified statement is cached.

Syntax	Description
bool isCached( const string &sql, const string &tag="");	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="");	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.

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

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.

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.

Syntax

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

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. The only value supported at this time is `OCCI_LOCK_NONE`.

rollback()

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

Syntax

void rollback();

postToSubscriptions()

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 Streams AQ functionality.

Syntax

void postToSubscriptions(
   const vector<Subscription>& sub);

Parameter	Description
sub	The vector of subscriptions that receive postings.

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 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<Subscription>& sub_list);

Parameter	Description
sub_list	Vector of subscriptions that will be registered for notification.

setStmtCacheSize()

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

Parameter	Description
size	The maximum number of statements in the cache.

terminateStatement()

Closes a Statement object.

Syntax	Description
void terminateStatement( Statement *statement);	Closes a `Statement` object and frees all resources associated with it.
void terminateStatement( Statement *statement, const string tag);	Release statement back to the cache after tagging it with the optional tag.

Parameter	Description
statement	The `Statement` to be closed.
tag	The tag associated with the statement.

unregisterSubscription()

Unregisters a Subscription, turning off its notifications.

Syntax

void unregisterSubscription(
   const Subscription& sub);

Parameter	Description
sub	`Subscription` whose notifications will be turned off.