Oracle® Objects for OLE C++ Class Library Developer's Guide 10g Release 2 (10.2) B14308-01 |
|
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.