TDADataTable

From RemObjects Software

This is a Data Abstract Architecture entry
Feel free to add your notes to this topic below.

Overview

TDADataTable is the abstract base class for all client data table implementations in Data Abstract.

Client Data Tables are classes that hold live data on the client application at runtime, to make it available to application code and visual controls. Client Data Tables can be filled from a remote source (typically a server) using a TDARemoteDataAdapter that coordinates the connection to the server; they maintain a local history of changes (Delta) and can apply those changes back to the database, again using the Remote Data Adapter.

Data Abstract currently provides two concrete implementations of client data tables in the form of the TDACDSDataTable and TDAADODataTable components.

File

uDADataTable

Declaration

TDADataTable = class(TScriptableComponent, ISupportErrorInfo, IDADataTable, IDASQLCommand, IDADataset,
                     IDAEditableDataset, IDADeltaOwner, IDADataReader, IDADatasetEx, IDAClonedCursorsSupport);

Hierarchy

TScriptableComponent
- TDADataTable

Properties

Property	Type	Description
Active	Boolean	Manages whether the dataset is currently active (open) or not. Setting this property to true will automatically Open the dataset, while setting it to false will automatically Close it.
BusinessRulesID	String
Closing	Boolean	Returns whether the data table is currently closing (true) or not (false).
Delta	IDADelta	Maintains the local changes to the data table that have not yet been applied back to the server.
DetailFields	String	Holds the field or list of fields from the current data table that make up the foreign key of a Master/Detail relationship. These fields will be matched against the MasterFields from the MasterSource table.
DetailOptions	TDADetailOptions	Specifies how changes to the master affect the detail table in a Master/Detail relationship. These options will be set on the Detail table of the Master/Detail relationship. Automatically open or close the detail table when the master table is opened or closed. Automatically apply detail changes to the server when ApplyUpdate is called on the master. Automatically fetch new data for this detail table, when the master record has changed. Automatically delete detail records when the master record is deleted. Automatically update detail records, if one of the MasterFields has changed in the master, to keep the relationship intact. Do not log cascaded detail deletes. Enable this option if the back-end database is configured to automatically cascade deletes on its own and the detail deletes do not have to be applied back to the database, individually. Do not log cascaded detail updates. Enable this option if the back-end database is configured to automatically cascade updates on its own and the detail updates (if referring only to DetailFields) do not have to be applied back to the database, individually. Automatically download data for this detail table, when filling the master.
Editing	Boolean	Returns whether the data table is currently in editing mode (true) or not (false).
EOF	Boolean	Indicates whether reading the dataset has reached the end of the recordset (EOF = End of File). EOF will only turn true if neither an empty dataset was opened or Next was called while the cursor was already on the last record (it will not turn to true when reaching the last record).
Fetching	Boolean	Returns whether the data table is currently fetching data form a remote source (true) or not (false).
FieldCount	Integer	Gets the number of Fields contained in the dataset.
Fields	TDAFieldCollection	Provides access to all the fields contained in the dataset.
FieldValues	Variant	Gives convenient access to all the fields values of the current record without having to go though the Fields collection property.
HasDelta	Boolean	Indicates whether the current dataset contains any unapplied deltas, or not.
HasDeltaRecursive	Boolean	Returns whether the current dataset or any of its detail tables contain any unapplied deltas, or not.
IsEmpty	Boolean	Indicates whether the dataset is empty, that is does not contain any records (true) or not (false).
LocalConnection	String	Defines the name of the connection to use when filling the data table locally, on the server side or in a single-tier scenario. The LocalDataStreamer and LocalSchema properties need to be set as well for local fetch to work, and RemoteFetchEnabled must be set to false.
LocalDataStreamer	TDADataStreamer	Specifies the TDADataStreamer to be used when filling the data table locally, on the server side or in a single-tier scenario. The LocalConnection and LocalSchema properties need to be set as well for local fetch to work, and RemoteFetchEnabled must be set to false. Note that when the TDADataTable is used server side on a TDataAbstractService, you may not share the same data streamer between the data table and the TDataAbstractService's ServiceDataStreamer property, as data streamers are not reentrant.
LocalSchema	TDASchema	Sets the TDASchema to use when filling the data table locally, on the server side or in a single-tier scenario. The LocalConnection and LocalDataStreamer properties need to be set as well for local fetch to work, and RemoteFetchEnabled must be set to false.
LogChanges	Boolean	Manages whether the data table will keep track of changes made to its data using a Delta (true, default), or not (false). If set to false, no log of changes will be kept, and any changes made to the table will not be applied back to the back-end database.
LogicalName	String	Defines the name of the data table. This name will be used to identify the table when retrieving data from or applying changes back to the server, and will typically match the name of the table defined in the server-side schema.
MasterFields	String	Holds the field or list of fields from the MasterSource table that make up the primary key of a Master/Detail relationship. These fields will be matched against the DetailFields from the local data table.
MasterMappingMode	TDAMasterMappingMode	Specifies how values of the MasterFields will be passed to the server to fetch detail data. Available options are: Detail data will be fetched by setting the MasterFields as parameters on the data table (Default). Detail data will be fetched by passing the MasterFields as parameters to a custom data request method provided by the service.
MasterOptions	TDAMasterOptions	Controls how changes to the master affect the detail table in a Master/Detail relationship. These options will be set on the Master table of the Master/Detail relationship. Automatically open or close the detail table when the master table is opened or closed. Automatically apply detail changes to the server when ApplyUpdate is called on the master. Automatically delete detail records when the master record is deleted. Automatically update detail records, if one of the MasterFields has changed in the master, to keep the relationship intact. Do not log cascaded detail deletes. Enable this option if the back-end database is configured to automatically cascade deletes on its own and the detail deletes do not have to be applied back to the database, individually. Do not log cascaded detail updates. Enable this option if the back-end database is configured to automatically cascade updates on its own and the detail updates (if referring only to DetailFields) do not have to be applied back to the database, individually. Automatically download data for the detail table, when filling the master.
MasterParamsMappings	TStrings	Defines the mapping of MasterFields to data table parameters if the MasterMappingMode is set to mmParams.
MasterRequestMappings	TStrings	Sets the mapping of MasterFields to data request parameters if the MasterMappingMode is set to mmDataRequest.
MasterSource	TDADataSource	Specifies the data source (and thereby the data table) that acts as master for the current table, in a Master/Detail relationship.
MaxRecords	Integer	Assigns the maximum number of records to retrieve from the server when opening the data table. A value of -1 (default) will download all records.
Opening	Boolean	Indicates whether the data table is currently opening (true) or not (false).
Params	TDAParamCollection	Provides access to the list of parameters defined for the command.
ReadOnly	Boolean	Manages whether the data table is read-only (true) or not (false, default). If enabled, no changes to the data contained in the table will be permitted.
RecordCount	Integer	Returns the number of records currently contained in the data table.
RemoteDataAdapter	TDABaseRemoteDataAdapter	Specifies the TDARemoteDataAdapter used to exchange data with the server. Remote data adapters handle the communication between the data table and the server, and are needed for retrieving data from and applying changes to the server.
RemoteFetchEnabled	Boolean	Decides whether the data table will be filled from a remote source using a TDARemoteDataAdapter (true, default), or using a local TDASchema (false). If enabled, the RemoteDataAdapter property must be assigned to establish the link to the server; if disabled, the LocalConnection, LocalDataStreamer and LocalSchema properties need to be set.
RemoteUpdatesOptions	TDARemoteUpdatesOptions	Provides options for applying updates to the server. Available options include: Changes to records will automatically be applied to the server as they are posted.Enable this option to achieve behavior similar to single- or two-tier database applications, where posting a record in the user interface will directly apply the change to the back-end database. This basically triggers an automatic call to ApplyUpdates for each record change.
ScriptCode	TStrings	Contains the Business Rules Script code for the data table. This property can either be assigned manually, or filled from the server using the LoadScript method. For business rules scripts to run, a ScriptingProvider must be assigned.
StoreActive	Boolean	Decides whether the Active property will be stored in the Delphi DFM file (true), or not (false, default). If set to true, setting Active to true at design-time (for example to see live data) will persist this property to the DFM, and the data table will automatically be opened at runtime. If set to false, the data table will not open at runtime until explicitly being opened from code - allowing for example to perform additional configurations such as loading the server address from a config file before the table opens.
StreamingOptions	TDAStreamingOptions	Configures options for the streaming behavior of the data table. Available options include: Any schema information sent from the server as part of the data packet will be ignored and the data table will maintain its predefined schema.If not present, schema information present in the data stream can override the configured field settings. The data table's notification events for data or row changes will not fire during streaming processes, while downloading new data or applying changes (default).
Where	TDAWhere	Provides access to a structured WHERE clause that can be modified and expanded in code. The WHERE clause is represented by an instance of the TDAWhere class, which provides methods to dynamically build and extend the WHERE clause in code. Upon execution of the command, the appropriate WHERE statement will automatically be generated and appended to the original SQL statement.

