The Variables tab allows you to define Variables that are required as input to the query or computed from the query’s result set after it has executed. These Variables can be used in Attributed Compliance Test rules or as part of a query’s selection criteria. Any values supplied as input with the query are initialized before the query is executed; the remaining values are calculated just after the Query is processed and the Result Set is generated.

Variables tab illustrates the layout of the variables tab.

Figure 1. Variables tab

The Variables Tab has three columns: the Name, Definition, and Value columns. Name gives the names of the variables that are defined, “devices” in the single variable defined above. Definition gives a textual definition of how to compute the variable, and Value gives the value(s) that were assigned to the variable if the query is previewed. (You do not have to understand the textual Definition of the Variable in order to create a Variable because there are helper screens provided for each type of variable that will create the correct definition.)

Variables are defined using the ”Add” button which invokes a separate pop up menu (corresponding to the devices variable defined above). Variable Definition dialog box illustrates the Variable Definition dialog box.

Figure 2. Variable Definition dialog box

The Name field contains the name of the variable, for example, as shown devices. Variable names start with an alphabetic character and can contain alphabetic, numeric, or the underscore characters; a compound path-like name can be constructed separating each path component with a “.”.

The type pull down selection allows you to choose what type of variable is to be defined:

  • Result set variables specify one or more rows and a column that generate a list of values that are computed from the result set.

  • Literals allow the creation of a list of literal string values.

  • Reference Variable allows selection of a reference variable.

  • Prompt String specifies an input variable to the query, and the corresponding prompt string to be displayed to the user.

  • Expression (Advanced) variables can be used to write Velocity expressions. Their use is beyond the scope of this document.

    The Definition panel changes depending on the type of variable being defined. Shown above is the Result Set definition panel; you can select “All Rows”, a single row by giving the row number, or a set of rows matching a value or a regular expression (or not matching by clicking the “Invert” check-box.) A single column can be selected. After the query is evaluated, a list will be generated consisting of the result set values in the column defined in the Column Selection criteria from each row matching the row selection criteria. In the example above, all rows are selected, and values from the DeviceName column are used to construct the devices variable list. Since there are multiple rows in our result set for the same Device, there are duplicates in the devices variable list.

    Variable Definition dialog box for literals illustrates the definition panel for literals.

    Figure 3. Variable Definition dialog box for literals

    To add literal values, enter them in the “Add Literal” box and clock “Add” or “Insert”. You can insert a variable reference into the literal by choosing the “Insert Variable” button. The variable reference will be inserted at the point of the cursor in the Add Literal box. You can change the ordering of the literals if desired.

    Variable Definition dialog box for prompt string illustrates the dialog box for adding prompt string variables.

    Figure 4. Variable Definition dialog box for prompt string

    If the query is run interactively the prompt string will be provided to the user, and the input received from the user will be used to initialize the variable before the query is evaluated. If a query containing a prompt variable is run in a non interactive situation (such as for a report or in an Attributed Compliance Test), and the variable is not already resolved to a value, an error will occur for a non resolved variable.

    Reference variables are defined by the screens illustrated in Reference variables definition dialog box.

    Figure 5. Reference variables definition dialog box

    When a Reference Variable is declared, the user is prompted to select the variable name from a list of available reference variables. Some reference variables may additionally prompt for required parameters.

    Reference variables can only be evaluated when the proper context has been established. The query processing engine establishes contexts only under the following conditions:

  • When a query is invoked by right clicking a Network under Network Navigation tree and selecting “Queries” and then a Query Name, a network context will be established.

  • When an attributed compliance test is evaluated, both network and device contexts are established for the Device that is being tested.