Create a new command.

Arguments:

name

The name to give the function.

/flags

Zero or more flag names, each one preceded by a '/' character. These appear as boolean variables inside the command. If the user calls the command with these flags, the corresponding boolean variables are assigned the value "true". Otherwise they have the value "false". See below for an example.

type name

The datatype and name of an argument of the command.

[type name,...]

The datatypes and names of any optional arguments. Such arguments can only be used to give values to the optional arguments of other commands (ie. ultimately to the optional arguments of builtin commands). See below for an example.

Example:

The following example creates a command that, when invoked, delays the execution of the script for a given interval. It then shows how one would call it to delay script execution for 10 minutes.

 command delay(Interval dt) {
   until $elapsed >= $dt
 }

 delay 10m

Example of using flags:

The following is an example of the definition of a command with flags.

 command track_source/wait/warn(Source src) {
 
   # If the source is currently below the horizon, and the
   # caller has asked to be told about this, output a warning.
 
   if($warn & $el($src) < 0.0) {
     print "Source ", $src, " is currently below the horizon."
   }
 
   # Tell the control system to track the source.
 
   track $src
 
   # If the caller wants us to wait until the source is acquired before
   # returning, do so here.
 
   if($wait) {
     until $acquired(source)
   }
 }

This command can then be called like:

  track_source/warn mars

in which case $warn would be true and $wait would be false, or

  track_source/warn/wait moon

to make both $warn and $wait true, or

  track_source mercury

to make both $warn and $wait false.

Example of using optional arguments:

The following is an example of the definition of a command that has optional arguments.

  command offset_track(Source src, [PointingOffset az, PointingOffset el,
		       PointingOffset dk]) {
    offset az=$az, el=$el, dk=$dk
    track $src
  }

This command has one mandatory argument, followed by 3 optional arguments. The optional arguments are passed to the builtin "offset" command, where only the arguments that are presented to the offset_track command actually become arguments of the offset command. To be more precise, if the optional $az argument is omitted when calling offset_track, the corresponding optional $az argument of the offset command will be assigned a nul value. For example:

 offset_track moon, az=0:0:5, el=0:0:10

would result in the offset command installing new tracking offsets for azimuth and elevation, but would leave the deck angle offset unchanged.

Context:

Once a new command has been defined like this it can be used exactly as though it were a builtin command.