Requesting Data from the Source Dataset or Document
Go Up to Using a Client Dataset with a Provider
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.
Incremental fetching
By changing the PacketRecords property, you can specify that the client dataset fetches data in smaller chunks. PacketRecords specifies either how many records to fetch at a time, or the type of records to return. By default, PacketRecords is set to -1, which means that all available records are fetched at once, either when the client dataset is first opened, or when the application explicitly calls GetNextPacket. When PacketRecords is -1, then after the client dataset first fetches data, it never needs to fetch more data because it already has all available records.
To fetch records in small batches, set PacketRecords to the number of records to fetch. For example, the following statement sets the size of each data packet to ten records:
ClientDataSet1.PacketRecords := 10;
ClientDataSet1->PacketRecords = 10;
This process of fetching records in batches is called "incremental fetching". Client datasets use incremental fetching when PacketRecords is greater than zero.
To fetch each batch of records, the client dataset calls GetNextPacket. Newly fetched packets are appended to the end of the data already in the client dataset. GetNextPacket returns the number of records it fetches. If the return value is the same as PacketRecords, the end of available records was not encountered. If the return value is greater than 0 but less than PacketRecords, the last record was reached during the fetch operation. If GetNextPacket returns 0, then there are no more records to fetch.
Warning: Incremental fetching does not work if you are fetching data from a remote provider on a stateless application server. See Supporting state information in remote data modules for information on how to use incremental fetching with stateless remote data modules.
Note: You can also use PacketRecords to fetch metadata information about the source dataset. To retrieve metadata information, set PacketRecords to 0.
Fetch-on-demand
Automatic fetching of records is controlled by the FetchOnDemand property. When FetchOnDemand is True (the default), the client dataset automatically fetches records as needed. To prevent automatic fetching of records, set FetchOnDemand to False. When FetchOnDemand is False, the application must explicitly call GetNextPacket to fetch records.
For example, Applications that need to represent extremely large read-only datasets can turn off FetchOnDemand to ensure that the client datasets do not try to load more data than can fit into memory. Between fetches, the client dataset frees its cache using the EmptyDataSet method. This approach, however, does not work well when the client must post updates to the server.
The provider controls whether the records in data packets include BLOB data and nested detail datasets. If the provider excludes this information from records, the FetchOnDemand property causes the client dataset to automatically fetch BLOB data and detail datasets on an as-needed basis. If FetchOnDemand is False, and the provider does not include BLOB data and detail datasets with records, you must explicitly call the FetchBlobs or FetchDetails method to retrieve this information.