Contents - Events - Methods - Properties

TFRDataSource encapsulates general dataset management functionality as editing, inserting, deleting records, retriving subset of records.

Description

Contents - TFRDataSource - Properties - Methods

GetNeedToFindRecord

Delphi declaration
property GetNeedToFindRecord: TFRGetNamedBoolValue read FGetNeedToFindRecord write FGetNeedToFindRecord;
C++ declaration
__property TFRGetNamedBoolValue GetNeedToFindRecord={ read=FGetNeedToFindRecord, write=FGetNeedToFindRecord }

Description
GetNeedToFind record is used to find out, if data record has to be located before custom action can be done.

GetRecordChanged

Delphi declaration
property GetRecordChanged: TFRGetBoolValue read FGetRecordChanged write FGetRecordChanged;
C++ declaration
__property TFRGetBoolValue GetRecordChanged={ read=FGetRecordChanged, write=FGetRecordChanged }

Description
GetRecordChanged event is used to find out if t he data recieved from t he client differs from t he data in t he dataset , and if t he dataset needs to be updated.

Implement GetRecordChanged , if you are using CustomFields , or if you are using TFRDataSource without t he dataset.

When GetRecordChaged is called, current input data is accessible from TFRInputParams.InputItem DataValues and t he relevant record in t he dataset is located ( OnFindRecord called, if necessary).

OnAppendRecord

Delphi declaration
property OnAppendRecord: TFRGetBoolValue read FOnAppendRecord write FOnAppendRecord;
C++ declaration
__property TFRGetBoolValue OnAppendRecord={ read=FOnAppendRecord, write=FOnAppendRecord }

Description
OnAppendRecord is called, when a new record has to be inserted to t he dataset. Implement OnAppendRecord, if you are using TFRDataSource without a database based dataset.

OnCancel

Delphi declaration
property OnCancel: TFRGetBoolValue read FOnCancel write FOnCancel;
C++ declaration
__property TFRGetBoolValue OnCancel={ read=FOnCancel, write=FOnCancel }

Description
OnCancel event is called, when edits or inserts to t he dataset are cancel l ed.

If you are using a database based dataset, you do not need to implement this event.

OnDelete

Delphi declaration
property OnDelete: TFRGetBoolValue read FOnDelete write FOnDelete;
C++ declaration
__property TFRGetBoolValue OnDelete={ read=FOnDelete, write=FOnDelete }

Description
OnDelete record is called, when a record has to be deleted from t he dataset.

If you are using a database based dataset, you will not need to implement this event.

OnEditRecord

Delphi declaration
property OnEditRecord: TFRGetBoolValue read FOnEditRecord write FOnEditRecord;
C++ declaration
__property TFRGetBoolValue OnEditRecord={ read=FOnEditRecord, write=FOnEditRecord }

Description
OnEditRecord event is called before a record is updated.

NOTE: if you are not using a database based dataset , you must remember that by default , ISAPI applications run in multi-thread mode , and you must implement a relevant locking mechanism to protect your data against other threads. In OnEditRecord event you must lock your record, in OnPostRecord and OnCancel you must release t he locks. When OnEditRecord event is called, other threads are by locked TFRDataSource and released, after your OnEdit event finishes.

OnException

Delphi declaration
property OnException: TFRExeptionEvent read FOnException write FOnException;
C++ declaration
__property TFRExeptionEvent OnException={ read=FOnException, write=FOnException }

Description
OnException event will be triggered , if an exception is raised while generating HTML. Use this event to free resources allocated in OnPrepare event , and to take specific recovery actions.

OnFindRecord

Delphi declaration
property OnFindRecord: TFRGetBoolValue read FOnFindRecord write FOnFindRecord;
C++ declaration
__property TFRGetBoolValue OnFindRecord={ read=FOnFindRecord, write=FOnFindRecord }

Description
Use OnFindRecord to locate a data record in TFRDataSource that does not use DataSet.

Data needed to locate a record is accessible from TFRInputParams.InputItem KeyValues property.

OnGetEnabledActions

Delphi declaration
property OnGetEnabledActions: TFRGetEnabledActions read FOnGetEnabledActions write FOnGetEnabledActions;
C++ declaration
__property TFRGetEnabledActions OnGetEnabledActions={ read=FOnGetEnabledActions, write=FOnGetEnabledActions }

Description
OnGetEnabledActions event is used to find out what actions will be enabled depending on current state of DataSet.

Parameters:

Name Type Meaning

Sendr TObject Caller of the event.

State AnsiString Current state of DataSource.

List TStrings List of actions.

Before the event is triggered, List is filled with possible data actions (default and user defined).

