Custom DB Engines Writing

FastReport allows building reports not only on the basis of data defined in application. You can define your own data sources (connections to DB, queries) right in report as well. FastReport is supplied with engines for ADO, BDE, IBX, DBX, FIB. You can create your own engine, and then connect it to FastReport.

The illustration below shows classes hierarchy intended for creating DB engines. New engine components are highlighted with green color.

As you can see, a standard set of DB engine components includes Database, Table and Query. You can create all these components or some of them (for example, many DB have no component of Table type). You can also create components, which are not included in the standard set (for example, StoredProc ).

Let us examine the basic classes in detail.

TfrxDialogComponent is the basic class for all non-visual components, which can be placed on a FastReport report design dialogue form. There are not any important properties or methods defined in it.

TfrxCustomDatabase class is basic class for DB components of “Database” type.

  TfrxCustomDatabase = class(TfrxDialogComponent)
  protected
    procedure SetConnected(Value: Boolean); virtual;
    procedure SetDatabaseName(const Value: String); virtual;
    procedure SetLoginPrompt(Value: Boolean); virtual;
    procedure SetParams(Value: TStrings); virtual;
    function GetConnected: Boolean; virtual;
    function GetDatabaseName: String; virtual;
    function GetLoginPrompt: Boolean; virtual;
    function GetParams: TStrings; virtual;
  public
    procedure SetLogin(const Login, Password: String); virtual;
    property Connected: Boolean read GetConnected write SetConnected default False;
    property DatabaseName: String read GetDatabaseName write SetDatabaseName;
    property LoginPrompt: Boolean read GetLoginPrompt write SetLoginPrompt default True;
    property Params: TStrings read GetParams write SetParams;
  end;

The following properties are defined in this class:

  • Connected – whether DB connection is active;

  • DatabaseName – database name;

  • LoginPrompt – whether to ask login when connecting to DB;

  • Params – connection parameters.

From the given class a component of TDatabase type is inherited. For its creation it is necessary to override all virtual methods and place the necessary properties in the to published section. Also it is necessary to add properties specific for your component.

TfrxDataset, TfrxCustomDBDataset, TfrxDBDataset classes provide the functions of data access. FastReport core uses these components for navigation and addressing data entering fields. In this case they are part of common hierarchy and are of no interest to us.

TfrxCustomDataSet is a basic class of DB components derived from TDataSet. Components, inherited from this class are “Query,” “Table,” and “StoredProc” clones. As a matter of fact, this class wraps over TDataSet.

  TfrxCustomDataset = class(TfrxDBDataSet)
  protected
    procedure SetMaster(const Value: TDataSource); virtual;
    procedure SetMasterFields(const Value: String); virtual;
  public
    property DataSet: TDataSet;
    property Fields: TFields readonly;
    property MasterFields: String;
    property Active: Boolean;
  published
    property Filter: String;
    property Filtered: Boolean;
    property Master: TfrxDBDataSet;
  end;

The following properties are defined in the class:

  • DataSet is a link to buried object of TDataSet type;

  • Fields is a link to DataSet.Fields;

  • Active - whether data set is active;

  • Filter - expression for filtering;

  • Filtered – whether filtering is active;

  • Master is a link to master dataset in master-detail relationship.

  • MasterFields is list of fields like field1=field2. Used for master-detail relations.

TfrxCustomTable – basic class for DB components of Table type. Class covers component of Table class.

  TfrxCustomTable = class(TfrxCustomDataset)
  protected
    function GetIndexFieldNames: String; virtual;
    function GetIndexName: String; virtual;
    function GetTableName: String; virtual;
    procedure SetIndexFieldNames(const Value: String); virtual;
    procedure SetIndexName(const Value: String); virtual;
    procedure SetTableName(const Value: String); virtual;
  published
    property MasterFields;
    property TableName: String read GetTableName write SetTableName;
    property IndexName: String read GetIndexName write SetIndexName;
    property IndexFieldNames: String read GetIndexFieldNames write SetIndexFieldNames;
  end;

The following properties are defined in class:

  • TableName – table name;

  • IndexName – index name;

  • IndexFieldNames – index field names.

Component of Table type is inherited from this class. For its creation it is necessary to define required properties, Database as usual. Also it is necessary to override virtual means from TfrxCustomDataset, TfrxCustomTable classes.

TfrxCustomQuery is basic class for DB components of “Query” type. This class is cover for Query type component.

  TfrxCustomQuery = class(TfrxCustomDataset)
  protected
    procedure SetSQL(Value: TStrings); virtual; abstract;
    function GetSQL: TStrings; virtual; abstract;
  public
    procedure UpdateParams; virtual; abstract;
  published
    property Params: TfrxParams;
    property SQL: TStrings;
  end;

SQL and Params properties (which are general for all Query components) are defined in the class. Since different Query components have different parameters realization (for example, TParams and TParameters), “Params” property has TfrxParams type and is a wrapper for concrete parameters type.

The following methods are defined in this class:

  • SetSQL is to set SQL component property of “Query” type;

  • GetSQL is to get SQL component property of “Query” type;

  • UpdateParams is to copy parameters values into component of Query type. If Query component parameters are of TParams type, copying is performed via frxParamsToTParams standard procedure.

Let us illustrate DB engine creation using the IBX example. Full engine original text can be found in SOURCE\IBX directory. Below are some quotations from source text with our comments.

IBX components around which we will build the wrapper are TIBDatabase, TIBTable, and TIBQuery. Accordingly, our components will be named TfrxIBXDatabase, TfrxIBXTable and TfrxIBXQuery.