TDataSet

Description

Specifies the dataset for which the TDataSource component serves as the conduit to data-aware controls or other datasets.

TDataSet Properties

Property Bof: Boolean (R)

Indicates whether the first record in the dataset is active. Test Bof (beginning of file) to determine if the dataset is positioned at the first record. If Bof is true, the active record is unequivocally the first row in the dataset. Bof is true when an application:

• Opens a dataset.
• Calls a dataset's First method.
• Call a dataset's Prior method, and the method fails because the first row is already active.
• Calls SetRange on an empty range or dataset.

Bof is false in all other cases.

Property Eof: Boolean (R)

Indicates whether a dataset is positioned at the last record. Test Eof (end-of-file) to determine if the active record in a dataset is the last record. If Eof is true, the current record is unequivocally the last row in the dataset. Eof is true when an application:

• Opens an empty dataset.
• Calls a dataset's Last method. (Unless it is a unidirectional dataset)
• Call a dataset's Next method, and the method fails because the current record is already the last row in the dataset.
• Calls SetRange on an empty range or dataset.

Eof is false in all other cases.

Property Fields: Field list (R)

Lists field components of the dataset. Use Fields to access field components. If fields are generated dynamically at runtime, the order of field components in Fields corresponds directly to the order of columns in the table or tables underlying a dataset. If a dataset uses persistent fields, then the order of field components corresponds to the ordering of fields specified in the Fields editor at design time. Accessing fields with the Fields property is useful for iterating over some or all fields in a dataset. If an application knows the data types of individual fields, then it can read or write individual field values through the Fields property.

Property FieldCount: Integer (R)

Indicates the number of field components associated with the dataset. Examine FieldCount to determine the number of fields listed by the Fields property. For datasets with dynamically created fields, FieldCount may differ each time a dataset is opened.

Property RecordCount: Integer (R)

Indicates the total number of records associated with the dataset.

Property BookMark: TBookMarkStr (R/W)

Bookmark gets or sets the current bookmark in a dataset. A bookmark marks a location in a dataset so that an application can easily return to that location quickly.

An application can read Bookmark to retrieve the bookmark associated with the current record, and it can change the current record in the dataset by assigning a saved bookmark value to this property.

TDataSet Methods and Functions

Method First

Moves to the first record in the dataset. Call First to make the first record in the dataset active. First posts any changes to the active record and:

• Clears the record buffers.
• Fetches the first record and makes it the active record.
• Sets the Bof property to true.
• Broadcasts the record change so that data controls and linked detail sets can update.

Method Next

Moves to the next record in the dataset. Call Next to move to the next record in the dataset, making it the active record. Next posts any changes to the active record and:

• Sets the Bof and Eof properties to false.
• Fetches the next record and makes it the active record.
• If the dataset is not unidirectional, fetches any additional records required for display, such as those needed to fill out a grid control.
• Sets the Eof property to true if the last record in the dataset was already active.
• Broadcasts the record change so that data controls and linked detail sets can update.

Method Prior

Moves to the previous record in the dataset. Call Prior to move to the previous record in the dataset, making it the active record. Prior posts any changes to the active record and:

• Sets the Bof and Eof properties to false.
• Fetches the previous record and makes it the active record. If the dataset is unidirectional, it raises an exception at this point.
• Fetches any additional records required for display, such as those needed to fill out a grid control.
• Sets the Bof property to true if the first record in the dataset was already active.
• Broadcasts the record change so that data controls and linked detail sets can update.

Method Last

Moves to the last record in the dataset. Call Last to make the last record in the dataset active. If the dataset is not unidirectional Last posts any changes to the active record and:

• Clears the record buffers.
• Fetches the last record and makes it the active record.
• Fetches any additional records required for display, such as those needed to fill out a grid control.
• Sets the Eof property to true.
• Broadcasts the record change so that data controls and linked detail sets can update.

For unidirectional datasets, Last raises an exception.

Method FieldByName(FieldName: string): TField

