Programmer Guide/Command Reference/DISPATCH

The DISPATCH command, well, dispatches a call to a class, i.e. a call where a class is being called like a macro. In this case, the DISPATCH command regards the first argument supplied to the class call as a function to invoke (see below), and the remaining arguments as arguments to these functions.

DISPATCH function argList [/Call] [/Silent] [/Prefix=X] [/To=Y] [/Fail=Z]

DISPATCH function argList [/Call] [/Silent] [/Prefix=X] [/To=Y] [/Fail=Z]
                          /Read [ /Var=A /Delim=C /Args=D ]

By default, the function to be invoked is a label whose name is built up from the static prefix Cmd and the first argument supplied to the class call. If, for example, there is a class called Example, and you invoke it with the statement Example test one two three, the DISPATCH command will jump to the label called Cmdtest, supplying it with the arguments one, two, and three, respectively.

Additionally, the DISPATCH command will store the command (less the prefix "cmd") in the local variable #cmd. The command argument itself will be removed from the argument list. So the label the DISPATCH command jumps to will only see any further arguments, not the command itself.

By default, the DISPATCH command will parse the arguments supplied to the class in the ARG style. If you prefer READ style, you may ask for it by supplying the /Read option. In this case, you may also choose a delimiter character and several other options (see below).

You may influence all these parameters by either supplying arguments or options to the DISPATCH commands. There are the following options:

/Silent

If the command fails, it reports a warning instead of an error.

/Prefix=X

Use X instead of the default label prefix "cmd".

/To=Y

Store the command word (less the prefix) in a variable called Y instead of "#cmd".

/Fail=Z

If there is no appropriate label to jump to, the command will jump to label Z. If you don't supply the "/Fail=" option, trying to jump to a non-existent label will lead to a run-time error.

/Read

Use this option if your class is being supplied with READ-style instead of ARG-style options (the latter is the default).

/Call

Normally, the DISPATCH command will simply jump to the respective label. Now, if you supply the /Call option, instead of jumping (the GOTO way), the command will call the respective label (the GOSUB way). In this case, as soon as the control flow reaches an appropriate EXIT statement, it will resume with the statement following the DISPATCH /Call command.

When using READ-style parsing, i.e. when supplying the "/Read" option, there are the following additional options:

/Var=A

If you supply this option, the command will read from a variable called A. By default, it will read from #argv, i.e. from the argument list supplied to the called class.

/Delim=C

If supplied, the command will parse arguments separated by the delimiter character C (which actually must be a character). This is equivalent to the delimiter character supplied to the READ family of commands (see there).

/Args=D

If you supply this option, the command will store the arguments (less the command argument!) to the variable D.

/C

Select the style of call to be used. If not specified, a GOTO command is used to jump to the command/default label. If /C is specified, a GOSUB command is used to call the command/default subroutine.

See the script dispatch_example.sts for an example of usage.