Skip Headers

Oracle® Objects for OLE C++ Class Library Developer's Guide
10g Release 1 (10.1)

Part Number B10119-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Feedback

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:

Open method options

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 backward 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
GetCacheBlocks
GetCacheSlicePerBlock
GetCacheSliceSize
GetEditMode
GetFetchLimit
GetFetchSize
GetFieldCount
GetFieldIndex
GetFieldOriginalName
GetFieldOriginalNameIndex
GetFieldPrecision
GetFieldScale
GetFieldServerSize
GetFieldServerType
GetFieldSize
GetLastModifiedMark
GetMark
GetOptions
GetRecordCount
GetSnapshot
GetSQL
GetXMLCollID
GetXMLEncodingTag
GetXMLNullIndicator
GetXMLOmitEncodingTag
GetXMLRowsetTag
GetXMLRowID
GetXMLRowTag
GetXMLUpperCase
IsBOF
IsCacheChanged
IsEOF
IsFieldNullOK
IsFieldTruncated
IsFirst
IsLast
IsOpen
IsValidRecord
NoMatch
SetCacheBlocks
SetCacheSlicePerBlock
SetCacheSliceSize
SetFetchLimit
SetFetchSize
SetFieldValue
SetSnapshot
SetSQL
SetXMLCollID
SetXMLEncodingTag
SetXMLNullIndicator
SetXMLOmitEncodingTag
SetXMLRowsetTag
SetXMLRowID
SetXMLRowTag
SetXMLUpperCase




Operations:
AddNewRecord
AppendFieldChunk
CancelEdit
Clone
CopyToClipboard
Close
DeleteRecord
DuplicateRecord
FindFirst
FindLast

FindNext
FindPrevious
GetConnection
GetDatabase
GetField
GetFieldChunk
GetFields
GetFieldValue

GetSession
GetXML
GetXMLToFile
MoveFirst
MoveLast
MoveNext
MovePrev
MoveNextN
MovePrevN

MoveRel
MoveTo
MoveToMark
Open
PlsqlOpen
Refresh
StartEdit
Update

Error Handling:

ErrorNumber

ErrorReset

GetErrorText

LookupErrorText