next up previous contents
Next: 3. The Agent (Programmers' Up: CFHT Director/Agent Model Revision Previous: 1. Introduction   Contents


2. Users' Guide

The information here is for those setting up environments that use Director. The actual commands available inside Director are mostly those provided by the Agents, and so are application specific. For those, the command ``help'', typed at the Director prompt, usually gives a list of available commands from Agents and scripts.

For information on invoking Director, typing ``director -h'' from the unix shell lists most of the information in the sections below.

2.1 Invoking Director

2.1.1 Cloning Pegasus Sessions

In an observing session where Director has been automatically started from login scripts, as part of the window session, it will appear in an rxvt terminal window in the lower right corner of the screen.

To bring up a similar window of an observing session in another session, I've created a script called /usr/local/bin/clone which will invoke the most appropriate version of director for you (possibly in a color terminal, if you have DISPLAY set correctly). So, for example, if you want to view the feedback from the ``aobir'' session, or send a message to the users of that session, type:

  clone aobir

Here is the help screen, which you can get on-line on a CFHT machine by just typing clone by itself.

usage: clone <session>
 Where <session> is the name of a Pegasus session, e.g., aobir
 From another Xsession or X-Terminal:
  - Make sure your DISPLAY variable is set first.
  - A new X window will pop up on DISPLAY with a director clone

 From home, or from a telnet session not on an X-display:
  - If DISPLAY is _not_ set, clone will start in the current window.
  - Be sure that TERM is set correctly.  When logged in using
    MS Windows telnet, for example, a setting of TERM=vt100 should
    work as long as the window is big enough to not have scroll bars.

 Unless you deliberately enter the Pegasus account password in your
 director clone window, it will not be possible for you to send
 any commands to the session except for the 'say' command, which
 just broadcasts a message to all other director windows.

2.1.2 Running Director in your own account

To use Director to run or test your own Agent programs, make sure your PATH is set up so you get the right version. You should typically have HOME/bin and /usr/local/bin before /cfht/bin in your PATH variable if you are CFHT. Locally, I make sure that /usr/local/bin/director exists, which will always be a link to the most recent stable version If you need to select a specific version that you know works with your setup, then you should do as the Pegasus accounts do and create a symbolic link in HOME/bin pointing to the appropriate version. For example, the current stable version is 3.31, so you'd run the command:
ln -fs /cfht/bin/director3-3.31 HOME/bin/director just once to set up selection of this version. After that, you can start up Director in one of the following ways:

usage: director [director options] [ -- [rhost:]agent [agent options] ]
or     director [director options] -- [{9600,N81,see_manual...}]serialdevice
or     director           (no startup and no args, just tails log pipe)
or     director -k <user> (attach to another user's session without su'ing)

realprogram options are passed without change to the actual cli program

director options are:
    -i <n>    displays <n> info lines at bottom of screen (default is 0)
    -j        enables jumpscroll mode for slow terminals
    -v        turns on verbose mode which shows logonly and debug
    -d        turns on debug messages (also requires -v to see on screen)
    -m        used by sessions to ensure they get a master, not a clone
    -c        sends a CR character after each command instead of a newline
    -C        turn off the titlebar clock for slow connections
    -t <type> override terminal auto-sensing and TERM var (e.g., -t vt100)
    -p <str>  sets the prompt string to expect after each command completes
    -h        displays this help information
    -hf       displays summary of director-related files and resources
    -hs       displays string parsing rules used on output from realprogram
    -he       displays summary of how the environment affects director
              (hint: -he can be combined with -k<user> for testing)  (*) See appendix

All options above can also be controlled by director builtin commands.
Type `builtin' at the director command prompt for more help on these.

2.1.3 Special options for serial devices

When opening a serial port, it is possible to specify optional parameters enclosed in braces , immediately before the name of the serial devices. There must be no spaces anywhere in this string. Multiple options can be separated by commas. Currently, the following option names are recognized. They are case sensitive:

Table 1: Supported Serial Port Options
300 1200 2400 9600 19200 38400 Choose one of these to select a baud rate when the port is opened. Some systems may support other baud rates in addition to the ones listed here.
N81 N72 O71 E71 Choose one of these to set parity, data bits, and stop bits. Default is N81.
LOCAL/-LOCAL Use this if you have/don't have modem control lines (DCD, etc.) connected. If you don't give either, the default setting of the port is kept.
SOFTFLOW/HARDFLOW Select between software/hardware flow control. Default is both OFF. When SOFTFLOW is selected (same as XON,XOFF) the stop/start characters are set to control-S/control-Q. It is currently not possible to select any other stop/start characters in director. When HARDFLOW is selected, it is assumed that CTS and RTS lines are hardwired. Note: If you need to distinguish between output flow control and input flow control, use combinations of settings below instead.
XON/CTS_OFLOW (or use XANY instead of XON) Select between software/hardware output flow control. Default is both OFF (So there is no need to give -XON or -CTS_OFLOW). On systems that have it, XANY also allows any character received to restart output (instead of just control-Q). Turning on XANY implies XON. Note: CTSXON and RTSCTS are synonyms for CTS_OFLOW.
XOFF/RTS_IFLOW Select between software/hardware input flow control. Default is both OFF. Note: RTSXOFF is a synonym for RTS_IFLOW.

For example, to connect to a typical 9600 baud RS232 device that has hardware flow control but is not a modem, the invocation might look something like this:

   director -- '{9600,N81,-LOCAL,HARDFLOW}/dev/tty02'

For serial devices that are really terminal server ``rtelnet'' processes you may not need any extra options at all since the settings in the terminal server itself are the ones that matter. You may, however, need a -p option to specify what the prompt looks like, and the -c option if the program expects a CR instead of a LF as the newline character. For example, to connect to a Prolog system:

   director -c -p '->' -- /dev/termsrv4/tty16

For devices which have no prompt at all, specifying an empty string for the prompt, as in:

   director -p '' -- /dev/termsrv4/tty16

will cause director to assume that the device is ready for new commands after all output has been flushed and a certain timeout has elapsed. The -T option (also an option to the builtin, ``agent start'' in Director 3.x) can be used to tune the timeouts in this case.

2.2 Director Window Screen Layout

Depending on the type of terminal you use to run Director, you should get most of the features illustrated in figure 4.

Figure 4: Director Window
\epsfig {file=director-window.eps}\end{center}\end{figure}

2.3 Files used by Director

~/., (see also: director -he)
  Opened for reading session feedback messages from other sources.

  When Director receives a command, this subdirectory is searched first.
  A non-executable file with a matching name is sourced like a batch file.
  An executable (or link to executable, or link to clicmd) is executed
  with the same arguments given on the command line.

  If this file exists as a symlink, Director will first attempt to
  `remsh' to the machine name given by the contents of the link.

  This file is automatically sourced at startup (non-clones only).
  Providing an agent on the command line (after --) suppresses this.

  Command history is saved here between sessions.  The `~' is always
  replaced by the home directory of the original user starting Director.

  Non-clones create (and remove at exit) this FIFO and read from it.
  Clones (and other external programs) must only write commands to it.
  If `-k' is present, clones use the `~' for that account.  `~' expansion
  at the command prompt also follows the `-k' user after in that case.

2.4 Help Screen: From Example Agent ``Directest''

When you type `help' in the Director window, you'll see something like this. The exact commands available will depend on the agent and its current mode of operation.

*---[ Command Set ]-------------------------------------------------------*
cd            : Change working directories
list          : List files in DIR
rename        : Rename a file
count         : Counts args in argv
comment       : Sets the comment header
sync          : Re-read par file
exit          : Exit the program
help          : Displays help for directest
builtin       : Displays help for director builtin options
!...          : Passes ... to a unix shell (e.g. `!ls -l *.fits')

2.5 Help Screen: Builtin Director Options

Here are some help screens about features that are handled by Director or the rxvt terminal window. These commands are reserved words and the agents themselves must never implement them.

*---[ Builtin Director Commands ]-----------------------------------------*
termhelp      : display help screen for operating this terminal window
debug on|off  : toggles debug output (also requires verbose for displaying)
verbose on|off: toggles displaying of verbose messages
clock on|off  : controls display of titlebar clock
infosize N    : displays N lines of the info panel (N=0..9)
cancel (or ^G): cancels queued but not yet executing commands
abort  (or ^C): sends SIGINT to the agent
stop   (or ^Z): sends SIGTSTP to the agent
quit   (or ^|): sends SIGQUIT to the agent
sigsend [NAME]: sends SIG[NAME] to the agent
ready         : silently returns pass or fail (for clicmd)
say <message> : use to send messages to other users with director clones
agent ...     : starts, restarts, or stops an agent running in director
autorestart on|off: tells director whether or not to restart agents that die
source <file> : reads batch commands from <file>

Want more lines or bigger fonts in the text window? Here's how...

*---[ Terminal Window Tips ]----------------------------------------------*
 o Resizing window will cause feedback area to fill available space
 o Shift-numpad-plus and Shift-numpad-minus change font size (rxvt only)
 o Shift-page-up and Shift-page-down scroll back the window (rxvt only)
 o Up-arrow and Down-arrow allow editing/repeating previous commands
 o Other cursor keys (home, end, left, right) do their thing
 o Most commonly used emacs bindings work also (but not ^Y!)
 o Command/file completion (usually bound to esc/tab) NOT implemented
 o Pressing Control-L will clear and redraw the entire window

2.5.1 Builtin agent restart

With Director 2.x, the agent command was mostly used in just one way, with restart as the argument. At the Director window prompt:

   > agent restart
   Restarting primary agent ...
   Agent ready.
   > _

This was mostly intended for debugging, recovering from crashes, or switching to a new version of an Agent without restarting Director. With Director 3.x, agent restart still works, but there are many other options. First, agent restart now takes an (optional) extra parameter telling it which Agent should be restarted. If none is given, the default Agent is restart. The default Agent is the determined by the following rules:

  1. the most recent one started with ``agent start -D ...'', or
  2. the earliest agent started, or
  3. the only agent left running.

This is mainly to provide backward compatibility with Director 2.x, where the ``agent restart'' command was never ambiguous since there was only one agent. With Director 3.x, it is best to give the handle of the agent to be restarted.

2.5.2 Builtin agent start

The command ``agent start [options] ...'' is the recommended way to add an Agent to a Director session. The command can be placed in .director/startup so that director, typed by itself from a unix prompt, will begin a Director session without any other required parameters or aliases. The syntax is as follows:

   > agent start [options] [hostname:]agentname

If the optional hostname: is omitted, the agent is started on the same host as Director. After this command completes, commands can be issued to this agent by using its ``handle'' (which, by default, is the agentname, with any version numbers removed.)

   > agentname.somecommand someagrs ...

The same string could be passed to clicmd, described below.

The handle can be omitted if this Agent is the only one running, or if -D is given in the [options] to agent start. The handle name can also be omitted if a script by the name of somecommand is placed in HOME/.director/bin/ (create the directory if it does not exist). Write the script so it simply calls

   exec agentname.somecommand "$@"

In the future, we may create a mechanism for agents to register their command set with Director so it is this necessary, but for now, this gives the same appearance to the user.

agent start supports several other options:

makes this agent the (new) default Agent. There can only be one default agent at a time.
turns on auto-restart for this Agent. (A new one will be started if it exits or crashes, but not if it hangs indefinitely.)
-H handlename
specifies the handle name which can always be used to refer to this agent specifically, by sending a command as handlename.command ....
-P promptlist
tells Director how this Agent's prompt is going to look. Use this for Agents that do not use libcli. The first character of the promptlist string is an arbitrary delimeter (choose any character not appearing in your prompt.) The string must also end with this character. This option is not needed for Agents that use cli_getline().
-T initial:sustained
is a hack for Agents which have no prompt at all. After a command is sent, a prompt will be ``assumed'' if no bytes at all are returned within initial milliseconds, or if bytes begin flowing but then stop for longer than sustained milliseconds. Use this option with caution, and only in cases where it is impossible to get an ``Agent'' to display any recognizable prompt. This option can be used in conjunction with -P for unreliable (serial, for example) connections where characters may occasionally be dropped sometimes causing the prompt to never reach Director. A long timeout can be set to prevent Director from waiting forever when this happens.
-M debug|logonly|status|warning|error
sets the default message type Director should assume for a line with no ``type:'' prefix. The option ``-M logonly'' can be useful for agents which cannot control all of the messages they generate on stdout (some may come from a library... Channel Access is a good example.) If those extra messages should normally not be visible to the user, ``-M logonly'' hides them, but permits them to be viewed later using the ``verbose on'' command.

2.5.3 Builtin agent stop

   > agent stop handlename

Use this to cause an agent to exit and be removed from the list in Director. If this agent needs be started again, a complete ``agent start ...'' command must be issued. Use ``agent restart'' instead for starting a new version of the Agent.

2.5.4 Builtin agent list

This command will print a table of all Agents in this session, along with the unix process IDs, handles, and current status.

2.5.5 Builtin clidump

This is another useful debugging command. It displays the internal queue of commands waiting to be processed. When scripts call other commands, this nesting is shown as a tree structure by clidump.

2.6 Utility Programs

As of version 3.x, Director itself no longer needs setuid-root privileges. This was required to allow Director to open rcmd() connections when an agent needs to run on a different host from the one running director. This is now handled with a separate utility, runon. There are also a set of three utilities which are useful for scripting, called clicmd and related programs clicap and clidup.

2.6.1 runon

Runon is based on rsh source code. It would be possible to have director use rsh ( remsh on some systems) but not all features with signal handling and exit status may work correctly. Instead, it is recommended that you install runon if Agents will need to run on various hosts. This utility needs setuid-root privileges.

A man page for runon is available on the Web. Director automatically invokes runon with the correct options when an agent is preceded with ``hostname:''.

2.6.2 clicmd

Agents are a type of server. The clicmd utility can be thought of as a very simple, non-specific client, because it allows any script to invoke commands as if they were separate executables. The PASS/FAIL return of the invoked command becomes the exit status of clicmd. It is typically used like this:

   clicmd command [arguments ...]

This is equivalent to typing ``command [arguments ...]'' in the Director window at the prompt. To make it even easier to access agent commands from a shell, clicmd can also be used transparently, by creating symlinks for each command which should appear as a unix shell command. By this simple mechanism, commands to a persistent server (the agent) can appear as unix shell commands (without having to add the clicmd prefix). To configure this, follow these steps:

  1. Make sure HOME/bin exists and is first in the PATH of the session. (HOME should be replaced by the home directory of the account.)
  2. Make HOME/bin/clicmd a symbolic link to the clicmd program. For example, ln -s /usr/local/bin/clicmd HOME/bin/clicmd.
  3. For each agent command which should appear as a unix shell command, set up a symbolic link to clicmd: ln -s clicmd HOME/bin/command.

If runon is also available on all hosts involved, the clicmd utility will even work when it is run from another host. It is most efficient, however, to run all sequencing and script on the same host as Director. Running Agents on different hosts does impose an efficiency penalty however.

2.6.3 clicap

This utility is the same as clicmd (see above), except that it captures the output of the command and sends it to the terminal where clicap was invoked, rather than sending feedback to the Director window. This can be confusing (users watching the Director window or clone windows will have no idea that a command was executed). Without a status server, clicap has been used as a temporary way of retrieving status from an agent. To do this, first create a command in the agent which prints a status value (and does nothing else.) The command with no arguments can be made to do this, or a separate command can be created. The following example demonstrates how this can be used to capture a value into a shell script environment variable.

   OLD_FILTER=`clicap filter`
   #  The dialog with the Agent for the above command looks like this:
   #  > filter
   #  R
   #  > _
   #  OLD_FILTER now contains "R"
   echo The old filter was \`$OLD_FILTER\'.  Moving it to \`V\'.
   exec clicmd filter V

Note the use of exec as the last statement in the shell script. It is appropriate to exec clicmd if the clicmd is the final step in the script, and the return code of the script should indicate the success or failure of this command. For clicmd (or anything else that can fail) appearing in the middle of a script, always check for failure so that scripts exit if something goes wrong.

   clicmd filter V || exit 1

2.6.4 clidup

This command is identical to clicap, except that output goes to both stdout of clicap and the director window. If a script uses clidup and this script is called from the Director window, output will be seen twice! The clidup command is only useful in some rare cases.

2.6.5 cli_cmd() in libcli

Most of the functions in libcli are for building Agents themselves. There is also a function in libcli which can be used to pass a command from another C program to an agent. This has the same effect as system("clicmd ..."); but is more efficient. It is used as follows:

   . . .
   #include "cli/cli.h"

   main(int argc, const char* argv[])
      /* NOTE: Do _not_ call cli_init() unless this program is also an Agent. */
      . . .
      if (cli_cmd("filter V") != PASS)
      . . .

next up previous contents
Next: 3. The Agent (Programmers' Up: CFHT Director/Agent Model Revision Previous: 1. Introduction   Contents
Sidik Isani