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

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.