Programmer Guide/Command Reference/DISPATCH

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 ]

The DISPATCH command can be used within a class to dispatch a call to a class, where the 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 this function.

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).

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.