TDataSet.FieldByName Method

Finds a field based on its name.

Pascal

function FieldByName(const FieldName: WideString): TField;

C++

__fastcall TField FieldByName(const BSTR FieldName);

Description

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 EDatabaseError exception.

FieldName can be 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. Because of this flexibility, it is often preferable to use FieldByName rather than the Fields property or the AggFields property.

An application can directly access specific properties and methods of the field returned by FieldByName. For example, the following statement determines if a specified field is a calculated field:

Copy Code

if Customers.FieldByName('FullName').Calculated then
  MessageDlg(Format('%s is a calculated field. ', ['FullName']), mtInformation, [mbOK], 0);

Copy Code

if (Customers->FieldByName("FullName")->Calculated)
  Application.ShowMessage("This is a calculated field", "FullName", MB_OK);

FieldByName is especially useful at design time for developers who are creating database applications, but do not have access to the underlying table and therefore cannot use persistent field components.

Tip: To retrieve or set the value for a specific field, call the default dataset method FieldValues instead of FieldByName.

Delphi Examples:

Copy Code

{
The following example copies the data in the Notes field of
Table1 or SQLDataSet1 to the Remarks field of ClientDataSet1.
}
procedure TForm1.Button1Click(Sender: TObject);
var
  Stream1: TBlobStream;
  Stream2: TStream;
  blobType : TBlobType;
begin
  blobType := Table1Notes.BlobType;
  Stream1 := TBlobStream.Create(Table1Notes, bmRead);
  try
    CDS2.Edit;
    { here’s a different way to create a blob stream }
    Stream2 := CDS2.CreateBlobStream(CDS2.FieldByName('Remarks'), bmReadWrite);
    try
      Stream2.CopyFrom(Stream1, Stream1.Size);
//    CDS2.Post;
//    CDS2.Active := True;
    finally
      Stream2.Free;
    end;
  finally
    Stream1.Free;
  end;
end;

Copy Code

{
This example uses the BeforeInsert event to do data 
validation. If the StrToInt function raises an exception, 
the edit control’s contents are set to a valid value so 
that the assignment to the INTEGER field in the dataset 
will succeed.  Continuing after the exception causes a
'0' to be placed in the PORTA field.
DataSet design:
This example requires a ClientDataSet, a DBGrid, a
DataSource and a DBNavigator.  Name the ClientDataSet CDS.
Set the DataSet property in the DataSource to CDS and name
that DataSource DS.  Set the DataSource in the DBNavigator
to DS the DataSource in the DBGrid to DS.  Right click on CDS
and select the Fields Editor, then right click on the Field
Editor form and create two fields by selecting "new field".
In the field configuration window, set the name to HOST, the
Component value will automatically be set to CDSHOST.  Set
the filed type to String.  In the field configuration window
for the second field, set the name to PORTA, the Component
value will automatically be set to CDSPORTA.  Set the field
type to Integer.  The file used to load CDS must have an
attribute name of HOST with an attribute type of string and
an attribute name of PORTA with an attribute type of integer.
Add DB, DBCtrls, Grids, DBGrids and DBClient to the uses clause.
}
{$IFNDEF UNICODE}
uses SwSystem;
{$ENDIF}

procedure TForm1.Button3Click(Sender: TObject);
begin
  CDS.Insert;
  CDS.FieldByName('PORTA').AsInteger := StrToInt(Edit1.Text);
  CDS.Post;
end;

procedure TForm1.CDSBeforeInsert(DataSet: TDataSet);
begin
  try
  { Make sure edit field can be converted to integer --
   this will raise an exception if it can’t }
    StrToInt(Edit1.Text);
  except
    Edit1.Text := '0';
  end;
end;

procedure TForm1.FormCreate(Sender: TObject);
begin
{$IFDEF UNICODE}
  CDS.LoadFromFile(GetCurrentDir + '\CDS.XML');
{$ELSE}
  CDS.LoadFromFile(gsAppPath + 'CDS.XML');
{$ENDIF}
end;