The following example uses a function and subroutine written in VBScript. As this example illustrates, you can use the ByRef keyword within subroutines to pass variables whose values may be altered by the subroutine. You can use functions to return a single value. Do not use the ByRef keyword to pass variables to functions; this does not cause any syntax violations, but modified values of variables passed by reference to functions are not returned to the calling formula in the variable table. VBScript only supports Variant data types.
The definitions of the function and subroutine in this example are stored in a document called FUNCTIONS.BAS. To see the syntax of the function and subroutine, click the Function button.
In FUNCTIONS.BAS, the function AddTwo takes two numbers as input, adds them, and outputs a single value. A function can take any number of arguments as input, but can only output a single value. When using a function as the formula of a variable, the result of the function is the value of the variable. The input to the function can be specific value or other variables.
The subroutine Normalize takes three values as input and outputs three values. Values are specified to be input by using the ByVal keyword. This specifies that you are passing only the value and it cannot be changed by the subroutine. Output variables need to be specified by using the ByRef keyword. Using ByRef specifies that the variable is being passed in as reference and can be modified by the subroutine. If you do not specify a keyword, ByRef is assumed. Since a subroutine can have multiple output values, it can be used as the formula for several variables.
To use the document FUNCTIONS.BAS in a Variable Table:
Choose Tools tab→Variables group→ Variables.
In the Variable Table, in the Unit Type list, select Distance.
In appropriate cells, type the following entries to create three input variables.
|
Type |
Name |
Value |
Formula |
|
Var |
Var1 |
5.50 in |
|
|
Var |
Var2 |
3.25 in |
|
|
Var |
Var3 |
7.80 in |
In appropriate cells, type three more entries to create three output variables with any value: X, Y, and Z.
|
Type |
Name |
Value |
Formula |
|
Var |
Var1 |
50 in |
|
|
Var |
Var2 |
3.25 in |
|
|
Var |
Var3 |
7.80 in |
|
|
Var |
X |
0.00 in |
|
|
Var |
Y |
0.00 in |
|
|
Var |
Z |
0.00 in |
Select any of the output variables (X, Y, or Z) and click the Fx button to start the Function Wizard.
On the Function Wizard - Step 1 of 2 dialog box, in the Function Category list, select User Defined.
On the Open File dialog box, select the functions.bas document to open it.
On the Function Wizard - Step 1 of 2 dialog box, in the Function Category box, click Visual Basic. In the Function Name box, click Functions.Normalize to select the function that you want to use from the functions.bas document.
Click Next.
On the Function Wizard - Step 2 of 2 dialog box, type the entries shown to specify the value or variable that is to be used as input for each input argument and the variable to be used for each output argument.
|
In this box |
Type this |
|
ByVal InX |
Var1 |
|
ByVal InY |
Var2 |
|
ByVal InZ |
Var3 |
|
ByRef OutX |
X |
|
ByRef OutY |
Y |
|
ByRef OutZ |
Z |
Click Finish.
The result within the Variable Table is shown below. The function is assigned as the formula to all of the variables that were specified to be output of the function. If any of the input values (Var1, Var2, or Var3) change, the function is automatically run and the output variables are updated.
|
Type |
Name |
Value |
Formula |
|
Var |
Var1 |
5.50 in |
|
|
Var |
Var2 |
3.25 |
|
|
Var |
Var3 |
7.80 |
|
|
Var |
X |
0.55 |
Functions.Normalize(Var1,Var2,Var3,X,Y,Z) |
|
Var |
Y |
0.32 |
Functions.Normalize(Var1,Var2,Var3,X,Y,Z) |
|
Var |
Z |
0.77 |
Functions.Normalize(Var1,Var2,Var3,X,Y,Z) |