ODynaset

The ODynaset class creates, manages, and accesses records of data from the database. It corresponds to a scrollable cursor. ODynaset is a subclass of OOracleObject.

An ODynaset is opened by executing a query against an Oracle database in the form of a SQL select statement. Any legal select statement is acceptable. All the database records that this query returns are referred to as the dynaset's result set. Records from the result set are fetched to the client as needed and cached locally. You then operate on the records of the dynaset one at a time. The record you are currently working with is referred to as the current record.

You can obtain field values from the current record (GetFieldValue), edit the current record (StartEdit, SetFieldValue, Update), delete the current record (DeleteRecord), or duplicate the current record (DuplicateRecord).

You can change the "current" record, navigating through the dynaset's result set, by using one of the "Move" methods. Execution of a Move method changes which record is current. The records in a dynaset's result set will be in some order. To specify a particular order, use an "order by" clause in your SQL statement to order the results. Records that are not explicitly ordered may be returned in different order on different queries. Records that are added are added at the end of the result set.

Records that have been fetched from the Oracle database and placed in the local cache do not reflect changes made to the data in the database until the dynaset is refreshed.

When operations - either navigations or operations such as Updates - are properly performed on the dynaset, messages are sent to any attached advisory objects. These messages may cancel the operation. (See the OAdvisory class for more information.) No advisories are attached to dynasets by default.

You can use the Clone method to open a separate dynaset (on the same record cache) with an independent current record mark. Cloned dynasets are read-only.

You can access data in the result set either directly (through ODynaset methods such as SetFieldValue and GetFieldValue) or by getting an OField object and using it to access the data. The OField object always contains the data from the current record. Columns can be referred to either by name or by index. The index starts at 1 and is the position of the column in the select statement. A column name is either the database column name or an aliased name if the SQL select statement aliases a column name. For example:

select ename, emp.sal, nvl(comm,0) "commission" from emp

will result in three columns. Column "ename" will have index 1, column "sal" will have index 2, and column "commission" will have index 3. It is more efficient to refer to columns by index. You can use the method GetFieldIndex to translate a field name into its index.

It is often important to know whether the opening select statement will result in an updatable dynaset. In general, queries that perform joins, have aliased column names, or have calculated columns are not updatable. In addition, queries that perform a "select distinct" are not updatable. Dynasets based on nonupdatable queries will fail the AddNew, Duplicate, StartEdit, and Update methods.

Several options are set for a dynaset at the time it is opened. These options are ORed together on the Open method call. The options are:

Option	Description
ODYNASET_DEFAULT	Accept the default behavior.
ODYNASET_NOBIND	Do not use bindable parameters.
ODYNASET_KEEP_BLANKS	Do not strip trailing blanks in values.
ODYNASET_READONLY	Make this dynaset nonupdatable.
ODYNASET_NOCACHE	Do not make a local record cache for this dynaset.
ODYNASET_ORAMODE	Behaves same as ODATABASE_ORAMODE for a ODatabase class except it affects only the dynaset being created. If the database was created in ODATABASE_ORAMODE mode, the dynaset inherits the property for compatibility.
ODYNASET_NO_REFETCH	Behaves same as ODATABASE_NO_REFETCH Mode for a ODatabase class except it affects only the dynaset being created. If the database was created in ODATABASE_NO_REFETCH mode, the dynaset inherits the property for compatibility.
ODYNASET_N_MOVEFIRST	Does not force a movefirst on dynaset creation. BOF and EOF are both TRUE.
ODYNASET_DIRTY_WRITE	Update and Delete will not check for read consistency.

By default all the options are off.

By default, a dynaset attempts to use any available bindable parameters when it is being opened (see OParameter for more information on parameters). Therefore, when issuing a SQL statement that does not refer to any parameters, you can make it more efficient by specifying "nobind".

By default, values returned by a dynaset are stripped of trailing blanks. You can retain the trailing blanks by specifying "keep_blanks".

By default, dynaset objects are updatable, which requires some processing overhead. Therefore, if you know that you will be using a dynaset only for reading data, you can make it more efficient by specifying "readonly".

By default, a local record cache is created for each dynaset to allow reverse scrolling. The record cache requires considerable overhead. If you know that you will simply be reading through the returned values of a dynaset, you can improve performance by turning on the "nocache" option. Dynasets without a record cache will not be able to move backwards or move to a dynaset mark.

A dynaset is opened with a particular SQL statement, which specifies the values to return from the Oracle database. The Refresh method of ODynaset is handy for reexecuting the SQL statement. This is useful in two circumstances:

1. The values in the database are changing and you want to obtain the new values, or

2. The SQL statement that you have used is parameterized (uses syntax of the form ":parameter") and the value of the parameter has changed.

Refreshing a dynaset resets the local record cache and moves the current record to the first record of the new result set.

The ODynaset class supports the following methods:

Construction and destruction:

ODynaset

~ODynaset

operator=

Attributes:

operator== operator!= CanMark CanRefresh CanScroll CanTransact CanUpdate GetEditMode GetFieldCount GetFieldIndex GetFieldPrecision GetFieldScale GetFieldServerSize

GetFieldServerType GetFieldSize GetOptions GetRecordCount GetSQL IsBOF IsEOF IsFieldNullOK IsFieldTruncated IsFirst IsLast IsOpen IsValidRecord

Operations:

AddNewRecord AppendFieldChunk CancelEdit Clone CopyToClipboard Close DeleteRecord DuplicateRecord FindFirst FindLast FindNext FindPrevious GetCacheBlocks GetCacheSlicePerBlock GetCacheSliceSize GetConnection GetDatabase GetFetchLimit GetFetchSize GetField GetFieldChunk GetFieldOriginalName GetFieldOriginalNameIndex GetFields GetFieldValue GetLastModifiedMark

GetMark GetSession GetSnapshot IsCacheChanged MoveFirst MoveLast MoveNext MovePrev MoveNextN MovePrevN MoveRel MoveTo MoveToMark NoMatch Open PlsqlOpen Refresh SetCacheBlocks SetCacheSlicePerBlock SetCacheSliceSize SetFetchLimit SetFetchSize SetFieldValue SetSnapshot SetSQL StartEdit Update

Error Handling:

ErrorNumber

ErrorReset

GetErrorText

LookupErrorText