3. General Commands

This document describes commands which can be typed in the ``director'' shell window (identified by its white-on-blue ``status bar.'') Some of these commands may be available in other contexts, but others may not. To be sure, enter these commands in the ``director'' window itself. From other shells (such as bash, or tcsh) send them to director with the help of the ``clicmd'' utility. For example:

bash$ clicmd go          # Look for the feedback in the director window.
> go                     # Typed at the director window itself.

Graphical user interface components may send these same commands, tied to button presses or menu selections. There are many possibilities, but typically they result in invoking the ``clicmd'' program, or making a call to the ``clicmd("command...")'' C-language interface.

When a graphical interface action results in a command being sent to the director shell window, the command and its feedback are echoed there, just as if the user had typed in the command.

3.1 help

This displays a summary of the commands available in the director shell window. If no specific ``help'' script has been installed (which may be done to document additional instrument-specific commands) then the ``help'' command will go directly to ``detcom'' and display only the detector control commands. Here is an example of the output:

*---[ Detector/Instrument Setup Commands ]-----------------------------------*
defaults           : Reset filename, etime, etype, and raster settings
mef on|off         : Save multi-extension (on) or separate FITS files (off)
header <c> <val>   : Set keyword `<c>' (comment,observer,object) to `<val>'
nheader <args>     : Set any keyword; <args>=`index CARDNAME value comment'
filter <name>      : Moves a new filter into beam
raster <rspec>     : <rspec>=`xc yc xs ys [xb yb]' (See `raster help')
etype <type>       : Select <type>=OBJECT, BIAS, DARK, FLAT
etime <sec>        : Set exposure time; <sec> can be a floating point number
*---[ Starting and Stopping Exposures ]--------------------------------------*
go [n]             : Start (n) exposure(s) with current etime and etype
stop               : Shorten an exposure (close shutter and readout now)
break              : Complete current exposure, then break out of sequence
abort              : Use with caution, and only when all else fails!
*---[ Other Commands ]-------------------------------------------------------*
cd [<directory>]   : Change/Show current working directory for images
ls [<files>]       : List files in the current working directory
say <message>      : Broadcast a message to other users on-line
*----------------------------------------------------------------------------*

In a complete observing environment, the DetCom help command is typically overridden by a ``help'' script (installed as $\tilde{}$/.director/bin/help). This script displays the DetCom command set, plus any other commands (to control an instrument, telescope, etc.) that are available. If such a script is in place and you want to see the actual detcom help screen, you must type detcom.help instead of just help. (Note that the help script can be set up to do this for users, by including the line clicmd detcom.help inside the script.)

3.2 mode

The mode command should not be used by observers. If DetCom is not in ``OBSERVING'' mode, then the current mode will be displayed at the left side of the blue status bar (above the prompt.) If this line begins with the current filename, then the current mode is ``OBSERVING'' mode.

3.2.1 OBSERVING mode

Observing mode is entered by typing mode observing. The defaults command also selects OBSERVING mode. In this mode, potentially dangerous commands are disabled and not recognized by the system. These include commands which:

• Write controller DSP memory locations directly.
• Change the DSP code filename loaded in the controller.
• Power on and off or change voltages on the detector.

Still other commands disappear from the help screen, but are still accepted because it is harmless for the user to enter them, and their functionality is sometimes required in scripts.

Observing mode also enables automatic retries and recovery from certain faults. (This behavior could make trying to debug the faults difficult in a lab, so that is why they are disabled in engineering mode.) Automatic state changes, such as enabling a background ``sweeping mode'' that cleans the detectors while idling, and a timer which relaxes spring tension on the shutter (if applicable to your shutter) are also enabled in observing mode.

3.2.2 ENGINEERING mode

Given the differences between observing and engineering mode described above, engineering mode should not blindly be used for all ``engineering'' work. If someone has their fingers in the instrument, it is certainly a good idea to enable engineering mode to prevent automatic actions from being taken, especially if your shutter has the ``sleep mode''. When trying to trap a specific fault, engineering mode is also useful otherwise DetCom may simply reset the fault and try to continue before you can trap it. But for many other tests, it is advisable to use observing mode in order to test the system in as much a way as it will be used on the sky as possible.

3.2.3 SAFE mode

DetCom will remember the previous mode across restarts. If DetCom is started for the first time, or its state file has been removed, it reverts to a special default mode. SAFE mode is DetCom's way of waiting for the user to choose a mode (either mode engineering or mode observing. The reason for having a SAFE mode is that ENGINEERING mode is not safe for an observer, for obvious reasons, but OBSERVING mode is also not always safe in an engineering environment, where the user may not want automatic initialization or recovery actions to be taken on a lab system as would be done for an installed observing system.