RAD Studio |  |

Using client datasets
Collapse All
Topics

Name | Description
Adding a New Index | There are three ways to add indexes to a client dataset:
Adding Application-specific Information to the Data | Application developers can add custom information to the client dataset's Data property. Because this information is bundled with the data packet, it is included when you save the data to a file or stream. It is copied when you copy the data to another dataset. Optionally, it can be included with the Delta property so that a provider can read this information when it receives updates from the client dataset. To save application-specific information with the Data property, use the SetOptionalParam method. This method lets you store an OleVariant that contains the data under a specific name. To... more
Aggregating over groups of records | By default, maintained aggregates are calculated so that they summarize all the records in the client dataset. However, you can specify that you want to summarize over the records in a group instead. This lets you provide intermediate summaries such as subtotals for groups of records that share a common field value. Before you can specify a maintained aggregate over a group of records, you must use an index that supports the appropriate grouping. Once you have an index that groups the data in the way you want it summarized, specify the IndexName and GroupingLevel properties of the aggregate... more
Applying Updates | Changes made to the client dataset's local copy of data are not sent to the database server (or XML document) until the client application calls the ApplyUpdates method. ApplyUpdates takes the changes in the change log, and sends them as a data packet (called Delta) to the provider. (Note that, when using most client datasets, the provider is internal to the client dataset.) ApplyUpdates takes a single parameter, MaxErrors, which indicates the maximum number of errors that the provider should tolerate before aborting the update process. If MaxErrors is 0, then as soon as an update error occurs,... more
Choosing the Type of Dataset for Caching Updates | Delphi includes some specialized client dataset components for caching updates. Each client dataset is associated with a particular data access mechanism. These are listed in the following table: Specialized client datasets for caching updates
Communicating with Providers Using Custom Events | Client datasets communicate with a provider component through a special interface called IAppServer. If the provider is local, IAppServer is the interface to an automatically-generated object that handles all communication between the client dataset and its provider. If the provider is remote, IAppServer is the interface to a remote data module on the application server, or (in the case of a SOAP server) an interface generated by the connection component. TClientDataSet provides many opportunities for customizing the communication that uses the IAppServer interface. Before and after every IAppServer method call that is directed at the client dataset's provider, TClientDataSet receives... more
Constraining Data Values | Client datasets can enforce constraints on the edits a user makes to data. These constraints are applied when the user tries to post changes to the change log. You can always supply custom constraints. These let you provide your own, application-defined limits on what values users post to a client dataset. In addition, when client datasets represent server data that is accessed using the BDE, they also enforce data constraints imported from the database server. If the client dataset works with an external provider component, the provider can control whether those constraints are sent to the client dataset, and the... more
Copying Data from Another Dataset | To copy the data from another dataset at design time, right click the client dataset and choose Assign Local Data. A dialog appears listing all the datasets available in your project. Select the one whose data and structure you want to copy and choose OK. When you copy the source dataset, your client dataset is automatically activated. To copy from another dataset at runtime, you can assign its data directly or, if the source is another client dataset, you can clone the cursor.
Creating a New Dataset | There are three ways to define and create client datasets that do not represent server data: You can define and create a new client dataset using persistent fields or field and index definitions. This follows the same scheme as creating any table type dataset. See Creating and deleting tables for details. You can copy an existing dataset (at design or runtime). You can create a client dataset from an arbitrary XML document. See Converting XML documents into data packets for details. Once the dataset is created, you can save it to a file. From then on, you do not need... more
Deleting and Switching Indexes | To remove an index you created for a client dataset, call DeleteIndex and specify the name of the index to remove. You cannot remove the DEFAULT_ORDER and CHANGEINDEX indexes. To use a different index when more than one index is available, use the IndexName property to select the index to use. At design time, you can select from available indexes in IndexName property drop-down box in the Object Inspector.
Editing Data | Client datasets represent their data as an in-memory data packet. This packet is the value of the client dataset's Data property. By default, however, edits are not stored in the Data property. Instead the insertions, deletions, and modifications (made by users or programmatically) are stored in an internal change log, represented by the Delta property. Using a change log serves two purposes: The change log is required for applying updates to a database server or external provider component. The change log provides sophisticated support for undoing changes. The LogChanges property lets you disable logging. When LogChanges is True, changes... more
Getting Parameters from the Application Server | There are two circumstances when the client dataset needs to fetch parameter values: The application needs the value of output parameters on a stored procedure. The application wants to initialize the input parameters of a query or stored procedure to the current values on the source dataset. Client datasets store parameter values in their Params property. These values are refreshed with any output parameters when the client dataset fetches data from the source dataset. However, there may be times a TClientDataSet component in a client application needs output parameters when it is not fetching data. To fetch output parameters... more
Handling Constraints from the Server | When a database server defines constraints on what data is valid, it is useful if the client dataset knows about them. That way, the client dataset can ensure that user edits never violate those server constraints. As a result, such violations are never passed to the database server where they would be rejected. This means fewer updates generate error conditions during the updating process. Regardless of the source of data, you can duplicate such server constraints by explicitly adding them to the client dataset. This process is described in Constraining data values. It is more convenient, however, if the... more
Indicating What Records Are Modified | While the user edits a client dataset, you may find it useful to provide feedback about the edits that have been made. This is especially useful if you want to allow the user to undo specific edits, for example, by navigating to them and clicking an "Undo" button. The UpdateStatus method and StatusFilter properties are useful when providing feedback on what updates have occurred: UpdateStatus indicates what type of update, if any, has occurred for the current record. It can be any of the following values: usUnmodified indicates that the current record is unchanged. usModified indicates that the current record... more
Intervening as Updates Are Applied | When a client dataset applies its updates, the provider determines how to handle writing the insertions, deletions, and modifications to the database server or source dataset. When you use TClientDataSet with an external provider component, you can use the properties and events of that provider to influence the way updates are applied. These are described in Responding to client update requests. When the provider is internal, however, as it is for any client dataset associated with a data access mechanism, you can't set its properties or provide event handlers. As a result, the client dataset publishes one property and... more
Limiting Records with Parameters | If the client dataset is a TClientDataSet instance whose associated provider represents a TTable or TSQLTable component a TSimpleDataSet or a TBDEClientDataSet instance whose CommandType property is ctTable then it can use the Params property to limit the records that it caches in memory. Each parameter represents a field value that must be matched before a record can be included in the client dataset's data. This works much like a filter, except that with a filter, the records are still cached in memory, but unavailable. Each parameter name must match the name of a field. When using TClientDataSet, these... more
Merging Changes into Data | When you edit the data in a client dataset, all edits to the data exist only in an in-memory change log. This log can be maintained separately from the data itself, although it is completely transparent to objects that use the client dataset. That is, controls that navigate the client dataset or display its data see a view of the data that includes the changes. If you do not want to back out of changes, however, you should merge the change log into the data of the client dataset by calling the MergeChangeLog method. MergeChangeLog overwrites records in Data with... more
Navigating Data in Client Datasets | If an application uses standard data-aware controls, then a user can navigate through a client dataset's records using the built-in behavior of those controls. You can also navigate programmatically through records using standard dataset methods such as First, Last, Next, and Prior. For more information about these methods, see Navigating datasets. Unlike most datasets, client datasets can also position the cursor at a specific record in the dataset by using the RecNo property. Ordinarily an application uses RecNo to determine the record number of the current record. Client datasets can, however, set RecNo to a... more
Obtaining Aggregate Values | To get the value of a maintained aggregate, call the Value method of the TAggregate object that represents the aggregate. Value returns the maintained aggregate for the group that contains the current record of the client dataset. When you are summarizing over the entire client dataset, you can call Value at any time to obtain the maintained aggregate. However, when you are summarizing over grouped information, you must be careful to ensure that the current record is in the group whose summary you want. Because of this, it is a good idea to obtain aggregate values at clearly specified times,... more
Overriding the Dataset On the Application Server | The client datasets that are associated with a particular data access mechanism use the CommandText and CommandType properties to specify the data they represent. When using TClientDataSet, however, the data is specified by the source dataset, not the client dataset. Typically, this source dataset has a property that specifies an SQL statement to generate the data or the name of a database table or stored procedure. If the provider allows, TClientDataSet can override the property on the source dataset that indicates what data it represents. That is, if the provider permits, the client dataset's CommandText property replaces the... more
Overview of Using Cached Updates | To use cached updates, the following order of processes must occur in an application: Indicate the data you want to edit. How you do this depends on the type of client dataset you are using: If you are using TClientDataSet, Specify the provider component that represent the data you want to edit. If you are using a client dataset associated with a particular data access mechanism, you must Identify the database server by setting the DBConnection property to an appropriate connection component. Indicate what data you want to see by specifying the CommandText and CommandType properties. CommandType indicates whether... more
Passing Parameters to the Source Dataset | Client datasets can pass parameters to the source dataset to specify what data they want provided in the data packets it sends. These parameters can specify Input parameter values for a query or stored procedure that is run on the application server Field values that limit the records sent in data packets You can specify parameter values that your client dataset sends to the source dataset at design time or at runtime. At design time, select the client dataset and double-click the Params property in the Object Inspector. This brings up the collection editor, where you can add, delete,... more
Refreshing Records | Client datasets work with an in-memory snapshot of the data from the source dataset. If the source dataset represents server data, then as time elapses other users may modify that data. The data in the client dataset becomes a less accurate picture of the underlying data. Like any other dataset, client datasets have a Refresh method that updates its records to match the current values on the server. However, calling Refresh only works if there are no edits in the change log. Calling Refresh when there are unapplied edits results in an exception. Client datasets can also update the data... more
Representing Calculated Values | As with any dataset, you can add calculated fields to your client dataset. These are fields whose values you calculate dynamically, usually based on the values of other fields in the same record. Client datasets, however, let you optimize when fields are calculated by using internally calculated fields. You can also tell client datasets to create calculated values that summarize the data in several records using maintained aggregates.
Requesting Data from the Source Dataset or Document | Client datasets can control how they fetch their data packets from a provider. By default, they retrieve all records from the source dataset. This is true whether the source dataset and provider are internal components (as with TBDEClientDataSet,TSimpleDataSet, and TIBClientDataSet), or separate components that supply the data for TClientDataSet. You can change how the client dataset fetches records using the PacketRecords and FetchOnDemand properties.
Saving Changes | Client datasets use different mechanisms for incorporating changes from the change log, depending on whether the client datasets stores its data in a file or represents data obtained through a provider. Whichever mechanism is used, the change log is automatically emptied when all updates have been incorporated. File-based applications can simply merge the changes into the local cache represented by the Data property. They do not need to worry about resolving local edits with changes made by other users. To merge the change log into the Data property, call the MergeChangeLog method. Merging changes into data describes this process. You... more
Sending Query or Stored Procedure Parameters | When the client dataset's CommandType property is ctQuery or ctStoredProc, or, if the client dataset is a TClientDataSet instance, when the associated provider represents the results of a query or stored procedure, you can use the Params property to specify parameter values. When the client dataset requests data from the source dataset or uses its Execute method to run a query or stored procedure that does not return a dataset, it passes these parameter values along with the request for data or the execute command. When the provider receives these parameter values, it assigns them to its associated dataset.... more
Setting Up a Simple Dataset | Setting up a simple dataset requires two essential steps. Set up: The connection information. The dataset information. The following steps describe setting up a simple dataset in more detail.
Sorting and Indexing | Using indexes provides several benefits to your applications: They allow client datasets to locate data quickly. They let you apply ranges to limit the available records. They let your application set up relationships with other datasets such as lookup tables or master/detail forms. They specify the order in which records appear. If a client dataset represents server data or uses an external provider, it inherits a default index and sort order based on the data it receives. The default index is called DEFAULT_ORDER. You can use this ordering, but you cannot change or delete the index. In addition to the... more
Specifying a Provider | Unlike the client datasets that are associated with a data access mechanism, TClientDataSet has no internal provider component to package data or apply updates. If you want it to represent data from a source dataset or XML document, therefore, you must associated the client dataset with an external provider component. The way you associate TClientDataSet with a provider depends on whether the provider is in the same application as the client dataset or on a remote application server running on another system.
Specifying Aggregates | To specify that you want to calculate summaries over the records in a client dataset, use the Aggregates property. Aggregates is a collection of aggregate specifications (TAggregate). You can add aggregate specifications to your client dataset using the Collection Editor at design time, or using the Add method of Aggregates at runtime. If you want to create field components for the aggregates, create persistent fields for the aggregated values in the Fields Editor. Note: When you create aggregated fields, the appropriate aggregate objects are added to the client dataset's Aggregates property automatically. Do not add them explicitly when creating aggregated... more
Undoing Changes | Even though a record's original version remains unchanged in Data, each time a user edits a record, leaves it, and returns to it, the user sees the last changed version of the record. If a user or application edits a record a number of times, each changed version of the record is stored in the change log as a separate entry. Storing each change to a record makes it possible to support multiple levels of undo operations should it be necessary to restore a record's previous state: To remove the last change to a record, call UndoLastChange. UndoLastChange takes... more
Updating Records | The contents of the change log are stored as a data packet in the client dataset's Delta property. To make the changes in Delta permanent, the client dataset must apply them to the database (or source dataset or XML document). When a client applies updates to the server, the following steps occur: The client application calls the ApplyUpdates method of a client dataset object. This method passes the contents of the client dataset's Delta property to the (internal or external) provider. Delta is a data packet that contains a client dataset's updated, inserted, and deleted records. The provider applies the... more
Using a Client Dataset to Cache Updates | By default, when you edit data in most datasets, every time you delete or post a record, the dataset generates a transaction, deletes or writes that record to the database server, and commits the transaction. If there is a problem writing changes to the database, your application is notified immediately: the dataset raises an exception when you post the record. If your dataset uses a remote database server, this approach can degrade performance due to network traffic between your application and the server every time you move to a new record after editing the current record. To minimize the network... more
Using a Client Dataset with a Provider | A client dataset uses a provider to supply it with data and apply updates when It caches updates from a database server or another dataset. It represents the data in an XML document. It stores the data in the client portion of a multi-tiered application. For any client dataset other than TClientDataSet, this provider is internal, and so not directly accessible by the application. With TClientDataSet, the provider is an external component that links the client dataset to an external source of data. An external provider component can reside in the same application as the client dataset, or... more
Using a Client Dataset with File-based Data | Client datasets can work with dedicated files on disk as well as server data. This allows them to be used in file-based database applications and "briefcase model" applications. The special files that client datasets use for their data are called MyBase. Tip: All client datasets are appropriate for a briefcase model application, but for a pure MyBase application (one that does not use a provider), it is preferable to use TClientDataSet, because it involves less overhead. In a pure MyBase application, the client application cannot get table definitions and data from the server, and there is no server... more
Using a Simple Dataset | TSimpleDataSet is a special type of client dataset designed for simple two-tiered applications. Like a unidirectional dataset, it can use an SQL connection component to connect to a database server and specify an SQL statement to execute on that server. Like other client datasets, it buffers data in memory to allow full navigation and editing support. TSimpleDataSet works the same way as a generic client dataset (TClientDataSet) that is linked to a unidirectional dataset by a dataset provider. In fact, TSimpleDataSet has its own, internal provider, which it uses to communicate with an internally created unidirectional dataset. Using... more
Using Indexes to Group Data | When you use an index in your client dataset, it automatically imposes a sort order on the records. Because of this order, adjacent records usually contain duplicate values on the fields that make up the index. For example, consider the following fragment from an orders table that is indexed on the SalesRep and Customer fields:
Using Internally Calculated Fields in Client Datasets | In other datasets, your application must compute the value of calculated fields every time the record changes or the user edits any fields in the current record. It does this in an OnCalcFields event handler. While you can still do this, client datasets let you minimize the number of times calculated fields must be recomputed by saving calculated values in the client dataset's data. When calculated values are saved with the client dataset, they must still be recomputed when the user edits the current record, but your application need not recompute values every time the current record changes. To save... more
Using Maintained Aggregates | Client datasets provide support for summarizing data over groups of records. Because these summaries are automatically updated as you edit the data in the dataset, this summarized data is called a "maintained aggregate." In their simplest form, maintained aggregates let you obtain information such as the sum of all values in a column of the client dataset. They are flexible enough, however, to support a variety of summary calculations and to provide subtotals over groups of records defined by a field in an index that supports grouping. The following topics describe how to Specify aggregates. Aggregate Over Groups... more
When to Use TSimpleDataSet | TSimpleDataSet is intended for use in a simple two-tiered database applications and briefcase model applications. It provides an easy-to-set up component for linking to the database server, fetching data, caching updates, and applying them back to the server. It can be used in most two-tiered applications. There are times, however, when it is more appropriate to use TClientDataSet: If you are not using data from a database server (for example, if you are using a dedicated file on disk), then TClientDataSet has the advantage of less overhead. Only TClientDataSet can be used in a multi-tiered database application .... more
Cloning a Client Dataset Cursor | Client datasets use the CloneCursor method to let you work with a second view of the data at runtime. CloneCursor lets a second client dataset share the original client dataset's data. This is less expensive than copying all the original data, but, because the data is shared, the second client dataset can't modify the data without affecting the original client dataset. CloneCursor takes three parameters: Source specifies the client dataset to clone. The last two parameters (Reset and KeepSettings) indicate whether to copy information other than the data. This information includes any filters, the current index, links to... more
Working with Data Using a Client Dataset | Like any dataset, you can use client datasets to supply the data for data-aware controls using a data source component. See Using data controls for information on how to display database information in data-aware controls. Client datasets implement all the properties an methods inherited from TDataSet. For a complete introduction to this generic dataset behavior, see Understanding datasets. In addition, client datasets implement many of the features common to table type datasets such as Sorting records with indexes. Using Indexes to search for records. Limiting records with ranges. Creating master/detail relationships. Controlling read/write access... more
Reconciling Update Errors | There are two events that let you handle errors that occur during the update process: During the update process, the internal provider generates an OnUpdateError event every time it encounters an update that it can't handle. If you correct the problem in an OnUpdateError event handler, then the error does not count toward the maximum number of errors passed to the ApplyUpdates method. This event only occurs for client datasets that use an internal provider. If you are using TClientDataSet, you can use the provider component's OnUpdateError event instead. After the entire update operation is finished, the client dataset... more
Assigning Data Directly | You can use the client dataset's Data property to assign data to a client dataset from another dataset. Data is a data packet in the form of an OleVariant. A data packet can come from another client dataset or from any other dataset by using a provider. Once a data packet is assigned to Data, its contents are displayed automatically in data-aware controls connected to the client dataset by a data source component. When you open a client dataset that represents server data or that uses an external provider component, data packets are automatically assigned to Data. When... more
Loading Data from a File or Stream | To load data from a file, call a client dataset's LoadFromFile method. LoadFromFile takes one parameter, a string that specifies the file from which to read data. The file name can be a fully qualified path name, if appropriate. If you always load the client dataset's data from the same file, you can use the FileName property instead. If FileName names an existing file, the data is automatically loaded when the client dataset is opened. To load data from a stream, call the client dataset's LoadFromStream method. LoadFromStream takes one parameter, a stream object that supplies the data. The data... more
Saving Data to a File or Stream | Even when you have merged changes into the data of a client dataset, this data still exists only in memory. While it persists if you close the client dataset and reopen it in your application, it will disappear when your application shuts down. To make the data permanent, it must be written to disk. Write changes to disk using the SaveToFile method. SaveToFile takes one parameter, a string that specifies the file into which to write data. The file name can be a fully qualified path name, if appropriate. If the file already exists, its current contents are completely overwritten.... more
Using Client Datasets: Overview | Client datasets are specialized datasets that hold all their data in memory. The support for manipulating the data they store in memory is provided by midaslib.dcu or midas.dll. The format client datasets use for storing data is self-contained and easily transported, which allows client datasets to Read from and write to dedicated files on disk, acting as a file-based dataset. Properties and methods supporting this mechanism are described in Using a client dataset with file-based data. Cache updates for data from a database server. Client dataset features that support cached updates are described in Using a client dataset to... more
Limiting What Records Appear | To restrict users to a subset of available data on a temporary basis, applications can use ranges and filters. When you apply a range or a filter, the client dataset does not display all the data in its in-memory cache. Instead, it only displays the data that meets the range or filter conditions. For more information about using filters, see Displaying and editing a subset of data using filters. For more information about ranges, see Limiting records with ranges. With most datasets, filter strings are parsed into SQL commands that are then implemented on the database server. Because... more

Copyright(C) 2009 Embarcadero Technologies, Inc. All Rights Reserved.
What do you think about this topic? Send feedback!