Depending on State you must remove from List t he actions that cannot be done with dataset in this State.

Default actions will be handled by TFRDataSource, you ne e d to handle only your own CustomActions .

In resulting HTML document controls will be enabled, if their FRDAction is listed in List and disabled else.

OnGetInputBoolValue

Delphi declaration
property OnGetInputBoolValue: TFRGetNamedBoolValue read FOnGetInputBoolValue write FOnGetInputBoolValue;
C++ declaration
__property TFRGetNamedBoolValue OnGetInputBoolValue={ read=FOnGetInputBoolValue, write=FOnGetInputBoolValue }

Description
OnGetInputBoolValue is used to get field data of Boolean type. If you are using CustomFields of Booleantype , you must implement this event.

OnGetInputName

Delphi declaration
property OnGetInputName: TFRGetNamedStrValue read FOnGetInputName write FOnGetInputName;
C++ declaration
__property TFRGetNamedStrValue OnGetInputName={ read=FOnGetInputName, write=FOnGetInputName }

Description
Use OnGetInputName to give specific names to HTML INPUT elements, linked with a field. Usually you will not need to implement OnGetInputName event, TFRDataSource will handle t he name generation automatically. If your HTML page contains data from more than one row in DataSource, names for INPUT elements will be numerated.

Note: if you will generate your own names for INPUT elements, values of these INPUT elements WILL NOT be available in InputParams!

OnGetInputValue

Delphi declaration
property OnGetInputValue: TFRGetNamedStrValue read FOnGetInputValue write FOnGetInputValue;
C++ declaration
__property TFRGetNamedStrValue OnGetInputValue={ read=FOnGetInputValue, write=FOnGetInputValue }

Description
OnGetInputValue event is used to get string representation of t he field data. If you are using CustomFields, other than Boolean, you must implement this event.

OnGetRecordCount

Delphi declaration
property OnGetRecordCount: TFRGetIntValue read FOnGetRecordCount write FOnGetRecordCount;
C++ declaration
__property TFRGetIntValue OnGetRecordCount={ read=FOnGetRecordCount, write=FOnGetRecordCount }

Description
OnGetRecordCount is used to get record count from underlying dataset.

If you are using a database based dataset , you will not need to implement this event.

OnNeedData

Delphi declaration
property OnNeedData: TFDataFindEvent read FOnNeedData write FOnNeedData;
C++ declaration
__property TFDataFindEvent OnNeedData={ read=FOnNeedData, write=FOnNeedData }

Description
OnNeedData event will be triggered when a record has to be retrived from underlying dataset.

Use OnNeedData to implement data reading for datasources without a dataset.

Parameters:

Name Type Meaning

Sender TFRDataSource DataSource that called the event

Action TFRDataFindAction frdaFirst Look for t he first record in t he dataset.

frdaNext Look for t he next record in t he dataset.

frdaPrior Look for t he prior record in t he dataset.

frdaLast Look for t he last record in t he dataset.

Found Boolean true, if record was found ; false , if not

OnPostRecord

Delphi declaration
property OnPostRecord: TFRGetBoolValue read FOnPostRecord write FOnPostRecord;
C++ declaration
__property TFRGetBoolValue OnPostRecord={ read=FOnPostRecord, write=FOnPostRecord }

Description
OnPostRecord is called after successful update of data.

NOTE: in OnPostRecord event you must release record locks (if any) activated in OnEdit event.

OnPrepare

Delphi declaration
property OnPrepare: TFRSimpleEvent read FOnPrepare write FOnPrepare;
C++ declaration
__property TFRSimpleEvent OnPrepare={ read=FOnPrepare, write=FOnPrepare }

Description
OnPrepare event will be triggered before t he HTML generation starts. Use this event to allocate resources, open queries , etc.

NOTE: OnPrepare and OnUnprepare events will be triggered only for t he datasource specified in URL or specified in TFReport.DataSource property. See Database management for more information.

OnRecordDataAction

Delphi declaration
property OnRecordDataAction: TFRHandleDataAction read FOnRecordDataAction write FOnRecordDataAction;
C++ declaration
__property TFRHandleDataAction OnRecordDataAction={ read=FOnRecordDataAction, write=FOnRecordDataAction }

Description
OnRecordDataAction is triggered once fo r each record in input parameters ( TFRInputParamItem ) after GetNeedToFindRecord has been triggered and, if necessary, t he record located.

OnSetValue

Delphi declaration
property OnSetValue: TFRSetNamedStrValue read FOnSetValue write FOnSetValue;
C++ declaration
__property TFRSetNamedStrValue OnSetValue={ read=FOnSetValue, write=FOnSetValue }