Finds a field based on its name. Call FieldByName to retrieve field information for a field given its name. FieldName is the name of an existing field. FieldByName returns the TField component that represents the specified field. If the specified field does not exist, FieldByName raises an exception. An application can directly access specific properties and methods of the field returned by FieldByName.

Method FindField(FieldName: string): TField

Searches for a specified field in the dataset. Call FindField to determine if a specified field component exists in a dataset. FieldName is the name of the field for which to search. This name can be the the name of a simple field, the name of a subfield of an object field that has been qualified by the parent field's name, or the name of an aggregated field.

If FindField finds a field with a matching name, it returns the TField component for the specified field. Otherwise it returns nil. FindField is the same as the FieldByName method, except that it returns nil rather than raising an exception when the field is not found.

Method Open

Opens the dataset. Call Open to set the Active property for the dataset to true. When Active is true, data can be populated with data. It can read data from a database or other source (such as a provider). Setting Active to true:

• Triggers the BeforeOpen event handler if one is defined for the dataset.
• Sets the dataset state to dsBrowse.
• Establishes a way to fetch data (typically by opening a cursor).
• Triggers the After Open event handler if one is defined for the dataset.

If an error occurs during the dataset open, dataset state is set to dsInactive, and any cursor is closed.

Method Close

Closes a dataset. Call Close to set the Active property of a dataset to false. When Active is false, the dataset is closed; it cannot read or write data and data-aware controls can't use it to fetch data or post edits. An application must close the dataset before changing properties that affect the status of the database or the controls that display data in an application. For example, to change the DataSource property for a dataset, the dataset must be closed. Closing the dataset puts it into the dsInactive state.

Method Edit

Enables editing of data in the dataset. Call Edit to permit editing of the active record in a dataset. Edit determines the current state of the dataset. If the dataset is empty, Edit calls Insert. Otherwise Edit:

• Calls CheckBrowseMode to post any pending changes to a prior record if necessary.
• Checks the CanModify property and raises an exception if the dataset can't be edited.
• Calls the BeforeEdit event handler.
• Retrieves the record.
• Puts the dataset into dsEdit state, enabling the application or user to modify fields in the record.
• Broadcasts the state change to associated controls.
• Calls the AfterEdit event handler.

Method Post

Implements a method to write a modified record to the database or change log.

Dataset methods that change the dataset state, such as Edit, Insert, or Append, or that move from one record to another, such as First, Last, Next, and Prior automatically call Post.

Method Cancel

Cancels modifications to the active record if those changes are not yet posted.

Call Cancel to undo modifications made to one or more fields belonging to the active record. As long as those changes are not already posted, Cancel returns the record to its previous state, and sets the dataset state to dsBrowse. Typically Cancel is used to back out of changes in response to user request, or in field validation routines that back out illegal field values. The TDBNavigator object contains a Cancel button that calls Cancel.

Note: If the dataset is not in an editing state (dsEdit or dsInsert), Cancel does nothing.

Method Append

Adds a new, empty record to the end of the dataset. For datasets that permit editing, call Append to:

• Open a new, empty record at the end of the dataset.
• Set the active record to the new record.

After a call to Append, an application can enable users to enter data in the fields of the record, and can then post those changes to the database or change log using Post (Client datasets can subsequently apply updates in the change log back to the database by calling ApplyUpdates.)

Method Insert

Inserts a new, empty record in the dataset. Call Insert to:

• Open a new, empty record in the dataset.
• Set the active record to the new record.

After a call to Insert, an application can allow users to enter data in the fields of the record, and then post those changes to the database or change log using Post. (Client datasets can subsequently apply updates in the change log back to the database by calling ApplyUpdates.)

Method Delete

Deletes the active record and positions the dataset on the next record. Call Delete to remove the active record from the database. If the dataset is inactive, Delete raises an exception. Otherwise, Delete:

