ProcessMasterRecord is only available in the OnBeforeMap event of a dataset.

By calling this function, processing will revert to the parent dataset - the program flow loop is broken and control returned to the next level up.

Normally, this function is used when processing a source definition that is a single dataset of lines needing to be split into a destination definition, that has header and line datasets.

The source dataset probably has a key field that is the same across lines in the same group e.g. if the source is an order line, then each line may have an order number field. Each time the order number changes you will need to create a new record in the destination header dataset.

You would need to configure your Map in the following way;

//LINKEDDATA EVENT OF destination CHILD DATASET ORDER_LINE (source is ORD_LINE)
procedure LinkedDataEvent(var LinkedData:TdaQueryDataView); //ORDER_LINE
begin
LinkedData := ORD_LINE;
end;

Firstly as above, you need to set the LinkedData of the child dataset - this should be set to the source dataset. Essentially you are linking the source lines to the destination lines.

//BEFOREMAP EVENT OF PARENT DATASET
procedure BeforeEvent(var Value:Variant);
begin
Global1 := KeyField.Value;
end;

The above script resides on the BeforeMap event of the parent dataset. It stores the key field's value in a global variable called Global1.

The pre-defined special Statelake variables called Global1 through Global10 (Global1, Global2, Global3, Global4, Global5, Global6, Global7, Global8, Global9, and Global10), are what are known as Globals. They are available across all Maps, and are accessible in any Map. They values they hold carry across to all parts of the current Map.

Please refer to Global Variables for more information.

//BEFOREMAP EVENT OF CHILD DATASET
procedure BeforeEvent(var Value:Variant);
begin
If Global1 <> KeyField.Value then;
begin
ProcessMasterRecord;
Exit; //call Exit to stop this script now and start on the header immediately
end;
end;

The above script resides on the BeforeMap event of the child dataset. Each time a line is processed it checks to see if the key field is still the same value. If it has changed value, you need to call ProcessMasterRecord to start a new header record.

For detail and expanded information about mapping, please refer to Map.

How does this work?

When the mapping first starts, a header record is processed in the destination (remember it is pull-based mapping running off the destination dataset).

The header has no LinkedData, therefore one record will be processed only.

During processing of this record, any reference to source fields will read values from the first record in the source. The current value of the key field is stored in a Global variable for later comparison.

After the header, the system will start to process the child dataset.

Since the LinkedData is set to the source dataset, it will continue processing the lines either until there are no more, or until the ProcessMasterRecord is called (due to change in key field value).

ProcessMasterRecord causes the script engine to start processing the header record again.

This time, any reference to source fields will be reading values from the current record in the source (the first record with the new key field).

Again after the header is processed, it will continue to process the lines.

Declaration: Procedure ProcessMasterRecord : boolean;

A typical example follows.

procedure BeforeEvent(var Value:Variant);
begin
If Global1 <> KeyField.Value then
begin
ProcessMasterRecord;
Exit; //call Exit to stop this script now and start on the header immediately
end;
//otherwise other code here . . .
end;

For a practical demonstration of ProcessMasterRecord, please review Tutorial 6: Import CSV Purchase Orders Into A Database. This tutorial provides a hands-on example of the use of this procedure, and can be reviewed at Tutorial 6: Import CSV Purchase Orders Into A Database.