Two Special Events

The script associated with the Functions and Subs event list item isn’t really an event script at all. It is a script into which you place functions and subroutines that you want to be accessible to all the other event scripts associated with the same data source. You can also use the Functions and Subs script to declare variables that other event control scripts need to access. (These are not quite "global" variables, as they can only be accessed by event control scripts for the same data source, and not by other scripts associated with other data sources.) Below is a list of tasks often performed and items often placed in the Functions and Subs script:

• User-Defined Functions and Subroutines. It is standard programming practice to place a section of computer code that needs to be run from multiple places into either a function or a subroutine. Placing them into the Functions and Subs script lets them be called multiple times from multiple scripts.

• Common Variables. To declare variables that will be accessible to all your event control scripts for a given data source, you can "dimension" them (using the Visual Basic "dim" statement) in the Functions and Subs script. Alternatively, you can simply initialize variables and they will be automatically dimensioned for you. (We use the term "common variables" and not "global variables," because they can only be accessed by event control scripts associated with the same data source. For more information, refer to Defining and Using Global Variables.)

• Variable Initialization. Variables can be set to a starting value by inserting a line of Visual Basic code similar to

  VariableName = value

  into the Functions and Subs script. Here, "VariableName" is the name of the variable to initialize and "value" is the value to initialize it to. Initialization in this manner lets you dispense with the previously mentioned dimensioning of variables, since Visual Basic will determine what variables are not yet dimensioned and do it for you automatically.

• Any Other Initialization. Any other code you need to run in order to set anything up that any of your other scripts might need, such as opening or creating a log file, or perhaps checking for the preexistence of a file. Depending on your needs and/or preference, this code can be placed inside a function or subroutine in the Functions and Subs Script, or simply left as "naked" code and inserted as is into script.

When the Type of Visual Basic Script is set to Event Control Scripts, this event is called with the same frequency that scripts are called when the Type is set to Multi-Line Script.

When using regular multi-line scripts, BarTender analyzes the design of both your script and template(s) according to some preset rules and determines the ideal times for the script to get called. The general goal is to evaluate how your document has its serialization opportunities and copies options set, and then call the multiple-line script often enough to supply the document with new data as needed, but no more often than necessary. In contrast, when the Type of Visual Basic Script is set to Event Control Scripts, you can explicitly specify which events you want to launch your scripts. The OnAutoSelectedEvent lets you write a script that gets called at those "ideal" times determined by BarTender with regular multi-line scripts, even though you may also be using other scripts tied to specific events.