Determining and Setting Dataset States
Go Up to Understanding Datasets
The state (or mode) of a dataset determines what can be done to its data. For example, when a dataset is closed, its state is dsInactive
, meaning that nothing can be done to its data. At runtime, you can examine a dataset’s read-only State
property to determine its current state. The following table summarizes possible values for the State
property and what they mean:
Value | State | Meaning |
---|---|---|
|
Inactive |
DataSet closed; its data is unavailable |
|
Browse |
DataSet open; its data can be viewed, but not changed |
|
Edit |
DataSet open; the current row can be modified |
|
Insert |
DataSet open; a new row is inserted or appended |
|
CalcFields |
DataSet open; indicates that an |
|
CurValue |
Internal use only |
|
NewValue |
Internal use only |
|
OldValue |
Internal use only |
|
Filter |
DataSet open; indicates that a filter operation is under way: a restricted set of data can be viewed, and no data can be changed |
When an application opens a dataset, it appears by default in dsBrowse
mode. The state of a dataset changes as an application processes data. An open dataset changes from one state to another based on either the code in your application, or the built-in behavior of data-related components.
To put a dataset into dsBrowse
, dsEdit
, or dsInsert
states, call the method corresponding to the name of the state. For example, the following code puts IBTable
into dsInsert
state, accepts user input for a new record, and writes the new record to the database:
IBTable.Insert; { Your application explicitly sets dataset state to Insert } AddressPromptDialog.ShowModal; if AddressPromptDialog.ModalResult := mrOK then IBTable.Post; { Delphi sets dataset state to Browse on successful completion } else IBTable.Cancel; {Delphi sets dataset state to Browse on cancel }
This example also illustrates that the state of a dataset automatically changes to dsBrowse
when
- The
Post
method successfully writes a record to the database. (IfPost
fails, the dataset state remains unchanged.) - The
Cancel
method is called.
Some states cannot be set directly. For example, to put a dataset into dsInactive
state, set its Active
property to False, or call the Close
method for the dataset. The following statements are equivalent:
IBTable.Active := False; IBTable.Close;
The remaining states (dsCalcFields
, dsCurValue, dsNewValue
, dsOldValue
, and dsFilter
) cannot be set by your application. Instead, the state of the dataset changes automatically to these values as necessary. For example, dsCalcFields
is set when a dataset’s OnCalcFields
event is called. When the OnCalcFields
event finishes, the dataset is restored to its previous state.
Whenever a dataset state changes, the OnStateChange
event is called for any data source components associated with the dataset. For more information about data source components and OnStateChange
, see the Using Data Controls chapter of the Delphi Developer’s Guide.
The following sections provide overviews of each state, how and when states are set, how states relate to one another, and where to go for related information, if applicable.
Topics
- Deactivating a Dataset
- Browsing a Dataset
- Enabling Dataset Editing
- Enabling Insertion of New Records
- Calculating Fields
- Updating Records