TDataSet.AppendRecord Method

Adds a new, populated record to the end of the dataset and posts it.

Pascal

procedure AppendRecord(const Values: array of const);

C++

__fastcall AppendRecord(const array of const Values);

Description

Call AppendRecord to create a new, empty record at the end of the dataset, populate it with the field values in Values, and post the values to the database or change log.

In C++, the Values parameter is an array of field values. The Values_Size parameter is the index of the last value (one less than the total number of values).

A newly appended record is posted to the database in one of three ways:

For indexed Paradox and dBASE tables, the record is inserted into the dataset in a position based on its index.

For unindexed Paradox and dBASE tables, the record is added to the end of the dataset.

For SQL databases, the physical location of the append is implementation-specific. For indexed tables, the index is updated with the new record information.

The newly appended record becomes the active record.

C++ Examples:

Copy Code

/*
The following example shows how to create a table.
*/

void __fastcall TForm1::FormCreate(TObject *Sender)
{
  Table1 = new TTable(Form1);
  Table1->Active = false; // The Table component must not be active
  Table1->DatabaseName = "DBDEMOS";
  Table1->TableType = ttParadox;
  Table1->TableName = "CustInfo";
  if (Table1->Exists)
    MessageDlg("CustInfo table already exists.", mtWarning, TMsgDlgButtons() << mbOK, 0);
  else // Don't overwrite an existing table
  {
    // describe the fields in the table
    Table1->FieldDefs->Clear();
    TFieldDef *newDef = Table1->FieldDefs->AddFieldDef();
    newDef->Name = "Field1";
    newDef->DataType = ftInteger;
    newDef->Required = true;
    newDef = Table1->FieldDefs->AddFieldDef();
    newDef->Name = "Field2";
    newDef->DataType = ftString;
    newDef->Size = 30;
    // Next, describe any indexes
    Table1->IndexDefs->Clear();
    /* the 1st index has no name because it is a Paradox primary key */
    Table1->IndexDefs->Add("","Field1", TIndexOptions() <<ixPrimary << ixUnique);
    Table1->IndexDefs->Add("Fld2Index", "Field2", TIndexOptions() << ixCaseInsensitive);
    // Now that we have specified what we want, create the table
    Table1->CreateTable();
    Table1->Active = True;
    for (int i = 1; i <= 20; i++)
      Table1->AppendRecord(ARRAYOFCONST((i*111, i*222)));
  }
  DS2->DataSet = Table1;
  DBGrid2->DataSource->DataSet = Table1;
  Table1->Active = True;
}
//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
  Table1->Close();
  Table1->DeleteTable();
}

Copy Code

/*
Reads through all records in the Customers table.
Updates the ProgressBar accordingly.
*/
void __fastcall TForm1::Button1Click(TObject *Sender)
{
  ProgressBar1->Min = 0;
  ProgressBar1->Max = Customers->RecordCount;
  Customers->First();
  for (int i = ProgressBar1->Min; i <= ProgressBar1->Max; i++)
  {
    ProgressBar1->Position = i;
    Customers->Next();
    // do something with the current record
  }
}

void __fastcall TForm1::FormCreate(TObject *Sender)
{
  Customers = new TTable(Form1); // The owner will clean this up.
  Customers->Active = false; // The Table component must not be active
  Customers->DatabaseName = "DBDEMOS";
  Customers->TableType = ttParadox;
  Customers->TableName = "CustInfo";
  Customers->Active = False;
  if (Customers->Exists) // Don't overwrite an existing table
  {
    Customers->Close();
    Customers->DeleteTable();
  }
  // 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
  Customers->FieldDefs->Clear();
  TFieldDef *pNewDef = Customers->FieldDefs->AddFieldDef();
  pNewDef->Name = "Field1";
  pNewDef->DataType = ftInteger;
  pNewDef->Required = true;
  pNewDef = Customers->FieldDefs->AddFieldDef();
  pNewDef->Name = "Field2";
  pNewDef->DataType = ftString;
  pNewDef->Size = 30;
  // Next, describe any indexes
  Customers->IndexDefs->Clear();
  /* the 1st index has no name because it is a Paradox primary key */
  Customers->IndexDefs->Add("","Field1", TIndexOptions() <<ixPrimary << ixUnique);
  Customers->IndexDefs->Add("Fld2Index","Field2", TIndexOptions() << ixCaseInsensitive);
  // Now that we have specified what we want, create the table
  Customers->CreateTable();
  Customers->Active = True;
  for (int i = 1; i <= 20; i++)
    Customers->AppendRecord(ARRAYOFCONST((i*111, i*222)));
  DS2->DataSet = Customers;
  DBGrid2->DataSource->DataSet = Customers;
  Customers->Active = True;
}

Delphi Examples:

Copy Code

{
This statement appends a record to the MyCustInfo data. Note
that Nulls are entered for some of the values, but are not
required for missing values at the end of the array argument,
i.e. after the Field3 field.  InsertRecord behaves differently
depending on the indexing of the table.
}
procedure TForm1.Button1Click(Sender: TObject);
begin
  Customers.InsertRecord([Edit1.Text, Edit2.Text, Null, Edit3.Text]);
end;

procedure TForm1.FormCreate(Sender: TObject);
begin
  Customers:= TTable.Create(Form1);
  with Customers do
  begin
    DatabaseName := 'DBDEMOS';
    TableType := ttParadox;
    TableName := 'MyCustInfo';
    ReadOnly:= False;

//    Don't overwrite an existing table
    if (not Customers.Exists) then CreateMyTable
    else
    begin
      if (Customers.Exists AND
        (MessageDlg('MyCustInfo table already exists.  Do you want to rebuild it?', mtConfirmation, [mbYes, mbNo], 0) = mrYes)) then
      begin
        Customers.Close;
        Customers.DeleteTable;
        CreateMyTable;
      end;
    end;
  end;
  DS2.DataSet:= Customers;
  DBGrid2.DataSource.DataSet:= Customers;
  Customers.Active:= True;
end;

procedure CreateMyTable();
var
  i: Integer;
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 Customers do
  begin
      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;
        with AddFieldDef do
        begin
          Name := 'Field3';
          DataType := ftString;
          Size := 30;
        end;
        with AddFieldDef do
        begin
          Name := 'Field4';
          DataType := ftString;
          Size := 30;
        end;
      end;

//    Take out this part to remove indexing
//    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;
      Customers.Active:= True;
      for i := 1 to 20 do
        Customers.AppendRecord([i*111, i*222, i*333, i*444]);
    end;
end;

Copy Code

{
Reads through all records in the Customers table.
Updates the ProgressBar accordingly.
}
procedure TForm1.Button1Click(Sender: TObject);
var
  i: Integer;
begin
  with ProgressBar1 do
  begin
    Min := 0;
    Max := Customers.RecordCount;
    Customers.First;
    for i := Min to Max do
    begin
      Position := i;
      Customers.Next;
      // do something with the current record
    end;
  end;
end;

procedure TForm1.FormCreate(Sender: TObject);
var
  i: Integer;
begin
  Customers:= TTable.Create(Form1);
  with Customers do
  begin
    DatabaseName := 'DBDEMOS';
    TableType := ttParadox;
    TableName := 'CustInfo';
    Active := False;
//  Overwrite any existing table
    if Customers.Exists then
    begin
      Customers.Close;
      Customers.DeleteTable;
    end;
    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;
      Customers.Active:= True;
      for i := 1 to 100 do
        Customers.AppendRecord([i*111, i*222]);
    end;
  end;
  DS2.DataSet:= Customers;
  DBGrid2.DataSource.DataSet:= Customers;
  Customers.Active:= True;
end;