Open topic with navigation

Forcing References

When BarTender determines the best time to run your scripts during a print job and which database fields it needs to access, it examines the structure of your templates and performs a test run of your scripts. Among other factors, BarTender considers when and how any database fields and shared data sources are used.

Conditional statements run different "branches" of code, depending on how a conditional expression is evaluated. Accordingly, depending on the conditions at the time of the evaluation, some code might not be run. This can cause a problem if a reference to a field or share name happens to be contained in code that is skipped during the test run of its scripts. If the associated conditional statement evaluates differently at print time and causes the field or share name to be referenced, and if it was not referenced during the previous test run, the script might not run at the most efficient time and might even fail.

In these cases, you can use forcing functions to make sure that the script references the database field or data source name that you want.

BarTender's Built-in Forcing Functions

The Script Editor includes two functions that force a script to reference a database field or data source name: ReferenceField and ReferenceSharedSubString. These functions do not change or assign any values; they only force the application to notice the presence of an item that could be missed during the test run of a script. When you use these functions, BarTender establishes links to all of the necessary data fields, and your scripts are run in response to the appropriate events at print time.

A VBScript object that has the field number "<Empty>" might display error message #3201: "An object on the template was set to read in the field '(field name)'. However, this field was not found. Proceed with unknown field as blank string?" Click Yes to show the specified blank string field in the template preview. Click No to add content to the empty field.

ClosedTo find the two forcing functions in the Script Editor

  1. In the Script Assistant pane, expand the Functions folder.

  2. In the Functions folder, expand the Declarations folder. ReferenceField and ReferenceSharedSubstring reside in this folder.

We recommend that you insert the reference functions at the start of your script before any conditional statements.

The ReferenceField function is available only if your template is connected to a database.

The ReferenceSharedSubString function is available only if a named data source is linked to an object on your template.

Forcing Reference to a Database Field or a Named Data Source

You can force a VBScript to reference a database field or named data source.

ClosedTo force reference to a database field

  1. In the Script Assistant pane, expand Functions, expand Declarations, and then expand ReferenceField.

  2. Double-click the name of the database field that you want to force. A code snippet that resembles the following appears in the Script pane:

    ReferenceField("field_name_or_field_number")

If the document is configured to read data from a regular text file, specify a field number. When the document reads from a database, specify a field name. Unless the field name itself is contained in a variable, be sure to enclose the name in quotation marks, such as ReferenceField("price").

ClosedTo force reference to a named data source

  1. In the Script Assistant pane, expand Functions, expand Declarations, and then expand ReferenceSharedSubString.

  2. Double-click the named data source that you want to force. A code snippet that resembles the following appears in the Script pane:

    ReferenceSharedSubString("share_name")

If any data sources in the template have a name, you can force reference to them as shown. Unless the data source name itself is contained in a variable, be sure to enclose the name in quotation marks, such as ReferenceSharedSubString("price").

Related Topics