Open (OBinder) Method

Applies To

OBinder

Description

This method opens an OBinder object, making it useful.

Usage

OBinder: oresult Open(const char *dbname, const char *username, const char *pwd, const char *sqls, long dynopts)

OBinder: oresult Open(const ODatabase &odb, const char *sqls, long dynopts)

OBinder: oresult Open(const ODatabase &odb, const char *sqlstmt, unsigned int slicesize, unsigned int perblock, unsigned int blocks, unsigned int fetchlimit, unsigned int fetchsize, long options = ODYNASET_DEFAULT)

Arguments	Description
dbname	The name of the database to which to connect.
username	The username to use to log into the database.
pwd	The database password for the user username.
odb	The database with which you want to open the OBinder's dynaset.
sqls	A valid select SQL statement.
dynopts	Options to be used to create the dynaset.
sqlstmt	A valid select SQL statement.
options	Options to be used to create the dynaset.
slicesize	Cache slice size.
perblock	Cache slices per block.
blocks	Cache maximum number of blocks.
fetchlimit	Fetch array size.
fetchsize	Fetch array buffer size.

Remarks

To Open an OBinder object for work, you need to connect it to an Oracle database and select a set of records. Opening an OBinder object is like opening both an ODatabase and an ODynaset.

The OBinder object needs to connect to a database. You can supply the database directly with an ODatabase argument, or you can give the connection information: database name, username, and password. If you choose the latter method, note that the database will be created with ODATABASE_DEFAULT set for its options.

The third Open method opens the OBinder object using custom cache and fetch parameters.

The OBinder object also needs a dynaset. The dynaset is created using the database specified by the arguments listed above, and by the sqlstmt and dynopts arguments. These arguments act identically as the arguments to an ODynaset Open. Note that whenever an OBinder opens a dynaset, it always moves immediately to the first record.

The dynopts argument can have the following values:

dynopts Argument Values

Constant	Value	Description
ODYNASET_DEFAULT	0	Accept the default behavior.
ODYNASET_NOBIND	1	Do not perform automatic binding of database parameters.
ODYNASET_KEEP_BLANKS	2	Do not strip trailing blanks from character string data retrieved from the database.
ODYNASET_READONLY	4	Force dynaset to be read-only.
ODYNASET_NOCACHE	8	Do not create a local dynaset data cache. Without the local cache, previous rows within a dynaset are unavailable; however, increased performance results during retrieval of data from the database (move operations) and from the rows (field operations). Use this option in applications that make single passes through the rows of a dynaset for increased performance and decreased resource usage.

Options may be combined by adding their respective values.

These values can be found in the file ORCL.H.

Open(OBinder) calls the PreQuery and PostQuery triggers. The OBinder Startup trigger will not be called until the first OBound object is bound to the OBinder.

It is legal (though unusual) to open an already open OBinder. The OBinder's dynaset is closed, then reopened. Note that this does not affect an OBinder's bound OBound objects - they are still bound.

If OBound objects are already bound to an OBinder, but do not represent valid column names in the SQL query, Open will fail. This can happen when OBound objects are bound prior to calling OBinder::Open or when opening an already open OBinder.

Return Value

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

Example

An example of setting up an OBinder object:

// construct the OBinder

OBinder empblock;

// we normally then bind OBound objects to the OBinder

// here we have several OBoundVal objects (see the Workbook)

OBoundVal salary;

OBoundVal ename;

// bind them

salary.BindToBinder(&empblock, "sal");

/*

That is the first thing bound, so the OBinder::Startup trigger is called.

*/

ename.BindToBinder(&empblock, "ename");

/*

The OBound::Startup trigger is called on each OBound as it is bound.

*/

// now open the OBinder

ODatabase odb("ExampleDB", "scott", "tiger"); // open the database

empblock.Open(odb, "select * from emp order by ename");

// that calls all the PreQuery and PostQuery triggers