Data references

A data reference is a reference to data in a data source. Once you run a merge, it will be replaced with the current data from the data source.

In its simplest form, it consists of 2 parts:

The data source name
A query

These parts are separated by a : (colon).

Example 1:

$[customers:name]

This data reference refers to the column name in a data source named customers. In this case, the query part is a column name.

This only works for non-XML data sources. For XML based data sources, the query part is an XPath expression.

Example 2:

$[authors:name/@name]

This data reference will return the name attribute of the name element in the current node set of a (XML) data source named authors.

Data references that cannot be resolved result in an error.

Using a sub-string

If you want to use only a small part of the value resulting from a data reference, you can use the inline sub-string operator.

The sub-string operator directly follows the query. It consists of two number surrounded by '(' and ')' and separated by a comma ','. The first number indicates the start index in the value. The second number indicates the length of the sub-string. The start index starts at zero (0).

Example 3:

$[customer:name(2,1)]

This examples takes a sub-string of the name column. The sub-string is 1 character long and starts at the third character of the name (index 2).

If the name was originally "Theo", this example will return "e".

If the length of the sub-string is greater that what is available, an empty string is returned.

Data formatting

Data references can be formatted according to an inline format specifier.

The inline format specifier is separated from the query by a | (vertical bar).

Example 4:

$[customers:name|Upper]

This data refers to the column name in a data source called customers. The resulting data is converted to upper case.

Data type conversion

The type of the current data to which a data reference evaluates depends on the data source. Typically a number column results in number values, but in some cases there is a need to convert from one data type to another. A typical example is an XML data source. All values from an XML data source will be of the type string. If you have a number in your XML data that you want to calculate with, it is necessary to convert that data to a number first.

Data references can be converted to a specific type using an inline data conversion.

The inline conversion surrounds the data source name and the query like this:

$[CInt(data source name:query)]

Where CInt is one of the possible conversions. In this case the data is converted to a 32-bit signed integer.

It is also possible to combine inline conversion and inline formatting in one data reference like this:

$[CDbl(order:price)|#.##0]

In this example the value of the price column from the order data source is first converted to a 64-bit floating point number and then formatted using the #.##0 format specifier.