• Verifies that the dataset is not empty (and raises an exception if it is).
• Calls CheckBrowseMode to post any pending changes to a prior record if necessary.
• Calls the BeforeDelete event handler.
• Deletes the record.
• Frees any buffers allocated for the record.
• Puts the dataset into dsBrowse mode.
• Resynchronizes the dataset to make the next undeleted record active. If the record deleted was the last record in the dataset, then the previous record becomes the current record.
• Calls the AfterDelete event handler.

Method Refresh

Re-fetches data from the database to update a dataset's view of data. Call Refresh to ensure that an application has the latest data from a database. For example, when an application turns off filtering for a dataset, it should immediately call Refresh to display all records in the dataset, not just those that used to meet the filter condition.

TDataSet generates a BeforeRefresh event before refreshing the records and an AfterRefresh event afterwards.

Method EnableControls

Call EnableControls to permit data display in data-aware controls after a prior call to DisableControls. EnableControls decrements the disabled count variable for the dataset if it is not already zero. If the disable count variable is zero, EnableControls updates the current state of the dataset, if necessary, and then tells associated controls to re-enable display.

Method DisableControls

Call DisableControls prior to iterating through a large number of records in the dataset to prevent data-aware controls from updating every time the active record changes. Disabling controls prevents flicker and speeds performance because data does not need to be written to the display.

If controls are not already disabled, DisableControls records the current state of the dataset, broadcasts the state change to all associated data-aware controls and detail datasets, and increments the dataset's disabled count variable. Otherwise, DisableControls just increments the disabled count variable.

The disabled count is used internally to determine whether to display data in data-aware controls. When the disable count variable is greater than zero, data is not updated.

If the dataset is the master of a master/detail relationship, calling DisableControls also disables the master/detail relationship. Setting BlockReadSize instead of calling DisableControls updates the detail datasets as you scroll through the dataset, but does not update data-aware controls.

Function Abort

Abort raises a special "silent exception" (EAbort), which operates like any other exception, but does not display an error message to the end user.

Use Abort to escape from a BeforePost without reporting an error. This can particular be usefull for field validation.

Code Snippet - Abort

Sub ScriptExampleBeforePost(Sender)

Rem This is the place for field validation.

If xquScriptExample.FieldByName("Description").Value = "" Then

msgbox "Description field must have a value"

Abort

End If

End Sub

Code Snippet - Multi select

MsgBox "Selected row(s): " & dbgrdScriptExample.SelectedRows.Count

lstbxMultiSelect.Clear

dbgrdScriptExample.DataSource.DataSet.DisableControls

For i = 0 to (dbgrdScriptExample.SelectedRows.Count -1)

dbgrdScriptExample.DataSource.DataSet.BookMark = dbgrdScriptExample.SelectedRows.Items(i)

lstbxMultiSelect.Items.Add(dbgrdScriptExample.DataSource.DataSet.Fields(0).AsString)

Next

dbgrdScriptExample.DataSource.DataSet.EnableControls

TDataSet Events

Event AfterCancel

Occurs after an application completes a request to cancel modifications to the active record.Write an AfterCancel event handler to take specific action after an application cancels changes to the active record. AfterCancel is called by the Cancel method after it updates the current position, releases the lock on the active record if necessary, and sets the dataset state to dsBrowse. If an application requires additional processing before returning control to a user after a Cancel event, code it in the AfterCancel event.

Event AfterClose

Occurs after an application closes a dataset. Write an AfterClose event handler to take specific action immediately after an application closes a dataset. AfterClose is called after a dataset is closed and the dataset state is set to dsInactive.

Event AfterDelete

Occurs after an application deletes a record. Write an AfterDelete event handler to take specific action immediately after an application deletes the active record in a dataset. AfterDelete is called by Delete after it deletes the record, sets the dataset state to dsBrowse, and repositions the current record.

Event AfterEdit

Occurs after an application starts editing a record. Write an AfterEdit event handler to take specific action immediately after dataset enters edit mode. AfterEdit is called by Edit after it enables editing of a record, recalculates calculated fields, and calls the data event handler to process a record change.