Description
OnSetValue is used to update field values in t he edited or inserted record. If you are using your own dataset, not based on t he database, or you are using CustomFields , you must implement this event.

OnUnprepare

Delphi declaration
property OnUnprepare: TFRSimpleEvent read FOnUnprepare write FOnUnprepare;
C++ declaration
__property TFRSimpleEvent OnUnprepare={ read=FOnUnprepare, write=FOnUnprepare }

Description
OnUnprepare event will be triggered after t he HTML generation is finished. Use this event to free t he resources allocated in OnPrepare event.

Contents - TFRDataSource - Properties - Events

FindFirst

Delphi declaration
function FindFirst: Boolean;
C++ declaration
virtual bool __fastcall FindFirst(void)

Description
Attempts to move to t he first record in t he dataset, triggers OnNeedData event.

Returns true, if sucessful.

FindLast

Delphi declaration
function FindLast: Boolean;
C++ declaration
virtual bool __fastcall FindLast(void)

Description
Attempts to move to t he last record in t he dataset, triggers OnNeedData event.

Returns true, if sucessful.

FindNext

Delphi declaration
function FindNext: Boolean;
C++ declaration
virtual bool __fastcall FindNext(void)

Description
Attempts to move to t he next record in t he dataset, triggers OnNeedData event.

Returns true, if sucessful.

FindPrior

Delphi declaration
function FindPrior: Boolean;
C++ declaration
virtual bool __fastcall FindPrior(void)

Description
Attempts to move to the prior record in the dataset, triggers OnNeedData event.

Returns true, if sucessful.

FindSaveInputRecord

Delphi declaration
function FindSaveInputRecord(RNum: Integer; AppendNotFound: Boolean): Boolean;
C++ declaration
bool __fastcall FindSaveInputRecord(int RNum, bool AppendNotFound)

Description
Used internally, do not use directly.

FRAppendRecord

Delphi declaration
function FRAppendRecord: Boolean;
C++ declaration
bool __fastcall FRAppendRecord(void)

Description
Appends a new record to t he dataset and triggers OnAppendRecord event.

FRCancel

Delphi declaration
function FRCancel: Boolean;
C++ declaration
bool __fastcall FRCancel(void)

Description
Cancels changes to t he dataset and triggers OnCancel event.

FRDeleteRecord

Delphi declaration
function FRDeleteRecord: Boolean;
C++ declaration
bool __fastcall FRDeleteRecord(void)

Description
Removes a record from t he dataset and triggers OnDelete event.

FREditRecord

Delphi declaration
function FREditRecord: Boolean;
C++ declaration
bool __fastcall FREditRecord(void)

Description
Prepares t he underlying dataset (i f any) for editing and triggers OnEditRecord event.

FRPostRecord

Delphi declaration
function FRPostRecord: Boolean;
C++ declaration
bool __fastcall FRPostRecord(void)

Description
Posts data to t he underlying dataset (if any) and triggers OnPostRecord event.

Contents - TFRDataSource - Methods - Events

ActionToDo

Action to do with data, recieved from client.

Delphi declaration
ActionToDo: AnsiString;
C++ declaration
System::AnsiString ActionToDo

Description
Default values:

Value Meaning

First Find t he first record in the dataset, set state to Browse and send t he record to t he client.

Next Find t he next record in t he dataset, set state to Browse and t he send record to t he client.

Prior Find t he prior record in t he dataset, set state to Browse and send t he record to t he client.

Last Find t he last record in t he dataset, set state to Browse and send t he record to t he client.

Edit Set state for current record to Edit.

Save Save data recieved from t he client to t he database. If InputState is Edit, record will be updated, if InputState is Append, a new record will be inserted.

Delete Delete t he current record.

Cancel Cancel edit or insert, set state to Browse.

Append Set state to Append.

You can add your own actions in TFRDataSource.CustomActions property.

CustomActions

List of user defined actions.

Delphi declaration
property CustomActions: TStringList read FCustomActions write SetCustomActions;
C++ declaration
__property Classes::TStringList *CustomActions={ read=FCustomActions, write=SetCustomActions, nodefault }

Description
Use CustomActions to add application-specific actions to your TFRDataSource components.

If you use CustomActions, you have to implement GetNeedToFindRecord event to show, if the data record has to be located or not before your action can be done, and OnRecordDataAction event to do the action.

CustomFields

List of user defined fields.

Delphi declaration
property CustomFields: TStringList read FCustomFields write SetCustomFields;
C++ declaration
__property Classes::TStringList *CustomFields={ read=FCustomFields, write=SetCustomFields, nodefault }

