II. STARGRASP Software Command Syntax Notes

A command and argument=value syntax is used throughout the layers of STARGRASP software. This applies to the demo scripts (written in Bourne Shell), the toolkit level commands which can be executed on a "command line" or from your favorite scripting language, and the ASCII socket level interface implemented on the controller. (It does not apply to the C API where the interface is a standard C-Language function call interface.) The following general rules apply:

• Arguments always follow the command.
• Order is not important(*)
• Do not include dashes "-" or "--" in front of the argument.
• Do not include white space around the equal sign ("=")
• Enclose white space in a value with double quotes (or quotes appropriate for the scripting language you are using.)

Examples:

go nexp=3 etype=DARK comment="Some comment string w/ spaces"  GOOD
go 3                                                          Not recommended
go nexp = 3                                                   WRONG!
go nexp=3 etype=DARK comment=Some comment string              WRONG!

Sticky Arguments

Some options are "sticky", or have separate commands that set a default. The effect is the same in either case. If you leave out the option, either the default set with the other command applies, or the last used "sticky" value applies. See the documentation on the various layers of software for details. In many cases, it is best to be explicit and send all relevant options each time, especially from a script. The extra overhead to transmit and process the arguments is not significant.

Examples:

readout dev=0 bpp=16

is equivalent to:

dev 0
readout bpp=16

However, this only works if there happens to be a separate command implemented to set the option default. As a case in point, there is no "bpp" command so

bpp 16              WRONG! (no such command implemented)

---

(*) The only time order is important is when using a shorthand in which only the value is given (i.e., no argument and no =). In this case, the command parser falls back on positional rules. This syntax is not recommended, because the full syntax is more explicit, provides a level of self-documentation in scripts, and is easier to make sense of in network traces.