Event AfterInsert

Occurs after an application inserts a new record. Write an AfterInsert event handler to take specific action immediately after an application inserts a record. The Insert and Append methods generate an AfterInsert event after inserting or appending a new record.

Event AfterOpen

Occurs after an application completes opening a dataset and before any data access occurs. Write an AfterOpen event handler to take specific action immediately after an application opens the dataset. AfterOpen is called after the dataset establishes access to its data and the dataset is put into dsBrowse state. For example, an AfterOpen event handler might check an ini file to determine the last record touched in the dataset the previous time the application ran, and position the dataset at that record.

Event AfterPost

Occurs after an application writes the active record to the database or change log and returns to browse state. Write an AfterPost event handler to take specific action immediately after an application posts a change to the active record. AfterPost is called after a modification or insertion is made to a record.

Event AfterRefresh

Occurs after an application refreshes the data in the dataset. Write an AfterRefresh event handler to take specific action immediately after an application has updated the records in the dataset. AfterRefresh is generated by calls to the Refresh method.

Event AfterScroll

Occurs after an application scrolls from one record to another. Write an AfterScroll event handler to take specific action immediately after an application scrolls to another record as a result of a call to the First, Last, Next, Prior and Locate methods. AfterScroll is called after all other events triggered by these methods and any other methods that switch from record to record in the dataset.

Event BeforeCancel

Occurs before an application executes a request to cancel changes to the active record. Write a BeforeCancel event to take specific action before an application carries out a request to cancel changes. BeforeCancel is called by the Cancel method before it cancels a dataset operation such as Edit, Insert, or Delete. An application might use the BeforeCancel event to record a user's changes in an undo buffer.

Event BeforeClose

Occurs immediately before the dataset closes. Write a BeforeClose event to take specific action before an application closes a dataset. Calling Close or setting the Active property to false results in a call to the BeforeClose event handler.

Event BeforeDelete

Occurs before an application attempts to delete the active record. Write a BeforeDelete event handler to take specific action before an application deletes the active record. BeforeDelete is called by Delete before it actually deletes a record. Making use of this event an application might display a dialog box asking for confirmation before deleting the record. On denial of confirmation, the application could abort the deletion by calling the Abort procedure.

Event BeforeEdit

Occurs before an application enters edit mode for the active record. Write a BeforeEdit event handler to take specific action before an application enables editing of the active record. For example, an application that keeps a log of database edits could use the BeforeEdit event to record the edit request, time, and user before entering edit state.

Event BeforeInsert

Occurs before an application enters insert mode. Write a BeforeInsert event handler to take specific action before an application inserts or appends a new record. The Insert or Append method generates a BeforeInsert method before it sets the dataset into dsInsert state.

Event BeforeOpen

Occurs before an application executes a request to open a dataset. Write a BeforeOpen event handler to take specific action before an application opens a dataset for viewing or editing. BeforeOpen is triggered when an application sets the Active property to true for a dataset or an application calls Open.

Event BeforePost

Occurs before an application posts changes for the active record to the database or change log. Write a BeforePost event handler to take specific action before an application posts dataset changes. BeforePost is triggered when an application calls the Post method. Post checks to make sure all required fields are present, then calls BeforePost before posting the record. An application might use BeforePost to perform validity checks on data changes before committing them. If it encountered a validity problem, it could cancel the Post operation.

Event BeforeScroll

Occurs before an application scrolls from one record to another. Write a BeforeScroll event handler to take specific action immediately before an application scrolls to another record as a result of a call to the First, Last, Next, Prior and Locate methods. BeforeScroll is called before all other events triggered by these methods and any other methods that switch from record to record in the dataset.

Event OnNewRecord

Occurs when an application inserts or appends a new dataset record. Write an OnNewRecord event handler to take specific actions as an application inserts or appends a new record. OnNewRecord is called as part of the insert or append process. An application might use the OnNewRecord event to set initial values for a record or as a way of implementing cascading insertions in related datasets.