Determining and Setting Dataset States

From InterBase

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:

Values for the dataset State property
Value State Meaning

dsInactive

Inactive

DataSet closed; its data is unavailable

dsBrowse

Browse

DataSet open; its data can be viewed, but not changed

dsEdit

Edit

DataSet open; the current row can be modified

dsInsert

Insert

DataSet open; a new row is inserted or appended

dsCalcFields

CalcFields

DataSet open; indicates that an OnCalcFields event is under way and prevents changes to fields that are not calculated

dsCurValue

CurValue

Internal use only

dsNewValue

NewValue

Internal use only

dsOldValue

OldValue

Internal use only

dsFilter

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. (If Post 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

Advance To: