TDataSet.InsertRecord Method

Inserts a new, populated record to the dataset and posts it.

Pascal

procedure InsertRecord(const Values: array of const);

C++

__fastcall InsertRecord(const array of const Values);

Description

Call InsertRecord to create a new, empty record in the dataset, populate it with the field values in Values, and post the values to the database or change log. In C++, the Values_Size parameter indicates the index of the last value in the Values array (one less than the number of values).

A newly inserted 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 tables, the record is inserted into the dataset at the current position.

For unindexed dBASE, FoxPro, and Access tables, the record is inserted into the dataset at the end.

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

The newly inserted record becomes the active record.

C++ Examples:

Copy Code

/*
This statement inserts 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.
*/

void __fastcall TForm1::Button1Click(TObject *Sender)
{
  Customers->InsertRecord(ARRAYOFCONST((
    Edit1->Text, Edit2->Text, NULL,
    Edit3->Text)));
}

void __fastcall TForm1::FormCreate(TObject *Sender)
{
  Customers = new TTable(Form1);
  Customers->Active = false; // The Table component must not be active
  Customers->DatabaseName = "DBDEMOS";
  Customers->TableType = ttParadox;
  Customers->TableName = "CustInfo";
  if (Customers->Exists)
    MessageDlg("CustInfo table already exists.", mtWarning, TMsgDlgButtons() << mbOK, 0);
  else // Don't overwrite an existing table
  {
    // describe the fields in the table
    Customers->FieldDefs->Clear();
    TFieldDef *newDef = Customers->FieldDefs->AddFieldDef();
    newDef->Name = "Field1";
    newDef->DataType = ftInteger;
    newDef->Required = true;
    newDef = Customers->FieldDefs->AddFieldDef();
    newDef->Name = "Field2";
    newDef->DataType = ftString;
    newDef->Size = 30;
    newDef = Customers->FieldDefs->AddFieldDef();
    newDef->Name = "Field3";
    newDef->DataType = ftString;
    newDef->Size = 30;
    newDef = Customers->FieldDefs->AddFieldDef();
    newDef->Name = "Field4";
    newDef->DataType = ftString;
    newDef->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, i*333, i*444)));
  }
  DS2->DataSet = Customers;
  DBGrid2->DataSource->DataSet = Customers;
  Customers->Active = True;
}

Delphi Examples:

Copy Code

{
This statement inserts 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;