Data selections

A data selection could be compared to an address. It indicates a location within a data file or database: the job file (see Job file), Metadata file (see Metadata), or Data Repository.
Data selections can be used in many task property fields and are always evaluated at run-time so they are always dynamic and depend on the job file that is currently being processed.
There are several types of data selections you can use, depending on which emulation you are using, whether or not Metadata have been created by a previous task in the process, and whether or not data have been entered in the Data Repository.

Adding a data selection

A data selection can be used in any task property that may contain a variable (see Variable task properties). These properties are recognizable by their colored field label (maroon, by default).
Right-click the property field and choose Get Data Location or Get Metadata Location to open the Data Selector (see The Data Selector) or Get Repository Location to open the Data Repository Manager (see Data Repository Manager).

Note: The Get (...) Value options will also open the Data Selector or the Data Repository Manager, but once selected, the value becomes static and does not change between each data page and job file.

After opening a sample of the data (see Choosing a sample data file) and/or Metadata, you can easily make a selection.
It is also possible to manually enter a data selection, or to change it after making a selection with the mouse pointer.

Data selections can also be used in a PlanetPress Design document that is being merged with the data (for example in a printed output); for more information, see PlanetPress Design User Guide.

Wild card parameter "?"

Data/Metadata selection functions accept a wildcard parameter "?", indicating the function operates on all nodes (not just one) of a given level.

