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
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:
- If the command fails, it reports a warning instead of an error.
Xinstead of the default label prefix "
- Store the command word (less the prefix) in a variable called
Yinstead of "
- 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.
- Use this option if your class is being supplied with READ-style instead of ARG-style options (the latter is the default).
- Normally, the
DISPATCHcommand will simply jump to the respective label. Now, if you supply the
/Calloption, 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
EXITstatement, it will resume with the statement following the
READ-style parsing, i.e. when supplying the "/Read" option, there are the following additional options:
- 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.
- 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
READfamily of commands (see there).
- If you supply this option, the command will store the arguments (less the command argument!) to the variable
See the script
dispatch_example.sts for an example of usage.