ODatabase Method

Applies To
ODatabase

Description
ODatabase constructor

Usage
ODatabase(void)

ODatabase(const ODatabase &otherdb)

ODatabase(const OSession &dbsess, const char *dbname, const char *username, const char *pwd, long options = ODATABASE_DEFAULT)

ODatabase(const char *dbname, const char *username, const char *pwd, long options = ODATABASE_DEFAULT)

ODatabase(const OServer &server, const char *username, const char *pwd, long options = ODATABASE_DEFAULT);

Arguments

otherdb	The ODatabase object you are copying
dbsess	The session under which you want to open this database.
dbname	The name of the database to connect to.
server
username	The username to use to log into the database.
pwd	The database password for the user username.
options	Options to be used to create the database object.

Remarks
These methods construct a new ODatabase instance.

The default constructor constructs an unopened ODatabase object. It cannot fail. You must open the object before you can use it.

The copy constructor copies another ODatabase object. If that other ODatabase object is open - which means it is a handle on an implementation database object - the new ODatabase object becomes a handle to that same database object. The copy constructor copies the reference to the database object but does not copy any strings that the source ODatabase may own. The copy constructor can fail; check whether the new ODatabase is open after the constructor call.

The remaining two constructors both construct and attempt to open the ODatabase object. Opening an ODatabase object creates a new database object and may create other resources such as sessions and connections. Successful Opening of an ODatabase results in a connection to the Oracle database.

Use the optional dbsess argument to choose the session under which this database should opened. The session under which the database is opened affects connection sharing and transaction processing. If you do not specify a session, the application's default session is used.

Use the dbname, username, and pwd arguments to establish the connection to the database. The pwd argument is allowed to be NULL. In that case it is expected that the string passed to username will be of the form "username/password"; the "slash" character must be in the string. The database name will either be a SQL*Net alias, such as "ExampleDB" or a complete Oracle database name such as "p:namedpipe-server" or "t:123.45.987.06:SID" (network protocol identifier, network address, option instance id).

The options affect various aspects of the database's behavior. See ODatabase for more information.

The constructors that construct and open an ODatabase can fail; check whether the ODatabase object is open after the constructor call.

Example
An example of opening ODatabase objects:

// construct an unopened ODatabase

ODatabase odb;

// the simplest way to open a database

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

// now if we open another database similarly

ODatabase odb2("ExampleDB", "scott", "tiger", ODATABASE_EDIT_NOWAIT);

We have two separate database objects on the same oracle database but because odb2 and odb are in the same session and have the same connection information they share a database connection. But because of different options the two database objects will behave differently.

// open a database on a named session

OSession msess("mysession");

ODatabase odb3(msess, "ExampleDB", "scott", "tiger");

// odb3 does not share a connection with odb, because it is on

// a different session

// call a routine to open a database for us

// see the implementation below

ODatabase mydb = OpenADatabase("ExampleDB", "scott", "tiger");

mydb is being constructed with the copy constructor. It is copying

the temporary ODatabase that is the result of OpenADatabase

if (!mydb.IsOpen())

{ // that didn't work

return; // we give up

}

// etc...

// here's the routine OpenADatabase

ODatabase OpenADatabase(const char *db, const char *un,

const char *pw)

{

ODatabase tempdb;

// get a handle on the default session

// we need it for error handling later on

OSession defsess(0);

// attempt to open tempdb within the default session

tempdb.Open(defsess, db, un, pw);

if (!tempdb.IsOpen())

{ // some kind of error. Give the user a message

const char *errmsg = defsess.GetServerErrorText();

MessageBox(errmsg);

}

return(tempdb);

}

We always return tempdb. Returning an object like this works because of the copy constructor. The caller of OpenADatabase can tell if the routine worked or not by checking whether or not the returned ODatabase is open.

Contents