TDataSet¶

Base class for records-based data-access.

Declaration¶

Source position: db.pas line 1661

type

  TDataSet = class(TComponent)
  public
    constructor Create;
    destructor Destroy;
    function ActiveBuffer : TRecordBuffer;
    function GetFieldData(Field: TField; Buffer: Pointer) : Boolean; overload;
    function GetFieldData(Field: TField; Buffer: Pointer; 
                     NativeFormat: Boolean) : Boolean; overload;
    procedure SetFieldData(Field: TField; Buffer: Pointer); overload;
    procedure SetFieldData(Field: TField; Buffer: Pointer; 
                      NativeFormat: Boolean); overload;
    procedure Append;
    procedure AppendRecord;
    function BookmarkValid : Boolean;
    procedure Cancel;
    procedure CheckBrowseMode;
    procedure ClearFields;
    procedure Close;
    function ControlsDisabled : Boolean;
    function CompareBookmarks : LongInt;
    function CreateBlobStream : TStream;
    procedure CursorPosChanged;
    procedure DataConvert;
    procedure Delete;
    procedure DisableControls;
    procedure Edit;
    procedure EnableControls;
    function FieldByName : TField;
    function FindField : TField;
    function FindFirst : Boolean;
    function FindLast : Boolean;
    function FindNext : Boolean;
    function FindPrior : Boolean;
    procedure First;
    procedure FreeBookmark;
    function GetBookmark : TBookMark;
    function GetCurrentRecord : Boolean;
    procedure GetFieldList;
    procedure GetFieldNames;
    procedure GotoBookmark;
    procedure Insert;
    procedure InsertRecord;
    function IsEmpty : Boolean;
    function IsLinkedTo : Boolean;
    function IsSequenced : Boolean;
    procedure Last;
    function Locate : Boolean;
    function Lookup : Variant;
    function MoveBy : LongInt;
    procedure Next;
    procedure Open;
    procedure Post;
    procedure Prior;
    procedure Refresh;
    procedure Resync;
    procedure SetFields;
    function Translate : Integer;
    procedure UpdateCursorPos;
    procedure UpdateRecord;
    function UpdateStatus : TUpdateStatus;
    property BlockReadSize: Integer; {rw}
    property BOF: Boolean; {r}
    property Bookmark: TBookMark; {rw}
    property CanModify: Boolean; {r}
    property DataSource: TDataSource; {r}
    property DefaultFields: Boolean; {r}
    property EOF: Boolean; {r}
    property FieldCount: LongInt; {r}
    property FieldDefs: TFieldDefs; {rw}
    property Found: Boolean; {r}
    property Modified: Boolean; {r}
    property IsUniDirectional: Boolean; {rd}
    property RecordCount: LongInt; {r}
    property RecNo: LongInt; {rw}
    property RecordSize: Word; {r}
    property SparseArrays: Boolean; {rw}
    property State: TDataSetState; {r}
    property Fields: TFields; {r}
    property FieldValues[FieldName : string]: Variant; {rw}
    property Filter: string; {rw}
    property Filtered: Boolean; {rwd}
    property FilterOptions: TFilterOptions; {rw}
    property Active: Boolean; {rwd}
    property AutoCalcFields: Boolean; {rwd}
    property BeforeOpen: TDataSetNotifyEvent; {rw}
    property AfterOpen: TDataSetNotifyEvent; {rw}
    property BeforeClose: TDataSetNotifyEvent; {rw}
    property AfterClose: TDataSetNotifyEvent; {rw}
    property BeforeInsert: TDataSetNotifyEvent; {rw}
    property AfterInsert: TDataSetNotifyEvent; {rw}
    property BeforeEdit: TDataSetNotifyEvent; {rw}
    property AfterEdit: TDataSetNotifyEvent; {rw}
    property BeforePost: TDataSetNotifyEvent; {rw}
    property AfterPost: TDataSetNotifyEvent; {rw}
    property BeforeCancel: TDataSetNotifyEvent; {rw}
    property AfterCancel: TDataSetNotifyEvent; {rw}
    property BeforeDelete: TDataSetNotifyEvent; {rw}
    property AfterDelete: TDataSetNotifyEvent; {rw}
    property BeforeScroll: TDataSetNotifyEvent; {rw}
    property AfterScroll: TDataSetNotifyEvent; {rw}
    property BeforeRefresh: TDataSetNotifyEvent; {rw}
    property AfterRefresh: TDataSetNotifyEvent; {rw}
    property OnCalcFields: TDataSetNotifyEvent; {rw}
    property OnDeleteError: TDataSetErrorEvent; {rw}
    property OnEditError: TDataSetErrorEvent; {rw}
    property OnFilterRecord: TFilterRecordEvent; {rw}
    property OnNewRecord: TDataSetNotifyEvent; {rw}
    property OnPostError: TDataSetErrorEvent; {rw}
  end;

Inheritance¶

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.

Properties¶

