Forcing References

In order for BarTender to determine the best time to run your scripts during a print job and which database fields it will need to access, it examines the structure of your template and does a test run of your scripts. Among other factors, BarTender considers when and how any database fields and data source names are used. It is possible for you to force a database field or shared named data sources to be evaluated first.

Conditional statements execute different "branches" of code, depending on how a conditional expression is evaluated. Accordingly, some code may not be executed, depending on the conditions at the time of the evaluation. This can cause a problem if a reference to a field or share name happens to be in code that gets 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 may not run at the most efficient time and may even fail.

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 don't change or assign any values. They simply force the application to notice the presence of an item that could be missed during the test run of a script. This ensures that BarTender will establish links to all of the necessary data fields and that your scripts will be executed in response to the appropriate events at print time.

In BarTender 2016, a VBScript object with field number, "<Empty>" will show 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?" Select Yes to show the specified blank string field in the template preview. Select 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 book.

  2. Under Functions, expand the Declarations book. There you will see two sub-books, ReferenceField and ReferenceSharedSubstring.

The reference functions are best inserted into the beginning of your script before any conditional statements.

The ReferenceField sub-book will be available only if your template is connected to a database.

The ReferenceSharedSubString sub-book will be available only if you have a Named Data Source 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, open Functions > Declarations > ReferenceField.

  2. Double-click the name of the data file field you wish to force. A code snippet will appear in the Script pane:


If the document is set up to read data from a regular text file, you will specify a field number. When reading from a database, you will specify a field name. Unless the field name itself is contained in a variable, be sure to put the name in quotes, such as ReferenceField("price").

ClosedTo force reference to a Named Data Source

  1. In the Script Assistant pane, open Functions > Declarations > ReferenceSharedSubString.

  2. Double-click the named data source you wish to force. A code snippet will appear in the Script pane:


If you have given any data sources in the template a name, you can force reference to them as shown above. (Unless the data source name is stored in a variable, enclose the name in quotation marks.)

Related Topics