1. Introduction

How to use this manual

1. This section, and the Abstract, explain what the Director program is all about.
2. The Users' Guide contains mostly the same information you can get from Director by invoking it with the ``-h'' command line option. There is also some information here on how to make sure you are running the right version of the program.
3. The Programmers' Guide contains information on creating an ``Agent'' command line program.
4. The Director section contains a summary of new features that Director brings to the CFHT observing software
5. Any additional reference material, including where to get and how to build and install Director, is in the Appendix.

1.1 What's New in 3.x

The documentation for Director 2.x mostly described features of that version of Director. The current version of this document now covers the Director 3.x. Updated sections include the Abstract, the section on the big picture, expanded options for the ``agent restart/start'' builtin,

New sections describing libcli functions useful for writing agents, and also libcli cli_cmd for clients and descriptions of runon, clicmd, clicap, and clidup have been added. A new timing diagram illustrates how overlapping commands using the intent/go/wait model can be used to control slow moving devices efficiently.

1.2 Unix Shell Comparison

Director is essentially just an interactive shell. Like other interactive unix shells (csh, bash, etc.):

• it displays a prompt where you can type commands
• it has some commands that are built-in (like ``cd'' to change working directories.)
• it can ``source'' scripts or batch files of commands
• it expects a terminal capable of a few basic functions. Cursor positioning is a requirement. Color makes things nicer but is not required.
• it waits on commands and gets basic exit/completion status.

Director differs from other unix shells in the following ways:

• It does not support job control in the same way that a traditional unix shell does. Instead of every command you type invoking a new program, commands can end up being sent to already running programs, called Agents.

• Director has additional features which are useful to developers and support staff, including a cloning capability, which can be used to get an exact copy of the user's window to appear at a remote location. The ncurses library takes care of efficiently updating the screen, so it even works well over a relatively slow modem connection. Once a clone window is displayed, additional debugging messages (which were always in memory, just not displayed on the user's screen) can be ``unhidden'' in the clone's view of the window, ``chat'' messages can be sent to the user, and a support person can even take over session to send diagnostic commands, or control things from the remote location without having the user exit their copy of the software.

• The Input Multiplexer built into Director allows the Agent program to pretend it only has one source for command input (standard input) but commands may in fact be redirected from a user interface or a script by Director. Figure 1 illustrates this concept.

  Figure 1: Director as an input multiplexer

  

• An Output Multiplexer is most important new feature introduced in Director version 3.x. It allows multiple agents to run within the same session. By merging the command sets and feedback of multiple programs, Director can give the appearance of a unified command interpreter to the end user. Figure 2 illustrates this concept.

  Figure 2: Director as an output multiplexer

  

1.3 The Big Picture

Since we are using Director for image acquisition systems at CFHT, it might help to look at the full observing environment. There are three major types of data or messages passed in our system:

1. Command / Response (Director)
2. Image Transfer of Pixel Data
3. State Information

Image Transfer is currently handled by writing directly from the Detector Agent (DetCom) to a file on disk (or network disk). Other than triggering the commands, Director has no connection with Image Transfer.

State Information will some day be handled by a Status Server, but currently we store values in ``par files'' on disk. This serves as a (sometimes troublesome) distributed status database. Director has no connection with a Status Server or par files.

In the absence of a Status Server, there are a few clunky ways to get by. One of these actually does involve Director, and is described in the section on the clicap utility.

Director only addresses the first aspect of our acquisition system: passing commands and getting a response. Warnings and errors (which Agents transmit to Director using calls like printf()) are merely presented to the operator highlighted or in color to draw attention, but are never interpreted by Director. Director also does not use any kind of error return codes. The only two possibilities for a command are for it to complete with PASS, or complete with FAIL (which halts any scripts or other commands that were waiting to be processed.)

For a detailed diagram showing how commands and responses flow in and out of Director, see figure 3. NOTE: This diagram shows some other Pegasus components which are not described in this document. A full understanding of this diagram is not necessary to use Director. See the section on Director's features for a summary of the practical advantages Director brings to an acquisition environment.

Figure 3: Command and Response Flow