A Command Reference is a reference to a Command Implementation. In other words, a Command Reference refers to (or identifies) a particular Command Implementation. The Command Implementation can be invoked (executed) via the Command Reference. Thus if you do not know the name of a Command Implementation, but you have a reference to it, then you can invoke it.

Command References are very useful when part of a program or module needs to be interchangeable. Instead of invoking a command directly, the program or module can store a Command Reference, and invoke whichever command the Command Reference refers to. The reference can be set to refer to different commands at different times, thus making that part interchangeable.

When invoking a command, a value must be supplied for each parameter of that command. Thus it is impossible to invoke a command if you do not know what parameters it has. A Command Reference is defined to have the same (or compatible) parameters as a specified Command Implementation. The Command Reference can be set to refer to any Command Implementation that has the same (or compatible) parameters as the Command Reference is defined to have.

In the following example, a Command Implementation named "Test" is defined, and it contains a variable that is a nullable reference to a command having the same (or compatible) parameters as "ActionCmd". The variable is initially set to contain a null reference.

Module MyProgram;

Command ActionCmd, Stub;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
EndCommand;

Command Test;
    Variable action, RefN[MyProgram.ActionCmd], Null;
EndCommand;

EndModule MyProgram;

In the above, "RefN[MyProgram.ActionCmd]" means a nullable reference to the command named "MyProgram.ActionCmd" or any command having the same (or compatible) parameters as "MyProgram.ActionCmd".

The command "MyProgram.ActionCmd" has been marked with "Stub" above. This is optional. The "Stub" option means that the Command Implementation contains no commands (other than parameter definitions), and the compiler should use it as a definition but not generate any executable code for it.

"MyProgram.ActionCmd" is not intended to ever be invoked/executed. Rather it exists only to define what parameters the Command Reference should have. In other words, "MyProgram.ActionCmd" is like a template for a real Command Implementation defined elsewhere.

To set a Command Reference variable to refer to a particular Command Implementation, use the "Set" command as in the following example:

Module MyProgram;

Command ActionCmd, Stub;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
EndCommand;

Command FunkyAction;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
    {...}
EndCommand;

Command SpunkyAction;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
    {...}
EndCommand;

Command Test;
    Variable action, RefN[MyProgram.ActionCmd], Null;
    {...}
    Set action, MyProgram.FunkyAction;
    {...}
    Set action, MyProgram.SpunkyAction;
    {...}
EndCommand;

EndModule MyProgram;

To invoke a Command Reference (meaning to invoke the command that the reference refers to), use the command named "Invoke" (shortcut "ivk"). The first parameter of the "Invoke" command must be the Command Reference to invoke. The remaining parameters of the "Invoke" command are passed to the command being invoked.

The following is an example of passing a Command Reference as a parameter, and invoking it:

Module MyProgram;

Command ActionCmd, Stub;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
EndCommand;

Command StdAction;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
    {...do something...}
EndCommand;

Command AltAction;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
    {...do something else...}
EndCommand;

Command PerformOperation;
    Parameter inVal, TUInt;
    Parameter inAction, Ref[MyProgram.ActionCmd];
    {...}
    Invoke inAction, inVal+10, inVal+20;
    {...}
EndCommand;

Command Test;
    Parameter inX, TUInt;
    If inX == 1;
        MyProgram.PerformOperation 1000, MyProgram.StdAction;
    ElseIf inX == 2;
        MyProgram.PerformOperation 1000, MyProgram.AltAction;
    EndIf;
EndCommand;

EndModule MyProgram;

A Function Reference is the same as a Command Reference except that it refers to a Function Implementation instead of a Command Implementation.

To invoke a Function Reference, use the function named "Invoke". "Invoke" is the name of a command and also the name of a function. Use the command "Invoke" to invoke Command References, and use the function "Invoke" to invoke Function References.

The return value of the "Invoke" function is the return value of the function being invoked via reference.

In the following example, the function named "MyProgram.StdAction" is invoked via a Function Reference:

Module MyProgram;

Function ActionFunc, TUInt, Stub;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
EndFunction;

Function StdAction, TUInt;
    Parameter inA, TUInt;
    Parameter inB, TUInt;
    Return inA + inB;
EndFunction;

Command PerformOperation;
    Parameter inVal, TUInt;
    Parameter inAction, Ref[MyProgram.ActionFunc];
    {...}
    Variable x, TUInt;
    Set x, 250 + Invoke[inAction, inVal+10, inVal+20];
    {...}
EndCommand;

Command Test;
    Parameter inPerform, TBoolean;
    If inPerform;
        MyProgram.PerformOperation 1000, MyProgram.StdAction;
    EndIf;
EndCommand;

EndModule MyProgram;