Name 

Description 

Responding to Client Update Requests 

A provider applies updates to database records based on a Delta data packet received from a client dataset or XML broker. The client requests updates by calling the ApplyUpdates method (indirectly, through the IAppServer interface).
As with all method calls made through the IAppServer interface, the provider can communicate persistent state information with a client dataset before and after the call to ApplyUpdates. This communication takes place using the BeforeApplyUpdates and AfterApplyUpdates event handlers.
If you are using a dataset provider, a number of additional events allow you more control:
When a dataset provider receives an update request, it... more 

Adding Custom Information to Data Packets 

Dataset providers can add application-defined information to data packets using the OnGetDataSetProperties event. This information is encoded as an OleVariant, and stored under a name you specify. Client datasets can then retrieve the information using their GetOptionalParam method. You can also specify that the information be included in delta packets that the client dataset sends when updating records. In this case, the client dataset may never be aware of the information, but the provider can send a round-trip message to itself.
When adding custom information in the OnGetDataSetProperties event, each individual attribute (sometimes called an "optional parameter") is specified using... more 

Applying Updates to Datasets That do Not Represent a Single Table 

When a dataset provider generates SQL statements that apply updates directly to a database server, it needs the name of the database table that contains the records. This can be handled automatically for many datasets such as table type datasets or "live" TQuery components. Automatic updates are a problem however, if the provider must apply updates to the data underlying a stored procedure with a result set or a multi-table query. There is no easy way to obtain the name of the table to which updates should be applied.
If the query or stored procedure is a BDE-enabled dataset (... more 

Choosing How to Apply Updates Using a Dataset Provider 

TXMLTransformProvider components always apply updates to the associated XML document. When using TDataSetProvider, however, you can choose how updates are applied. By default, when TDataSetProvider components apply updates and resolve update errors, they communicate directly with the database server using dynamically generated SQL statements. This approach has the advantage that your server application does not need to merge updates twice (first to the dataset, and then to the remote server).
However, you may not always want to take this approach. For example, you may want to use some of the events on the dataset component. Alternately, the dataset you... more 

Communicating with the Client Dataset 

All communication between a provider and a client dataset or XML broker takes place through an IAppServer interface. If the provider is in the same application as the client, this interface is implemented by a hidden object generated automatically for you, or by a TLocalConnection component. If the provider is part of a multi-tiered application, this is the interface for the application server's remote data module or (in the case of a SOAP server) an interface generated by the connection component.
Most applications do not use IAppServer directly, but invoke it indirectly through the properties and methods of the client... more 

Controlling What Information Is Included in Data Packets 

When working with a dataset provider, there are a number of ways to control what information is included in data packets that are sent to and from the client. These include

• Specifying what fields appear in data packets
• Setting options that influence the data packets
• Adding custom information to data packets

 

Determining the Source of Data 

When you use a provider component, you must specify the source it uses to get the data it assembles into data packets. Depending on your version of Delphi, you can specify the source as one of the following:

• To provide the data from a dataset, use TDataSetProvider.
• To provide the data from an XML document, use TXMLTransformProvider.

 

Editing Delta Packets Before Updating the Database 

Before a dataset provider applies updates to the database, it generates an OnUpdateData event. The OnUpdateData event handler receives a copy of the Delta packet as a parameter. This is a client dataset.
In the OnUpdateData event handler, you can use any of the properties and methods of the client dataset to edit the Delta packet before it is written to the dataset. One particularly useful property is the UpdateStatus property. UpdateStatus indicates what type of modification the current record in the delta packet represents. It can have any of the values in the following table:
UpdateStatus values  

Handling Server Constraints 

Most relational database management systems implement constraints on their tables to enforce data integrity. A constraint is a rule that governs data values in tables and columns, or that governs data relationships across columns in different tables. For example, most SQL-92 compliant relational databases support the following constraints:

• NOT NULL, to guarantee that a value supplied to a column has a value.
• NOT NULL UNIQUE, to guarantee that column value has a value and does not duplicate any other value already in that column for another record.
• CHECK, to guarantee that a value supplied to a column falls within a... more 

Influencing How Updates Are Applied 

The OnUpdateData event gives your dataset provider a chance to indicate how records in the delta packet are applied to the database.
By default, changes in the delta packet are written to the database using automatically generated SQL UPDATE, INSERT, or DELETE statements such as  

Resolving Update Errors On the Provider 

When an error condition arises as the dataset provider tries to post a record in the delta packet, an OnUpdateError event occurs. If the provider can't resolve an update error, it temporarily stores a copy of the offending record. When record processing is complete, the provider returns a count of the errors it encountered, and copies the unresolved records into a results data packet that it passes back to the client for further reconciliation.
In multi-tiered applications, this mechanism lets you handle any update errors you can resolve mechanically on the application server, while still allowing user interaction on the... more 

Responding to Client Data Requests 

Usually client requests for data are handled automatically. A client dataset or XML broker requests a data packet by calling GetRecords (indirectly, through the IAppServer interface). The provider responds automatically by fetching data from the associated dataset or XML document, creating a data packet, and sending the packet to the client.
The provider has the option of editing data after it has been assembled into a data packet but before the packet is sent to the client. For example, you might want to remove records from the packet based on some criterion (such as the user's level of access), or,... more 

Responding to Client-generated Events 

Provider components implement a general-purpose event that lets you create your own calls from client datasets directly to the provider. This is the OnDataRequest event.
OnDataRequest is not part of the normal functioning of the provider. It is simply a hook to allow your client datasets to communicate directly with providers. The event handler takes an OleVariant as an input parameter and returns an OleVariant. By using OleVariants, the interface is sufficiently general to accommodate almost any information you want to pass to or from the provider.
To generate an OnDataRequest event, the client application calls the DataRequest method... more 

Screening Individual Updates 

Immediately before each update is applied, a dataset provider receives a BeforeUpdateRecord event. You can use this event to edit records before they are applied, similar to the way you can use the OnUpdateData event to edit entire delta packets. For example, the provider does not compare BLOB fields (such as memos) when checking for update conflicts. If you want to check for update errors involving BLOB fields, you can use the BeforeUpdateRecord event.
In addition, you can use this event to apply updates yourself or to screen and reject updates. The BeforeUpdateRecord event handler lets you signal that... more 

Setting Options That Influence the Data Packets 

The Options property of a dataset provider lets you specify when BLOBs or nested detail tables are sent, whether field display properties are included, what type of updates are allowed, and so on. The following table lists the possible values that can be included in Options.
Provider options  

Specifying What Fields Appear in Data Packets 

When using a dataset provider, you can control what fields are included in data packets by creating persistent fields on the dataset that the provider uses to build data packets. The provider then includes only these fields. Fields whose values are generated dynamically by the source dataset (such as calculated fields or lookup fields) can be included, but appear to client datasets on the receiving end as static read-only fields.
If the client dataset will be editing the data and applying updates, you must include enough fields so that there are no duplicate records in the data packet. Otherwise, when... more 

Using Provider Components 

Provider components (TDataSetProvider and TXMLTransformProvider) supply the most common mechanism by which client datasets obtain their data. Providers

• Receive data requests from a client dataset (or XML broker), fetch the requested data, package the data into a transportable data packet, and return the data to the client dataset (or XML broker). This activity is called "providing."
• Receive updated data from a client dataset (or XML broker), apply updates to the database server, source dataset, or source XML document, and log any updates that cannot be applied, returning unresolved updates to the client dataset for further reconciliation. This activity is... more