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



DataSet closed; its data is unavailable



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



DataSet open; the current row can be modified



DataSet open; a new row is inserted or appended



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



Internal use only



Internal use only



Internal use only



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 }
if AddressPromptDialog.ModalResult := mrOK then
  IBTable.Post; { Delphi sets dataset state to Browse on successful completion }
  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;

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.


Advance To: