TDataSet class

In unit DB

Base class for records-based data-access.

Declaration

pascal

TDataSet = class(TComponent)

Inheritance

Descends from it: TDBDataset TMemDataset

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 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 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

`ActiveRecord`	protected
`CurrentRecord`	protected
`BlobFieldCount`	protected
`BookmarkSize`	protected
`Buffers`	protected
`BufferCount`	protected
`CalcBuffer`	protected
`CalcFieldsSize`	protected
`InternalCalcFields`	protected
`Constraints`	protected
`MyDataSources`	protected
`MyDataSourceCount`	protected
`BlockReadSize`	public	Number of records to read.
`BOF`	public	Is the cursor at the beginning of the data (on the first record).
`Bookmark`	public	Get or set the current cursor position.
`CanModify`	public	Can the data in the dataset be modified.
`DataSource`	public	Datasource this dataset is connected to.
`DefaultFields`	public	Is the dataset using persistent fields or not.
`EOF`	public	Indicates whether the last record has been reached.
`FieldCount`	public	Number of fields.
`FieldDefs`	public	Definitions of available fields in the underlying database.
`Found`	public	Check success of one of the Find methods.
`Modified`	public	Was the current record modified ?
`IsUniDirectional`	public	Is the dataset unidirectional (i.e. forward scrolling only).
`RecordCount`	public	Number of records in the dataset.
`RecNo`	public	Current record number.
`RecordSize`	public	Size of the record in memory.
`SparseArrays`	public
`State`	public	Current operational state of the dataset.
`Fields`	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.
`Active`	public	Is the dataset open or closed.
`AutoCalcFields`	public	How often should the value of calculated fields be calculated.
`BeforeOpen`	public	Event triggered before the dataset is opened.
`AfterOpen`	public	Event triggered after the dataset is opened.
`BeforeClose`	public	Event triggered before the dataset is closed.
`AfterClose`	public	Event triggered after the dataset is closed.
`BeforeInsert`	public	Event triggered before the dataset is put in insert mode.
`AfterInsert`	public	Event triggered after the dataset is put in insert mode.
`BeforeEdit`	public	Event triggered before the dataset is put in edit mode.
`AfterEdit`	public	Event triggered after the dataset is put in edit mode.
`BeforePost`	public	Event called before changes are posted to the underlying database.
`AfterPost`	public	Event called after changes have been posted to the underlying database.
`BeforeCancel`	public	Event triggered before a Cancel operation.
`AfterCancel`	public	Event triggered after a Cancel operation.
`BeforeDelete`	public	Event triggered before a Delete operation.
`AfterDelete`	public	Event triggered after a successful Delete operation.
`BeforeScroll`	public	Event triggered before the cursor changes position.
`AfterScroll`	public	Event triggered after the cursor has changed position.
`BeforeRefresh`	public	Event triggered before the data is refreshed.
`AfterRefresh`	public	Event triggered after the data has been refreshed.

Methods

`GetDefaultBufferCount`	protected
`RecalcBufListSize`	protected
`ActivateBuffers`	protected
`BindFields`	protected
`BlockReadNext`	protected
`BookmarkAvailable`	protected
`CalculateFields`	protected
`CheckActive`	protected
`CheckInactive`	protected
`CheckBiDirectional`	protected
`Loaded`	protected	Called when the component has finished loading.
`ClearBuffers`	protected
`ClearCalcFields`	protected
`CloseBlob`	protected
`CloseCursor`	protected
`CreateFields`	protected
`DataEvent`	protected
`DestroyFields`	protected
`DoAfterCancel`	protected
`DoAfterClose`	protected
`DoAfterDelete`	protected
`DoAfterEdit`	protected
`DoAfterInsert`	protected
`DoAfterOpen`	protected
`DoAfterPost`	protected
`DoAfterScroll`	protected
`DoAfterRefresh`	protected
`DoBeforeCancel`	protected
`DoBeforeClose`	protected
`DoBeforeDelete`	protected
`DoBeforeEdit`	protected
`DoBeforeInsert`	protected
`DoBeforeOpen`	protected
`DoBeforePost`	protected
`DoBeforeScroll`	protected
`DoBeforeRefresh`	protected
`DoOnCalcFields`	protected
`DoOnNewRecord`	protected
`FieldByNumber`	protected
`FindRecord`	protected
`FreeFieldBuffers`	protected
`GetBookmarkStr`	protected
`GetCalcFields`	protected
`GetCanModify`	protected
`GetChildren`	protected	Must be overridden by descendants to return all child components that must be streamed.
`GetFieldClass`	protected
`GetfieldCount`	protected
`GetFieldValues`	protected
`GetIsIndexField`	protected
`GetIndexDefs`	protected
`GetNextRecords`	protected
`GetNextRecord`	protected
`GetPriorRecords`	protected
`GetPriorRecord`	protected
`GetRecordCount`	protected
`GetRecNo`	protected
`InitFieldDefs`	protected
`InitFieldDefsFromFields`	protected
`InitRecord`	protected
`InternalCancel`	protected
`InternalEdit`	protected
`InternalInsert`	protected
`InternalRefresh`	protected
`OpenCursor`	protected
`OpenCursorcomplete`	protected
`RefreshInternalCalcFields`	protected
`RestoreState`	protected
`SetActive`	protected
`SetBookmarkStr`	protected
`SetBufListSize`	protected
`SetChildOrder`	protected	Determines the order in which children are streamed/created.
`SetCurrentRecord`	protected
`SetDefaultFields`	protected
`SetFiltered`	protected
`SetFilterOptions`	protected
`SetFilterText`	protected
`SetFieldValues`	protected
`SetFound`	protected
`SetModified`	protected
`SetName`	protected	Write handler for Name property.
`SetOnFilterRecord`	protected
`SetRecNo`	protected
`SetState`	protected
`SetTempState`	protected
`TempBuffer`	protected
`UpdateIndexDefs`	protected
`AllocRecordBuffer`	protected
`FreeRecordBuffer`	protected
`GetBookmarkData`	protected
`GetBookmarkFlag`	protected
`GetDataSource`	protected
`GetRecordSize`	protected
`InternalAddRecord`	protected
`InternalDelete`	protected
`InternalFirst`	protected
`InternalGotoBookmark`	protected
`InternalHandleException`	protected
`InternalInitRecord`	protected
`InternalLast`	protected
`InternalPost`	protected
`InternalSetToRecord`	protected
`SetBookmarkFlag`	protected
`SetBookmarkData`	protected
`SetUniDirectional`	protected
`FieldDefsClass`	protected
`FieldsClass`	protected
`GetRecord`	protected
`InternalClose`	protected
`InternalOpen`	protected
`InternalInitFieldDefs`	protected
`IsCursorOpen`	protected
`PSEndTransaction`	protected
`PSExecute`	protected
`PSExecuteStatement`	protected
`PSGetAttributes`	protected
`PSGetCommandText`	protected
`PSGetCommandType`	protected
`PSGetDefaultOrder`	protected
`PSGetIndexDefs`	protected
`PSGetKeyFields`	protected
`PSGetParams`	protected
`PSGetQuoteChar`	protected
`PSGetTableName`	protected
`PSGetUpdateException`	protected
`PSInTransaction`	protected
`PSIsSQLBased`	protected
`PSIsSQLSupported`	protected
`PSReset`	protected
`PSSetCommandText`	protected
`PSSetParams`	protected
`PSStartTransaction`	protected
`PSUpdateRecord`	protected
`Create`	public	Create a new TDataset instance.
`Destroy`	public	Free a TDataset instance.
`ActiveBuffer`	public	Currently active memory buffer.
`GetFieldData`	public	Get the data for a field.
`SetFieldData`	public	Store the data for a field.
`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.
`ControlsDisabled`	public	Check whether the controls are disabled.
`CompareBookmarks`	public	Compare two bookmarks.
`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.
`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.
`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.
`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.

Events

`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.

Inherited

From TComponent (70)

_AddRef _Release BeforeDestruction CanObserve ChangeName ComObject ComponentCount ComponentIndex Components ComponentState ComponentStyle DefineProperties DesignInfo DestroyComponents Destroying ExecuteAction FindComponent FreeNotification FreeOnRelease GetChildOwner GetChildParent GetDeltaStreams GetEnumerator GetIDsOfNames GetNamePath GetObservers GetOwner GetParentComponent GetTypeInfo GetTypeInfoCount HasParent iicrGetComponent InsertComponent Invoke IsImplementorOf Loading Name Notification ObserverAdded Observers OnGetDeltaStreams Owner PaletteCreated QueryInterface ReadDeltaState ReadDeltaStream ReadState ReferenceInterface RemoveComponent RemoveFreeNotification RemoveFreeNotifications SafeCallException SetAncestor SetDesigning SetDesignInstance SetInline SetParentComponent SetSubComponent Tag ToString TToStringNameMode UpdateAction Updated UpdateRegistry Updating ValidateContainer ValidateInsert ValidateRename VCLComObject WriteState

From TPersistent (5)

Assign AssignTo FPOAttachObserver FPODetachObserver FPONotifyObservers

From TObject (37)

AfterConstruction CheckDisposed ClassInfo ClassName ClassNameIs ClassParent ClassType CleanupInstance DefaultHandler DefaultHandlerStr Dispatch DispatchStr Disposed DisposeOf Equals FieldAddress Free FreeInstance GetDisposed GetHashCode GetInterface GetInterfaceByStr GetInterfaceEntry GetInterfaceEntryByStr GetInterfaceTable GetInterfaceWeak GetLastCastErrorInfo InheritsFrom InitInstance InstanceSize MethodAddress MethodName newinstance QualifiedClassName StringMessageTable SystemHasExtendedRTTI UnitName

An experiment, built from development snapshots. Not the official Free Pascal or Lazarus documentation.