1. Introduction

How to use this manual

1. The first section (the one you are reading now) explains what the director program is all about.
2. The User's 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 of interest to anyone writing and agent (explained below) or wanting to adapt an existing CLI driven program to run under director.
4. The Director section contains a summary of new features that director brings to the CFHT observing software, and some notes to myself on what needs to be fixed or implemented. If you find a bug not listed in this section, please let me know about it.
5. Any addition reference material, including where to get and how to build and install director, will be found in the Appendix.

1.1 Motivation

Let's say you want to write a program to control some new piece of hardware. You've never even seen this thing operate, and you just want to be able to send some commands at it to see if it works. Without thinking ahead to how this hardware might need to interact with other pieces of a software system, or how it might have to eventually accept commands from a graphical user interface or a script, your first instinct might be to write a quick and easy self-contained program that displays a menu or command prompt of the functions that this hardware accepts, takes commands on the input and prints feedback on the output (with standard things like printf() or perror() if you're using C). Once you have this thing running, it is all you'd need to verify that everything is working.

The motivation behind director is to allow a simple program like this to function in a more complex environment, such as CFHT's Pegasus observing sessions.

1.2 Unix Shell Comparison

Director is essentially just an interactive shell. Like other interactive unix shells (csh, sh, 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. Additionally, color makes things nicer to read but is not required.
• it can get basic exit/completion status from the commands it runs.

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 (which themselves could even be other interactive shells).

• Director has additional features which are useful to developers and support staff, such as 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 brought up, 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, messages can be sent to the user, and a support person can even take over control of the session to send diagnostic commands, etc.

• 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 in the works for version 3.0, which will allow multiple agents to run within the same director window. 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 Communications

There are three main types of messages and data being passed around. Director provides a very simple and easy to manage answer for the first, but the main improvements in efficiency and sophistication need to be made in the last two. Director itself does not address these issues! It does not handle state information, nor does it parse or in anyway interpret (beyond colorizing) the responses coming back from the Agent!

1. Command / Response <-- Director
2. State Information
3. Data Feed

These are topics for other papers, but NOAO's Mosaic Data Handling system could be used to speed up the Data Feed, and State Information could be handled by EPICS channel access. See below under future possibilities... director might be able to act as the go-between for the Agents by broadcasting state information for them to channel access. It is not clear if this is a good idea though. Finally, neither director nor channel access are suitable for a data feed. Keep in mind that everything here is dealing only with Command / Response issues. For a detailed diagram showing how commands and responses flow in and out of director, see figure 3.

Figure 3: Command and Response Flow