Products Download Order Support Company

Data Access | DataPipeline Component

In ReportBuilder, data access is provided via the DataPipeline component.

 
ReportBuilder includes data pipelines for accessing data from a variety of sources:

Pipeline

Description

DBPipeline Used for accessing data via the BDE, third-party BDE replacement products, or TDataSet descendants. The DBPipeline is connected via the DataSource property.
TextPipeline Used to access data in text files.
JITPipeline Just-In-Time pipeline for accessing data in Delphi objects.

Regardless of the type of pipeline or the type of data being accessed, the data pipeline component has two basic purposes:

1. Supply data
2. Control data traversal

Supplying Data
Data pipelines provide data via field objects. For instance, the following code would retrieve the current field value of a field called ‘Company’:

lValue := DataPipeline1.Fields[‘Company’].Value;

Each time a data-aware report component prints, it uses this approach to retrieve the data from the data pipeline. Data-aware report components have two properties that determine the data they will retrieve: DataPipeline and DataField. The name of the appropriate data pipeline component is assigned to the DataPipeline. The DataField property is assigned the name of the field that contains the data to be displayed. Once these two properties are assigned, the data-aware component has the ability to retrieve data directly from the data pipeline, independent of the report where the data-aware component resides.

Controlling Data Traversal
The second purpose of the data pipeline is to control data traversal. Data traversal is the act of moving from the first record of the data to the last record. When a report is printed, the report engine traverses the data by doing the following steps:

1. Opens the data pipeline.
2. Goes to the first record.
3. Begins printing the page and then gives the detail band the opportunity to print.
4. Goes to the next record.
5. Gives the detail band the opportunity to print.
6. Continues steps 4 and 5 until there is no more page space.
7. Completes the page.
8. Continues steps 4 through 7 until all records have been exhausted.

It is important to note that when the detail band is given the opportunity to print, the data-aware components within the detail band are rendered – at which point they retrieve the field value of the current record. The engine then moves to the next record and prints the detail band again. It is this combination of the report traversing the data and the data-aware components retrieving the data that creates the pages of the report. If the data pipeline is not assigned to either of these entities (data-aware component or report), then the report will not work. Therefore, the report must be assigned to a data pipeline and each data-aware component must be assigned to a datapipeline and a datafield.

We’ve said that the report engine traverses the data. That isn’t completely true. The report engine makes requests of the data pipeline (such as open, first, next, last), and then relies on the data pipeline to do the work. This means that the data pipeline controls the data traversal. This control can be used to great advantage.

For instance, let’s say you are displaying a database grid on a form. The user has selected an individual record of the grid and wants to print that record. If you have a datapipeline pointed at the same dataset as the grid, then it can access all of the records. However, we can instruct the data pipeline to traverse only the current record by simply setting the RangeBegin and RangeEnd properties to CurrentRecord. When the report prints, it will send traversal requests to the data pipeline, and the data pipeline will traverse only one record. It will then inform the report engine that all records have been traversed and the report will print only one record.

Let’s take this example further and say that you let the user select multiple records from the database grid. You then want the report to contain only the selected records. In this case we can assign the Bookmarks from the grid to the BookmarkList property of the data pipeline. When the report prints, the data pipeline will traverse only those records in the list of bookmarks and only those records will appear in the report. Essentially, the engine makes the same traversal requests of the data pipeline for every report, but the data pipeline controls how the data is actually traversed.