[Overview][Constants][Types][Classes][Procedures and functions][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 1323

`type TDataSet = class(TComponent)`
`protected`
`procedure RecalcBufListSize;`
`procedure ActivateBuffers; virtual;`
`procedure BindFields();`
`function BookmarkAvailable;`
`procedure CalculateFields(); virtual;`
`procedure CheckActive; virtual;`
`procedure CheckInactive; virtual;`
`procedure CheckBiDirectional;`
`procedure Loaded; override;`
`procedure ClearBuffers; virtual;`
`procedure ClearCalcFields(); virtual;`
`procedure CloseBlob(); virtual;`
`procedure CloseCursor; virtual;`
`procedure CreateFields; virtual;`
`procedure DataEvent(); virtual;`
`procedure DestroyFields; virtual;`
`procedure DoAfterCancel; virtual;`
`procedure DoAfterClose; virtual;`
`procedure DoAfterDelete; virtual;`
`procedure DoAfterEdit; virtual;`
`procedure DoAfterInsert; virtual;`
`procedure DoAfterOpen; virtual;`
`procedure DoAfterPost; virtual;`
`procedure DoAfterScroll; virtual;`
`procedure DoAfterRefresh; virtual;`
`procedure DoBeforeCancel; virtual;`
`procedure DoBeforeClose; virtual;`
`procedure DoBeforeDelete; virtual;`
`procedure DoBeforeEdit; virtual;`
`procedure DoBeforeInsert; virtual;`
`procedure DoBeforeOpen; virtual;`
`procedure DoBeforePost; virtual;`
`procedure DoBeforeScroll; virtual;`
`procedure DoBeforeRefresh; virtual;`
`procedure DoOnCalcFields; virtual;`
`procedure DoOnNewRecord; virtual;`
`function FieldByNumber();`
`function FindRecord(); virtual;`
`procedure FreeFieldBuffers; virtual;`
`function GetBookmarkStr; virtual;`
`procedure GetCalcFields(); virtual;`
`function GetCanModify; virtual;`
`procedure GetChildren(); override;`
`function GetFieldClass(); virtual;`
`function GetfieldCount;`
`function GetFieldValues(); virtual;`
`function GetIsIndexField(); virtual;`
`function GetIndexDefs();`
`function GetNextRecords; virtual;`
`function GetNextRecord; virtual;`
`function GetPriorRecords; virtual;`
`function GetPriorRecord; virtual;`
`function GetRecordCount; virtual;`
`function GetRecNo; virtual;`
`procedure InitFieldDefs; virtual;`
`procedure InitFieldDefsFromfields;`
`procedure InitRecord(); virtual;`
`procedure InternalCancel; virtual;`
`procedure InternalEdit; virtual;`
`procedure InternalInsert; virtual;`
`procedure InternalRefresh; virtual;`
`procedure OpenCursor(); virtual;`
`procedure OpenCursorcomplete; virtual;`
`procedure RefreshInternalCalcFields(); virtual;`
`procedure RestoreState();`
`procedure SetActive(); virtual;`
`procedure SetBookmarkStr(); virtual;`
`procedure SetBufListSize(); virtual;`
`procedure SetChildOrder(); override;`
`procedure SetCurrentRecord(); virtual;`
`procedure SetDefaultFields();`
`procedure SetFiltered(); virtual;`
`procedure SetFilterOptions(); virtual;`
`procedure SetFilterText(); virtual;`
`procedure SetFound();`
`procedure SetFieldValues(); virtual;`
`procedure SetModified();`
`procedure SetName(); override;`
`procedure SetOnFilterRecord(); virtual;`
`procedure SetRecNo(); virtual;`
`procedure SetState();`
`function SetTempState();`
`function Tempbuffer;`
`procedure UpdateIndexDefs; virtual;`
`property ActiveRecord: LongInt; [r]`
`property CurrentRecord: LongInt; [r]`
`property BlobFieldCount: LongInt; [r]`
`property BookmarkSize: LongInt; [rw]`
`property Buffers: PChar; [r]`
`property BufferCount: LongInt; [r]`
`property CalcBuffer: PChar; [r]`
`property CalcFieldsSize: LongInt; [r]`
`property InternalCalcFields: Boolean; [r]`
`property Constraints: TCheckConstraints; [rw]`
`function AllocRecordBuffer; virtual;`
`procedure FreeRecordBuffer(); virtual;`
`procedure GetBookmarkData(); virtual;`
`function GetBookmarkFlag(); virtual;`
`function GetDataSource; virtual;`
`function GetRecordSize; virtual;`
`procedure InternalAddRecord(); virtual;`
`procedure InternalDelete; virtual;`
`procedure InternalFirst; virtual;`
`procedure InternalGotoBookmark(); virtual;`
`procedure InternalHandleException; virtual;`
`procedure InternalInitRecord(); virtual;`
`procedure InternalLast; virtual;`
`procedure InternalPost; virtual;`
`procedure InternalSetToRecord(); virtual;`
`procedure SetBookmarkFlag(); virtual;`
`procedure SetBookmarkData(); virtual;`
`procedure SetUniDirectional();`
`function GetRecord(); virtual; abstract;`
`procedure InternalClose; virtual; abstract;`
`procedure InternalOpen; virtual; abstract;`
`procedure InternalInitFieldDefs; virtual; abstract;`
`function IsCursorOpen; virtual; abstract;`
`procedure PSEndTransaction(); virtual;`
`procedure PSExecute; virtual;`
`function PSExecuteStatement(); virtual;`
`procedure PSGetAttributes(); virtual;`
`function PSGetCommandText; virtual;`
`function PSGetCommandType; virtual;`
`function PSGetDefaultOrder; virtual;`
`function PSGetIndexDefs(); virtual;`
`function PSGetKeyFields; virtual;`
`function PSGetParams; virtual;`
`function PSGetQuoteChar; virtual;`
`function PSGetTableName; virtual;`
`function PSGetUpdateException(); virtual;`
`function PSInTransaction; virtual;`
`function PSIsSQLBased; virtual;`
`function PSIsSQLSupported; virtual;`
`procedure PSReset; virtual;`
`procedure PSSetCommandText(); virtual;`
`procedure PSSetParams(); virtual;`
`procedure PSStartTransaction; virtual;`
`function PSUpdateRecord(); virtual;`
`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;` |  | 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;` |  | Find the first active record (deprecated)
`function FindLast;` |  | Find the last active record (deprecated)
`function FindNext;` |  | Find the next active record (deprecated)
`function FindPrior;` |  | 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]`
`property BOF: Boolean; [r]` |  | Is the cursor at the beginning of the data (on the first record)
`property Bookmark: TBookmarkStr; [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 persisten 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; [rw]` |  | 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]` |  | Acces 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]` |  |
`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`
`TObject`

## Description

TDataset is the main class of the db unit. This abstract class provides all basic funtionality 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 rechaed when navigating backwards. If both proprties 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

The latest version of this document can be found at lazarus-ccr.sourceforge.net .