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


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

Base class for records-based data-access


Source position: db.pas line 1439

type TDataSet = class(TComponent)


  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.





Base class for records-based data-access








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



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

Documentation generated on: May 14 2021