Close Method

Applies To

OAdvise, OClient, OConnection, OConnectionCollection, ODatabase, ODatabaseCollection, ODynaset, ODynasetMark, OField, OFieldCollection, OParameter, OParameterCollection, OSession, OSessionCollection, OAQ, OAQAgent, OAQMsg, OBfile, OBlob, OClob, OCollection, OException, OMDAttribute, OMetaData, OObject, ORef, OServer, OSnapshotID

Description

This method closes the object, freeing the connection with the underlying implementation object.

Usage

oresult Close(void)

Remarks

All objects that are instances of subclasses of OOracleObject are handles that reference some implementations object. This architecture allows the class objects to be very lightweight and easy to use. The relationship between an object and its implementation is established when the object is opened, either explicitly with an Open method or implicitly with some constructors or the assignment operator. Normally the relationship between the object and its implementation is dropped when the object is destroyed. It can also be dropped if the object is reopened. It can also be dropped explicitly by using the Close method.

Once all handles for an implementation object are closed (or destroyed), the implementation object will be destroyed. Because certain objects consume considerable resource when they are open (databases consume connections and dynasets consume a great deal for their local data cache), it is sometimes desirable to close handle objects (with the Close method) before they are destroyed. Use Close also if the OOracleObject is be a member of some class that you do not want to destroy, but you do want to free the implementation object.

Closed objects generally fail all operations, with the obvious exception of Open.

Return Value

An oresult indicating whether the operation succeeded (OSUCCESS) or not (OFAILURE).

Example

This example demonstrates when a database object is released.

// open an ODatabase. This creates an underlying database object

ODatabase odb("ExampleDB", "scott", "tiger");

// now we can do operations with this database object

odb.ExecuteSQL("drop table dontwantit");

// get another handle (ODatabase) on the same database

ODatabase odb2 = odb;

// now we close odb

odb.Close(); // that works

// try to use the database object (with a closed ODatabase)

odb.ExecuteSQL("drop table fooey"); // fails because odb is Closed

// now use an open ODatabase on the database object

// that odb referenced

odb2.ExecuteSQL("drop table fooey");

// that succeeded because odb2 is Open

// now close odb2

odb2.Close();

// that dropped odb2. Now the database connection is dropped because

// now all the handles on the database object have been closed.