[Overview][Constants][Types][Classes][Procedures and functions][Variables][Index] | Reference for unit 'DB' (#fcl)

# TDataSet

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

Base class for records-based data-access

## Declaration

Source position: db.pas line 1439

`type TDataSet = class(TComponent)`
`public`
`constructor Create(); override;` |  | Create a new TDataset instance
`destructor Destroy; override;` |  | Free a TDataset instance
`function ActiveBuffer;` |  | Currently active memory buffer
`function GetFieldData();` |  | Get the data for a field
`procedure SetFieldData();` |  | Store the data for a field
`procedure Append;` |  | Append a new record to the data
`procedure AppendRecord();` |  | Append a new record to the dataset and fill with data
`function BookmarkValid(); virtual;` |  | Test whether ABookMark is a valid bookmark.
`procedure Cancel; virtual;` |  | Cancel the current editing operation
`procedure CheckBrowseMode;` |  | Check whether the dataset is in browse mode.
`procedure ClearFields;` |  | Clear the values of all fields
`procedure Close;` |  | Close the dataset
`function ControlsDisabled;` |  | Check whether the controls are disabled
`function CompareBookmarks(); virtual;` |  | Compare two bookmarks
`function CreateBlobStream(); virtual;` |  | Create blob stream
`procedure CursorPosChanged;` |  | Indicate a change in cursor position
`procedure DataConvert(); virtual;` |  | Convert data from/to native format
`procedure Delete; virtual;` |  | Delete the current record.
`procedure DisableControls;` |  | Disable event propagation of controls
`procedure Edit;` |  | Set the dataset in editing mode.
`procedure EnableControls;` |  | Enable event propagation of controls
`function FieldByName();` |  | Search a field by name
`function FindField();` |  | Find a field by name
`function FindFirst; virtual;` |  | Find the first active record (deprecated)
`function FindLast; virtual;` |  | Find the last active record (deprecated)
`function FindNext; virtual;` |  | Find the next active record (deprecated)
`function FindPrior; virtual;` |  | Find the previous active record (deprecated)
`procedure First;` |  | Position the dataset on the first record.
`procedure FreeBookmark(); virtual;` |  | Free a bookmark obtained with GetBookmark (deprecated)
`function GetBookmark; virtual;` |  | Get a bookmark pointer (deprecated)
`function GetCurrentRecord(); virtual;` |  | Copy the data for the current record in a memory buffer
`procedure GetFieldList();` |  | Return field instances in a list
`procedure GetFieldNames();` |  | Return a list of all available field names
`procedure GotoBookmark();` |  | Jump to bookmark
`procedure Insert;` |  | Insert a new record at the current position.
`procedure InsertRecord();` |  | Insert a new record with given values.
`function IsEmpty;` |  | Check if the dataset contains no data
`function IsLinkedTo();` |  | Check whether a datasource is linked to the dataset
`function IsSequenced; virtual;` |  | Is the data sequenced
`procedure Last;` |  | Navigate forward to the last record
`function Locate(); virtual;` |  | Locate a record based on some key values
`function Lookup(); virtual;` |  | Search for a record and return matching values.
`function MoveBy();` |  | Move the cursor position
`procedure Next;` |  | Go to the next record in the dataset.
`procedure Open;` |  | Activate the dataset: Fetch data into memory.
`procedure Post; virtual;` |  | Post pending edits to the database.
`procedure Prior;` |  | Go to the previous record
`procedure Refresh;` |  | Refresh the records in the dataset
`procedure Resync(); virtual;` |  | Resynchronize the data buffer
`procedure SetFields();` |  | Set a number of field values at once
`function Translate(); virtual;` |  | Transliterate a buffer
`procedure UpdateCursorPos;` |  | Update cursor position
`procedure UpdateRecord;` |  | Indicate that the record contents have changed
`function UpdateStatus; virtual;` |  | Get the update status for the current record
`property BlockReadSize: Integer; [rw]` |  | Number of records to read
`property BOF: Boolean; [r]` |  | Is the cursor at the beginning of the data (on the first record)
`property Bookmark: TBookMark; [rw]` |  | Get or set the current cursor position
`property CanModify: Boolean; [r]` |  | Can the data in the dataset be modified
`property DataSource: TDataSource; [r]` |  | Datasource this dataset is connected to.
`property DefaultFields: Boolean; [r]` |  | Is the dataset using persistent fields or not.
`property EOF: Boolean; [r]` |  | Indicates whether the last record has been reached.
`property FieldCount: LongInt; [r]` |  | Number of fields
`property FieldDefs: TFieldDefs; [rw]` |  | Definitions of available fields in the underlying database
`property Found: Boolean; [r]` |  | Check success of one of the Find methods
`property Modified: Boolean; [r]` |  | Was the current record modified ?
`property IsUniDirectional: Boolean; [r]` |  | Is the dataset unidirectional (i.e. forward scrolling only)
`property RecordCount: LongInt; [r]` |  | Number of records in the dataset
`property RecNo: LongInt; [rw]` |  | Current record number
`property RecordSize: Word; [r]` |  | Size of the record in memory
`property State: TDataSetState; [r]` |  | Current operational state of the dataset
`property Fields: TFields; [r]` |  | Indexed access to the fields of the dataset.
`property FieldValues []: Variant; default; [rw]` |  | Access to field values based on the field names.
`property Filter: string; [rw]` |  | Filter to apply to the data in memory.
`property Filtered: Boolean; [rw]` |  | Is the filter active or not.
`property FilterOptions: TFilterOptions; [rw]` |  | Options to apply when filtering
`property Active: Boolean; [rw]` |  | Is the dataset open or closed.
`property AutoCalcFields: Boolean; [rw]` |  | How often should the value of calculated fields be calculated
`property BeforeOpen: TDataSetNotifyEvent; [rw]` |  | Event triggered before the dataset is opened.
`property AfterOpen: TDataSetNotifyEvent; [rw]` |  | Event triggered after the dataset is opened.
`property BeforeClose: TDataSetNotifyEvent; [rw]` |  | Event triggered before the dataset is closed.
`property AfterClose: TDataSetNotifyEvent; [rw]` |  | Event triggered after the dataset is closed
`property BeforeInsert: TDataSetNotifyEvent; [rw]` |  | Event triggered before the dataset is put in insert mode.
`property AfterInsert: TDataSetNotifyEvent; [rw]` |  | Event triggered after the dataset is put in insert mode.
`property BeforeEdit: TDataSetNotifyEvent; [rw]` |  | Event triggered before the dataset is put in edit mode.
`property AfterEdit: TDataSetNotifyEvent; [rw]` |  | Event triggered after the dataset is put in edit mode.
`property BeforePost: TDataSetNotifyEvent; [rw]` |  | Event called before changes are posted to the underlying database
`property AfterPost: TDataSetNotifyEvent; [rw]` |  | Event called after changes have been posted to the underlying database
`property BeforeCancel: TDataSetNotifyEvent; [rw]` |  | Event triggered before a Cancel operation.
`property AfterCancel: TDataSetNotifyEvent; [rw]` |  | Event triggered after a Cancel operation.
`property BeforeDelete: TDataSetNotifyEvent; [rw]` |  | Event triggered before a Delete operation.
`property AfterDelete: TDataSetNotifyEvent; [rw]` |  | Event triggered after a successful Delete operation.
`property BeforeScroll: TDataSetNotifyEvent; [rw]` |  | Event triggered before the cursor changes position.
`property AfterScroll: TDataSetNotifyEvent; [rw]` |  | Event triggered after the cursor has changed position.
`property BeforeRefresh: TDataSetNotifyEvent; [rw]` |  | Event triggered before the data is refreshed.
`property AfterRefresh: TDataSetNotifyEvent; [rw]` |  | Event triggered after the data has been refreshed.
`property OnCalcFields: TDataSetNotifyEvent; [rw]` |  | Event triggered when values for calculated fields must be computed.
`property OnDeleteError: TDataSetErrorEvent; [rw]` |  | Event triggered when a delete operation fails.
`property OnEditError: TDataSetErrorEvent; [rw]` |  | Event triggered when an edit operation fails.
`property OnFilterRecord: TFilterRecordEvent; [rw]` |  | Event triggered to filter records.
`property OnNewRecord: TDataSetNotifyEvent; [rw]` |  | Event triggered when a new record is created.
`property OnPostError: TDataSetErrorEvent; [rw]` |  | Event triggered when a post operation fails.
`end;`

## Inheritance

`TDataSet` |  | Base class for records-based data-access
`TComponent,IUnknown,IInterfaceComponentReference`
`TPersistent,IFPObserved`
`TObject`

## Description

TDataset is the main class of the db unit. This abstract class provides all basic functionality to access data stored in tabular format: The data consists of records, and the data in each record is organised in several fields.

TDataset has a buffer to cache a few records in memory, this buffer is used by TDatasource to create the ability to use data-aware components.

TDataset is an abstract class, which provides the basic functionality to access, navigate through the data and - in case read-write access is available, edit existing or add new records.

TDataset is an abstract class: it does not have the knowledge to store or load the records from whatever medium the records are stored on. Descendants add the functionality to load and save the data. Therefor TDataset is never used directly, one always instantiates a descendent class.

Initially, no data is available: the dataset is inactive. The Open method must be used to fetch data into memory. After this command, the data is available in memory for browsing or editing purposes: The dataset is active (indicated by the TDataset.Active property). Likewise, the Close method can be used to remove the data from memory. Any changes not yet saved to the underlying medium will be lost.

Data is expected to be in tabular format, where each row represents a record. The dataset has an idea of a cursor: this is the current position of the data cursor in the set of rows. Only the data of the current record is available for display or editing purposes. Through the Next, Prev, First and Last methods, it is possible to navigate through the records. The EOF property will be True if the last row has been reached. Likewise, the BOF property will return True if the first record in the dataset has been reached when navigating backwards. If both properties are empty, then there is no data available. For dataset descendents that support counting the number of records, the RecordCount will be zero.

The Append and Insert methods can be used to insert new records to the set of records. The TDataset.Delete statement is used to delete the current record, and the Edit command must be used to set the dataset in editing mode: the contents of the current record can then be changed. Any changes made to the current record (be it a new or existing record) must be saved by the Post method, or can be undone using the Cancel method.

The data in the various fields properties is available through the Fields array property, giving indexed access to all the fields in a record. The contents of a field is always readable. If the dataset is in one of the editing modes, then the fields can also be written to.

## See also

TField |  | Provide access to the contents of a single field in a record

Documentation generated on: May 14 2021