Open (ODatabase) Method

Applies To

Description

This method opens an ODatabase, making it useful.

Usage

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

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

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

Arguments	Description

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

Remarks

These methods open the ODatabase object. Opening an ODatabase object establishes a connection to an Oracle database and specifies certain kinds of behavior.

You can specify the session in which you want the database to work; if you do not specify a session, the database works in the default session. The session under which the database is opened affects connection sharing and transaction processing. Use dbsess to specify the session.

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 following options are available for the ODatabase at the time it is opened. These options are ORed together on the Open method call. They affect operations on dynasets attached to this database.

Open Method Options

Constant	Value	Description
ODATABASE_DEFAULT	0	Default Mode Field (column) values not explicitly set are set to NULL when using AddNewRecord or StartEdit. The NULL values override any server column defaults. Wait on row locks when using Edit ("SELECT... FOR UPDATE"). Non-blocking SQL functionality will not be enabled.
ODATABASE_ORAMODE (Formerly ODATABASE_PARTIAL_INSERT)	1	Oracle Mode Let Oracle database set the default field (column) values when using AddNewRecord or StartEdit. The Oracle default column values are refetched from database immediately after the insert or add operation. Note: If you use triggers, we recommend you refetch data using the full Oracle Mode.
ODATABASE_EDIT_NOWAIT	2	Lock No-Wait Mode Do not wait on row locks. When you use StartEdit to update a row that is locked by another user or process, Lock No-Wait mode results in an immediate return of an error code. Note: (1) Lock No-Wait modes also affect any SQL statements processed using ExecuteSQL. (2) This option may be of limited use with Dynasets based on heavily used tables. As documented, this option causes ORA 54 errors to occur with Row Locks. But it will also do the same for other resource contentions. In certain cases a considerable number of ORA 54 errors may be raised. You will want to test your application with a realistic database load to see if this affects you.
ODATABASE_NO_REFETCH	4	Oracle Mode (No Refetch) Like Oracle Mode, but data is not refetched to the local cache, boosting performance. Caution: Use the No Refetch mode only when you intend to insert rows without editing them, because server column defaults will cause inconsistencies between server data and the local cache. Attempting to edit after inserting in this mode will cause a "Data has been modified" (4119) error.
ODATABASE_NONBLOCK	8	Non-Blocking Mode This mode turns on Non-Blocking mode on SQL statement execution. Non-Blocking mode affects the SQL statements processed using the ExecuteSQL, CreateDynaset or CreateSQL methods. Note that this parameter only applies to Windows 3.1 where it is used solely to prevent hanging during cooperative multitasking. It has no effect in Windows 95 or NT, in which cases the parameter is ignored. You cannot use this parameter to implement non-blocking via polling or other asynchronous callbacks.

Options may be combined by adding their respective values. These values can be found in the file ORCL.H.

Two separate database objects share an Oracle database connection if they are in the same session and have the same connection information (database name, username, and password).

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

It is legal to Open an already open ODatabase. The ODatabase is closed and then opened with the new arguments. Note that if you do this, any ODynasets that were opened with the old ODatabase still work and are still connected to the old database object. Only the ODatabase handle object is affected.

Return Value

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

Example

An example of opening ODatabase objects:

// the simplest way to open a database

ODatabase odb;

odb.Open("ExampleDB", "scott", "tiger");

// now if we open another database similarly

ODatabase odb2;

odb2.Open("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;

odb3.Open(msess, "ExampleDB", "scott", "tiger");

/*

odb3 does not share a connection with odb, because it is on a different session.

*/