Description
Use CustomFields to add fictional fields that can be sent to t he client and t he client can send back to t he server.

OnGetInputValue event can be used to send data in t he custom field to t he client. T he d ata sent by t he client in t he custom field will be available in InputParams .

DefaultAction

Default a c tion to do.

Delphi declaration
property DefaultAction: AnsiString read FDefaultAction write FDefaultAction;
C++ declaration
__property System::AnsiString DefaultAction={ read=FDefaultAction, write=FDefaultAction, nodefault }

Description
Use default action to specify t he action to take when there is no action speci f ied in t he recieved query.

GroupBegin

Delphi declaration
property GroupBegin: Integer read FGroupBegin write FGroupBegin;
C++ declaration
__property int GroupBegin={ read=FGroupBegin, write=FGroupBegin, nodefault }

Description
Number of t he first record in t he group, managed by TFRGroupManager component.

GroupEnd

Delphi declaration
property GroupEnd: Integer read FGroupEnd write FGroupEnd;
C++ declaration
__property int GroupEnd={ read=FGroupEnd, write=FGroupEnd, nodefault }

Description
Number of t he last record in t he group, managed by TFRGroupManager component.

GroupLen

Delphi declaration
property GroupLen: Integer read FGroupLen write FGroupLen;
C++ declaration
__property int GroupLen={ read=FGroupLen, write=FGroupLen, nodefault }

Description
Group length. Managed by TFRGroupManager component.

GroupManager

Delphi declaration
property GroupManager: TFRGroupManager read Manager write Manager;
C++ declaration
__property TFRGroupManager *GroupManager={ read=Manager, write=Manager, nodefault }

Description
TFRGroupManager component for DataSource.

InputParams

TFRInputParams object created for TFRDataSource.

Delphi declaration
InputParams: TFRInputParams;
C++ declaration
TFRInputParams *InputParams

Description
Use InputParams to access t he data recieved from t he client.

InputState

State after previous request to DataSource.

Delphi declaration
InputState: AnsiString;
C++ declaration
System::AnsiString InputState

Description
Use InputState to examine in what state DataSource was left after t he previous request.

InsNewRecords

Count of new, empty records added to dataset.

Delphi declaration
property InsNewRecords: Integer read GetInsNewRecords write SetInsNewRecords;
C++ declaration
__property int InsNewRecords={ read=GetInsNewRecords, write=SetInsNewRecords, nodefault }

Description
Use InsNewRecords to add empty records to the end of t he data sent to clients. T he c lient can fill in all or some of these records and the new, filled records will be appended to the underlying database table every time when Post or Save action is called.

KeyFields

List of key fields used to identify record in dataset.

Delphi declaration
property KeyFields: TFRKeyFields read FKeyFields write SetKeyFields;
C++ declaration
__property TFRKeyFields *KeyFields={ read=FKeyFields, write=SetKeyFields, nodefault }

Description
In HTTP server you cannot have database cursors pointing to records processed by the client as in desktop or databese server applications. If database record is edited or deleted by t he user, your server application must first find out wh i ch record was edited or deleted . F or this purpose TFRDataSource uses key fields. KeyFields property must list a set of fields that enables t he application to uniquely identify one record in t he dataset. It is recommended to have index for fields listed in KeyFields property. TFRRecordKey is used to insert key fields into t he HTML document as HIDDEN elements that will be sent back to t he server, when HTML FORM is submit t ed.

MasterSource

Delphi declaration
property MasterSource: TFRDataSource read FMasterSource write SetMasterSource;
C++ declaration
__property TFRDataSource *MasterSource={ read=FMasterSource, write=SetMasterSource, nodefault }

Description
TFRDataSource or TDataSource used as master to implement master/detail relationship.

RecordCount

Delphi declaration
property RecordCount: Integer read GetRecordCount;
C++ declaration
__property int RecordCount={ read=GetRecordCount, nodefault }

Description
Use to find out t he count of records in the underlying dataset.

RetryTimes

Delphi declaration
property RetryTimes: Integer read FRetryTimes write FRetryTimes default 10;
C++ declaration
__property int RetryTimes={ read=FRetryTimes, write=FRetryTimes, default=10 }

Description
Specifies, how many times TFRDataSource attempts to get edit loc on t he underlying dataset before exception is raised.

State

State of DataSource.

Delphi declaration
State: AnsiString;
C++ declaration
System::AnsiString State

Description
Possible values:

Value Meaning

Browse Data was retrived for reading.

Edit Data was retrived for editing.

Append New record(s) w ere appended.