Member	Visibility	Description
Active	public	Is the dataset open or closed.
AfterCancel	public	Event triggered after a Cancel operation.
AfterClose	public	Event triggered after the dataset is closed.
AfterDelete	public	Event triggered after a successful Delete operation.
AfterEdit	public	Event triggered after the dataset is put in edit mode.
AfterInsert	public	Event triggered after the dataset is put in insert mode.
AfterOpen	public	Event triggered after the dataset is opened.
AfterPost	public	Event called after changes have been posted to the underlying database.
AfterRefresh	public	Event triggered after the data has been refreshed.
AfterScroll	public	Event triggered after the cursor has changed position.
AutoCalcFields	public	How often should the value of calculated fields be calculated.
BeforeCancel	public	Event triggered before a Cancel operation.
BeforeClose	public	Event triggered before the dataset is closed.
BeforeDelete	public	Event triggered before a Delete operation.
BeforeEdit	public	Event triggered before the dataset is put in edit mode.
BeforeInsert	public	Event triggered before the dataset is put in insert mode.
BeforeOpen	public	Event triggered before the dataset is opened.
BeforePost	public	Event called before changes are posted to the underlying database.
BeforeRefresh	public	Event triggered before the data is refreshed.
BeforeScroll	public	Event triggered before the cursor changes position.
BlockReadSize	public	Number of records to read.
BOF read only	public	Is the cursor at the beginning of the data (on the first record).
Bookmark	public	Get or set the current cursor position.
CanModify read only	public	Can the data in the dataset be modified.
DataSource read only	public	Datasource this dataset is connected to.
DefaultFields read only	public	Is the dataset using persistent fields or not.
EOF read only	public	Indicates whether the last record has been reached.
FieldCount read only	public	Number of fields.
FieldDefs	public	Definitions of available fields in the underlying database.
Fields read only	public	Indexed access to the fields of the dataset.
FieldValues	public	Access to field values based on the field names.
Filter	public	Filter to apply to the data in memory.
Filtered	public	Is the filter active or not.
FilterOptions	public	Options to apply when filtering.
Found read only	public	Check success of one of the Find methods.
IsUniDirectional read only	public	Is the dataset unidirectional (i.e. forward scrolling only).
Modified read only	public	Was the current record modified ?
RecNo	public	Current record number.
RecordCount read only	public	Number of records in the dataset.
RecordSize read only	public	Size of the record in memory.
SparseArrays	public
State read only	public	Current operational state of the dataset.

See all Properties

Methods¶

Member	Visibility	Description
ActiveBuffer	public	Currently active memory buffer.
Append	public	Append a new record to the data.
AppendRecord	public	Append a new record to the dataset and fill with data.
BookmarkValid	public	Test whether ABookMark is a valid bookmark.
Cancel	public	Cancel the current editing operation.
CheckBrowseMode	public	Check whether the dataset is in browse mode.
ClearFields	public	Clear the values of all fields.
Close	public	Close the dataset.
CompareBookmarks	public	Compare two bookmarks.
ControlsDisabled	public	Check whether the controls are disabled.
Create	public	Create a new TDataset instance.
CreateBlobStream	public	Create blob stream.
CursorPosChanged	public	Indicate a change in cursor position.
DataConvert	public	Convert data from/to native format.
Delete	public	Delete the current record.
Destroy	public	Free a TDataset instance.
DisableControls	public	Disable event propagation of controls.
Edit	public	Set the dataset in editing mode.
EnableControls	public	Enable event propagation of controls.
FieldByName	public	Search a field by name.
FindField	public	Find a field by name.
FindFirst	public	Find the first active record (deprecated).
FindLast	public	Find the last active record (deprecated).
FindNext	public	Find the next active record (deprecated).
FindPrior	public	Find the previous active record (deprecated).
First	public	Position the dataset on the first record.
FreeBookmark	public	Free a bookmark obtained with GetBookmark (deprecated).
GetBookmark	public	Get a bookmark pointer (deprecated).
GetCurrentRecord	public	Copy the data for the current record in a memory buffer.
GetFieldData	public	Get the data for a field.
GetFieldList	public	Return field instances in a list.
GetFieldNames	public	Return a list of all available field names.
GotoBookmark	public	Jump to bookmark.
Insert	public	Insert a new record at the current position.
InsertRecord	public	Insert a new record with given values.
IsEmpty	public	Check if the dataset contains no data.
IsLinkedTo	public	Check whether a datasource is linked to the dataset.
IsSequenced	public	Is the data sequenced.
Last	public	Navigate forward to the last record.
Locate	public	Locate a record based on some key values.
Lookup	public	Search for a record and return matching values.
MoveBy	public	Move the cursor position.
Next	public	Go to the next record in the dataset.
Open	public	Activate the dataset: Fetch data into memory.
Post	public	Post pending edits to the database.
Prior	public	Go to the previous record.
Refresh	public	Refresh the records in the dataset.
Resync	public	Resynchronize the data buffer.
SetFieldData	public	Store the data for a field.
SetFields	public	Set a number of field values at once.
Translate	public	Transliterate a buffer.
UpdateCursorPos	public	Update cursor position.
UpdateRecord	public	Indicate that the record contents have changed.
UpdateStatus	public	Get the update status for the current record.

See all Methods

Events¶

Member	Visibility	Description
OnCalcFields	public	Event triggered when values for calculated fields must be computed.
OnDeleteError	public	Event triggered when a delete operation fails.
OnEditError	public	Event triggered when an edit operation fails.
OnFilterRecord	public	Event triggered to filter records.
OnNewRecord	public	Event triggered when a new record is created.
OnPostError	public	Event triggered when a post operation fails.

See all Events