TTable.SetRange Method

Sets the starting and ending values of a range, and applies it.

Pascal

procedure SetRange(const StartValues: array of const; const EndValues: array of const);

C++

__fastcall SetRange(const array of const StartValues, const array of const EndValues);

Description

Call SetRange to specify a range and apply it to the dataset. The new range replaces the currently applied range, if any.

StartValues indicates the field values that designate the first record in the range. StartValues_Size specifies the index of the last value in StartValues (one less than the total number of values).

EndValues indicates the field values that designate the last record in the range. EndValues_Size specifies the index of the last value in EndValues (one less than the total number of values).

SetRange combines the functionality of SetRangeStart, SetRangeEnd, and ApplyRange in a single procedure call. SetRange performs the following functions:

1Puts the dataset into dsSetKey state.

2Erases any previously specified starting range values and ending range values.

3Sets the start and end range values.

4Applies the range to the dataset.

If either StartValues or EndValues has fewer elements than the number of fields in the current index, then the remaining entries are set to NULL.

After a call to SetRange, the cursor is left on the first record in the range.

Note: With Paradox or dBASE tables, SetRange works only on indexed fields. With SQL databases, SetRange also works with any columns specified in the IndexFieldNames property.

Delphi Examples:

Copy Code

{
The following example sets a range for a dataset. The form
requires two edit boxes, a data source, a client dataset or
table, a db grid, and a button.  Make sure that the Table1
info in FormActivate agrees with the table used.  Also, the
caption for the button must be initialized to '&ApplyRange'.
}

procedure TForm1.FormActivate(Sender: TObject);
begin
  Table1.DatabaseName := 'DBDEMOS';
  Table1.TableName := 'CustInfo';
  Table1.Active := True;
  Table1.IndexName := '';
end;

procedure TForm1.Button2Click(Sender: TObject);
begin
  if Button2.Caption = '&Apply Range' then
    begin
      Table1.SetRange([Edit1.Text],[Edit2.Text]);
      Button2.Caption := '&Drop Range';
    end
  else
    begin
      Table1.CancelRange;
      Table1.Refresh;
      Button2.Caption := '&Apply Range';
    end;
end;

procedure TForm1.FormCreate(Sender: TObject);
var
  i: Integer;
begin
  Table1:= TTable.Create(Form1);
  with Table1 do
  begin
    DatabaseName := 'DBDEMOS';
    TableType := ttParadox;
    TableName := 'CustInfo';
    Table1.Active := False;
    { Don't overwrite an existing table }
    if Table1.Exists then
      MessageDlg('CustInfo table already exists.', mtWarning, [mbOK], 0)
    else
    begin
      { The Table component must not be active }
      { First, describe the type of table and give }
      { it a name }
      { Next, describe the fields in the table }
      with FieldDefs do
      begin
        Clear;
        with AddFieldDef do
        begin
          Name := 'Field1';
          DataType := ftInteger;
          Required := True;
        end;
        with AddFieldDef do
        begin
          Name := 'Field2';
          DataType := ftString;
          Size := 30;
        end;
      end;
      { Next, describe any indexes }
      with IndexDefs do
      begin
        Clear;
        { The 1st index has no name because it is
        { a Paradox primary key }
        with AddIndexDef do
        begin
          Name := '';
          Fields := 'Field1';
          Options := [ixPrimary];
        end;
        with AddIndexDef do
        begin
          Name := 'Fld2Indx';
          Fields := 'Field2';
          Options := [ixCaseInsensitive];
        end;
      end;
      { Call the CreateTable method to create the table }
      CreateTable;
      Table1.Active:= True;
      for i := 1 to 20 do
        Table1.AppendRecord([i*111, i*222]);
    end;
  end;
  DS2.DataSet:= Table1;
  DBGrid2.DataSource.DataSet:= Table1;
  Table1.Active:= False;
end;