The TDataSet component provides several methods for navigating the rows present in the underlying dataset, as well as properties for obtaining information about the current row position and reading data from the current row.

Moving the Row Pointer

---

To move the row pointer to a different position in the dataset, use the TDataSet First, Prior, Next, Last, MoveTo, and MoveBy methods. Use the TDataSet BOF, EOF, and RowNo properties to obtain information about the current row position.

The following example navigates from the beginning of a dataset to the end, appending each order ID to a string:

var
   OrderIDs: String='';
begin
   with CustomerOrders do
      begin
      First;
      while (not EOF) do
         begin
         if (OrderIDs='') then
            OrderIDs:=Columns['OrderID'].AsString
         else
            OrderIDs:=OrderIDs+', '+Columns['OrderID'].AsString;
         Next;
         end;
      end;
end;

Bookmark Operations

---

Sometimes it is necessary to save the current row pointer, perform some operations that may or may not move the row pointer, and then return to the saved row pointer. The TDataSet SaveBookmark, GotoBookmark, and FreeBookmark methods provide the bookmark functionality for datasets. Bookmarks include a non-volatile row ID and BOF/EOF information so that a row pointer can be restored even when the active sort has been changed. The only case when a row pointer cannot be restored is when the row represented by the bookmark has been deleted.


The following example saves the current row pointer as a bookmark, updates a column in all of the rows, and then restores the row pointer by calling GotoBookmark:

procedure TOrderEntryDlg.UpdateLineNumbers;
begin
   with CustomerItems do
      begin
      DisableControls;
      try
         SaveBookmark;
         try
            First;
            while (not EOF) do
               begin
               Update;
               Columns['LineNo'].AsInteger:=RowNo;
               Save;
               Next;
               end;
         finally
            GotoBookmark;
         end;
      finally
         EnableControls;
      end;
      end;
end;

Reading Column Values

---

The TDataSet Columns property allows you to read the column values for the current row. You can access a column in the Columns property by its index or by its name via the TDataColumns Column property. However, since the Column property is the default property for the TDataColumns object, you can omit it when referencing the Columns property. The following example loops through all columns in a dataset and appends their name to a string:

var
   I: Integer;
   ColumnNames: String='';
begin
   with CustomerOrders do
      begin
      for I:=0 to Columns.Count-1 do
         begin
         if (ColumnNames='') then
            ColumnNames:=Columns[I].Name
         else
            ColumnNames:=ColumnNames+','+Columns[I].Name
         end;
      end;
end;

Each TDataColumn object present in the TDataSet Columns property has several As* properties that allow you to access the data in the column for the current row as a particular type. Type conversions are performed automatically wherever necessary. However, certain type conversions are impossible and will, if attempted, cause an exception to be raised. For example, the following code will cause an exception to be raised because the OrderDate column, which has a type of dtDate, cannot be converted to a Boolean value:

begin
   with CustomerOrders do
      Result:=Columns['OrderDate'].AsBoolean;
end;

To determine if a column is Null, you can use the TDataColumn Null property.

Tracking Navigation Operations

---

The TDataSet BeforeScroll event is fired before the dataset's row pointer moves during navigation. To prevent the navigation from occurring, return False as the result in an event handler for this event.

The TDataSet AfterScroll event is fired after the dataset's row pointer is moved.

The following TDataSet property assignments cause the BeforeScroll and AfterScroll events to be triggered:

   RowID
   RowNo

The following TDataSet methods cause the BeforeScroll and AfterScroll events to be triggered:

   First
   Prior
   Next
   Last
   MoveBy
   MoveTo
   Find
   Sort
   GotoBookmark