Methods

Method	Description
ApplyUpdates	Applies all pending changes stored in the data table's Delta to the server using the RemoteDataAdapter.UpdateDataCall.
CancelUpdates	Discards all pending changes stored in the data table's Delta, reverting the data to the state after the last download or call to ApplyUpdates.
Close	Closes the dataset and discards any local data that had been retrieved from the database.
FieldByName	Locates a specific field contained in the dataset, based on its name. If no matching field is defined, an exception will be raised.
LoadFromFile	Loads the content of the data table, including the Delta, from a local briefcase file.
LoadFromRemoteSource	Fills the data table with data from the server using the RemoteDataAdapter.GetDataCall If MaxRecords property is not equal -1, method loads next MaxRecords records.
LoadFromStream	Loads the content of the data table, including the Delta, from a stream.
LoadSchema	Downloads the schema for the data table from the server using the RemoteDataAdapter.GetSchemaCall and fills the Fields and Params collections based on the newly obtained schema information.
LoadScript	Fills the ScriptCode property by downloading the appropriate script from the server using the RemoteDataAdapter.GetScriptsCall. For business rules scripts to run, a ScriptingProvider must be assigned.
MergeDelta	Merges the changes stored in the Delta into the base data of the data table, and clears the delta. This persists the changes in the local data, but removes them from the Delta so they will not be (re-)applied to the server. You will not usually call this method directly; it is used internally by ApplyUpdates. Call this method if you want to explicitly prevent pending changes from being applied to the server, but keep them in the local data table. For example, it could be imagined that after applying changes to the server, an application might delete records from the data table that are no longer needed locally - say to keep the memory footprint of the application small. After doing so, it would call MergeDelta, to ensure these deletes will not be propagated to the server. (Alternatively, the application could also set LogChanges to false while performing the deletes).
Open	Opens the dataset and prepares it for fetching records from the database. If the dataset is not empty, the cursor will be placed on the first available record; otherwise, EOF will be set to true to indicate the end of the (empty) record set has been reached.
ParamByName	Locates a specific parameter defined for the command, based on its name. If no matching parameter is defined, an exception will be raised.
SaveToFile	Saves the current content of the data table, including the Delta, to a local briefcase file.
SaveToStream	Saves the current content of the data table, including the Delta, to a stream.

Events

Event	Description
OnAfterApplyUpdates	Fires right after the data table has finished applying updates to the server.
OnAfterFieldChange	Fires right after a field was changed.
OnAfterMergeDelta	Fires right after the data table has finished merging delta received from the server.
OnBeforeApplyUpdates	Fires just before the data table starts applying updates to the server.
OnBeforeFieldChange	Fires just before a field is about to change, allowing the option to validate and possibly reject the new value.
OnBeforeMergeDelta	Fires just before the data table starts merging delta received from the server.

TDADataTable

From RemObjects Software

Overview

File

Declaration

Hierarchy

Properties

Methods

Events

See Also

Views

Personal tools

Navigation

products

special

Search

Toolbox