As mentioned earlier, when the parser encounters a dollar sign it tries to look up the variable in a list. What list? Well, the list of variables that it knows the script needs. This is the same list it would have to present to you to allow you to fill in the values. How does it get this list?

It could be argued that the parser could run through every line of the script and for any references it finds, add them to the list. But there are flaws to this approach.

  • First, if it only had the names of the variables to go on, when it wanted to ask you for the values, it would simply have to use those names. By having variable declarations, you get to put in a nice piece of informative text that only you will see when you generate the report, that makes it clear what the variable you are being asked for will be used for. Without this, you would have to choose names carefully to make sense.
  • Second, what happens if you made a mistake and used the wrong variable name in the script? If it saw a different spelling, it would simply assume it was a different variable and list it. You would be asked for an extra variable! By declaring the variables beforehand, it can spot a miss-spelt variable name and throw it out (by rendering it directly to the output as the variable name with dollar sign).

So we declare the variable in advance, and let the parser know exactly what it should be expecting. To insert a variable declaration you use the Request (User) button on the SYSTEM ribbon panel.

  • Type in the name you want to give your variable (without the dollar sign).
  • Provide the text you want to use as a prompt when entering a value for the variable.

This then inserts a REQUIRES command, as shown in the previous section.

Note IconThe REQUIRES command does not have to come at the top of the script. It will happily work even if it occurs at the end of the script, after you have referenced the variable. The script is actually pre-parsed and so the list is built up before it tries to render anything. It thus already knows what the variables are by the time it tries to render the raw script.

Whenever your script is altered and it contains a variable that has not yet been given a value, the Required Variables panel activates. This is not to annoy you. It is to help make sure you don't forget to fill in values.

Note that in script editor mode, the values you give variables are for testing purposes only, to check if you have written your script correctly. These values are not remembered once you close the script.

When you create a real report from one of your custom scripts, you enter the real values of the variables then, and these are remembered when you save the report (actually, the report output is saved verbatim, so the values of the variables are permanently embedded in the text, having been substituted).