Examples

  • In a PDF emulation, the format of a selected region could be:

    region(?,0.59375,2.21875,1.85416,2.51041,KeepCase,NoTrim)

    In this case “?” represents the current physical data page processed by the task.

  • In the following rule, the Metadata selection function loops through all datapages in a job, comparing their index in the document to a value:

    (GetMeta(SelectedIndexInDocument[0], 11, Job.Group[?].Document[?].Datapage[?]) Equal 0

  • In the following rule, the question mark in the text-based data selection represents the current page number:

    (@(?,1,1,1,9,KeepCase,NoTrim) IS EQUAL TO Page 1 of)

Text-based data selections

Text-based selections are used for text data files such as Line Printer, ASCII and Channel Skip emulations. The selection refers to a rectangular selection that may contain multiple lines, rows, columns on a given page.

Syntax

@(page number, from line, to line, from column, to column, case option, trim option)

Here is a breakdown of the syntax (all options are mandatory):

  • @(): Always surrounds a data selection.

  • Page Number: The data page number from which you want the data selection to grab the data. If you want to get data from each page individually, this has to be done after a splitter.

  • From Line: The starting line of the data selection.

  • To Line: the last line of the data selection.

  • From Column: the leftmost character position of the data selection.

  • To Column: the rightmost character position of the data selection.

  • Case Options: This can be one of three options:

    • KeepCase: Keeps the current uppercase and lowercase letters as they are.

    • UpperCase: Converts all letters to their uppercase equivalent.

    • LowerCase: Converts all letters to their lowercase equivalent.

  • Trim Option: Can either be "Trim" if you want to trim empty spaces before and after the data selection or "NoTrim" if you want to retain the extra spaces.

Database data selections

These selections are used for database-driven data files such as Database and CSV emulations. The selection refers to a specific field on any given data page.

Syntax

field(record set number, child number, field name, treatment of character case, treatment of empty trailing cells)

Here is a breakdown of the syntax (all options are mandatory):

  • field(): Always surrounds database field selections.

  • Record Set Number: The data page (or "record") of the data selection.

  • Child Number: Line Number in the record (if there are multiple lines returned for one single record).

  • Field Name: The name of the field you want to retrieve.

  • Case Option: This can be one of three options:

    • KeepCase: Keeps the current uppercase and lowercase letters as they are.

    • UpperCase: Converts all letters to their uppercase equivalent.

    • LowerCase: Converts all letters to their lowercase equivalent.

  • Trim Option: Can either be "Trim" if you want to trim empty spaces before and after the data selection or "NoTrim" if you want to retain the extra spaces.

Data Repository lookups

The Data Repository selections are made through the lookup function. Selections are done from the data located in the Data Repository Manager. The lookup function returns the value of a single key, which is always a string. If the lookup operation fails to find any data, for any reason, the return value is always "NODATA".

Syntax

lookup(group, return key, lookup key, lookup value)

Here is a breakdown of the syntax (all arguments are mandatory):

  • group: The name of the group in which to retrieve the value. Does not need to be surrounded by quotes.

  • return key: The name of the key where the information you want to retrieve is located. Does not need to be surrounded by quotes.

  • lookup key: The name of the key in the group with which to look up the value. The return key of the KeySet in which the lookup key's value matches the lookup value will be returned.

  • lookup value: A string surrounded by quotes which will be used in the lookup.

The lookup syntax is akin to a SQL SELECT statement and could be loosely translated to:

SELECT [return key] FROM [group] WHERE [lookup key] = [lookup value];

PDF data selections

These selections are used for PDF data files. The selection refers to a specific area of any given page of the PDF by using precise region coordinates (in inches).
Note that when adding a metadata field, if you perform a multi-line data selection on a PDF region, only the first line of that region will be set to the metadata field.

Syntax

region(page, left, top, right, bottom, case option, trim option)

Here is a breakdown of the syntax (all options are mandatory):

  • region(): Always surrounds PDF data selections.

  • Page: The page of the PDF from which to retrieve the data.

  • Left: Exact horizontal position (in inches) that defines the left of the selection region.

  • Top: Exact vertical position (in inches) that defines the top of the selection region.

  • Right: Exact horizontal position (in inches) that defines the right of the selection region.

  • Bottom: Exact vertical position (in inches) that defines the bottom of the selection region.

  • Case Option: This can be one of three options:

    • KeepCase: Keeps the current uppercase and lowercase letters as they are.

    • UpperCase: Converts all letters to their uppercase equivalent.

    • LowerCase: Converts all letters to their lowercase equivalent.

  • Trim Option: Can either be "Trim" if you want to trim empty spaces before and after the data selection or "NoTrim" if you want to retain the extra spaces.

Metadata selections

Metadata selections are used with any type of emulation, as long as a metadata file was created by a previous task in the process.

Tip: To get a sample of the metadata file, debug your process and step through it until the option View Metadata gets enabled. This happens when metadata have been created by a task in the process. Open the metadata viewer and save the metadata file to use it as a metadata sample file in the Data Selector.

Syntax

GetMeta(Field Name [, Option Flags, Metadata Path])

Here is a breakdown of the syntax:

  • GetMeta(): Always surrounds metadata selections.

  • Field/Attribute Name: specifies the name of the field (or attribute, if the GetAttribute option flag is set) to retrieve (see Metadata Attributes and Fields).

  • Option Flag (optional): Sets the options for the selection (see table below).

  • Metadata Path (optional): Defines the precise path where the Metadata Field is located.

    Note: Metadata Index/Count values are zero-based: the first element in any collection has an index of 0 and the last element's index corresponds to the collection's length minus 1.

Option flags

The flag value to enter should be the sum of all desired flags. So, a value of 11, which is 8+2+1, means that behavior 8, 2 and 1 are applied.

A value of 0 means 'no flag'.

Name

Value

Behavior

GetAttribute

1

Search for the name argument in the attribute collection instead of the default field collection. See: Metadata Attributes and Fields.

NoCascade

2

Search only the level specified by the path argument (defaults to Page level when path argument is empty), instead of default behavior, which recursively goes up from the Page level to the Job level.

FailIfNotFound

4

Raise an error and crash the job is the specified name is not found instead of returning an empty string.

SelectedNodesOnly

8

Returns values from selected nodes only (i.e. ignores unselected nodes).

XML data selections

XML data selections are used to retrieve an element's name, value or count from an XML file.

Syntax

xmlget(XPath[, Value option, Case option, Trim option])

Here is a breakdown of the syntax:

  • xmlget(): Always surrounds a data selection.
  • Value Options:
    • Count: The number of elements on the same level in the same node that have the same name.
    • Name: The element's name.
    • Value: The element's value.
  • Case Options: This can be one of three options:
    • KeepCase: Keeps the current uppercase and lowercase characters as they are.
    • LowerCase: Converts all characters to their lowercase equivalent.
    • UpperCase: Converts all characters to their uppercase equivalent.
  • Trim Options: Enter "Trim" if you want to trim empty spaces before and after the data selection or "NoTrim" to retain the extra spaces.