Cafard - A Program for Interchanging Mail over Terminal Lines Mark Crispin Centre Mondial Informatique et Ressource Humaine 19 July 1984 LAST UPDATED: Mark Crispin, PANDA PROGRAMMING, 19 March 1985 INTRODUCTION Cafard (French for "cockroach") is a program for interchanging mail over TTY lines. It is designed to be used with the Special network interface in the TOPS-20 mailsystem (see SPECIAL-NETWORK.DOC for information on the Special interface). Cafard is distributed by PANDA PROGRAMMING as part of the TOPS-20 MM mailsystem package. Cafard requires no special privileges other than read/write access to the queue directory it must dequeue from, write access to MAILQ: (e.g. what all other users on the system have), and access to whatever TTY line(s) it must use. Unlike MMailr, Cafard is not a continually-running system daemon, nor does it operate automatically. It is instead intended to be run as a periodically-resubmitted batch job. This is because many applications (e.g. anything which incurs line charges, such as phone lines or X.25) of TTY mail should only be run at certain hours. SPECIFICATIONS Cafard is in one of two modes: Cafard user and Cafard server. The differences between the two are as follows: . a Cafard server is invoked by GET CAFARD then REENTER; a Cafard user by RUN CAFARD. . a Cafard server does its I/O on its own TTY:, while a Cafard user does I/O on a separate TTY opened as a device. . A Cafard user processes two "dialog script" files which instruct Cafard what to send over the line to get in contact with a Cafard server, and how to clean up afterwards. . A Cafard user first delivers mail to the server host then picks up mail for it; a Cafard server does the reverse. The user Cafard process should be connected to the appropriate MAILS: subdirectory for the host it is expected to connect to. In addition to any -MAIL.* files which may be on that directory, there should also be two "dialog script" files named OPEN-DIALOG.TXT and CLOSE-DIALOG.TXT. A dialog script file is actually a small programming language designed for interacting with terminals, PADs, modems, etc. It uses the following grammar: open_dialog := line_list CRLF command_list close_dialog := command_list command_list := command [command_list] command := [WS] [comment | eat_command | loop_command | lose_command | message_command | send_command | test_command | wait_command] line_list := octal_number [`,' octal_number] loop_command_list := command | exit_command | repeat_command [loop_command_list] comment := `!' string `!' eat_command := `E' exit_command := `X' loop_command := `<' loop_command_list `>' lose_command := `L' message_command := `[' string `]' repeat_command := `^' send_command := `"' string `"' test_command := `=' [time] `"' string `"' [+ command_list] [- command_list] [~] wait_command := `W' CRLF := CR LF WS := NUL TAB LF FF CR SPACE So much for the grammar. What this all means is that a dialog script file consists of a set of commands with optional whitespace between them. The OPEN-DIALOG.TXT file starts off with a list of TTY lines which Cafard should try to use followed by a CRLF, then dialog commands. The CLOSE-DIALOG.TXT file has only dialog commands. The `!' character opens a comment, which is terminated by a second `!'. Note that comments are NOT terminated by CRLF or by the termination of a loop or conditional. This can lead to a number of pitfalls; a single missing `!' can cause truly amazing results. The `[' character begins a string to be output to the console terminal (as opposed to the TTY line the protocol is happening on). It is useful in logs for progress and error reporting. It is closed by a `]'. The same cautions noted for comments apply here. The `"' command begins a string to be sent to the TTY line. Such things as network connect commands, login commands, etc. would be sent by this. It is closed by another `"' and at the risk of being tiresome I'll remind you to read the cautions about comments and log strings as they are applicable here to. The `L' command indicates that the dialog has encountered some error. Typically, this is as a result of a test command (see below) returning failure (or perhaps truth). The dialog file is aborted and Cafard gives up on that line for the nonce. It will retry on another line, or on this line again after the delay period (see the sources for more information about the delay period; it is an assembly switch). The `<' command begins a loop. The comments following up to a `>' (NOT part of a comment or other string!!) are considered part of the loop. Within a loop, a few additional commands are valid. `X' gets out of the loop, searching for the `>' and resuming execution of the script at that point. `^' goes back to the top of the loop, up to the Cafard-defined maximum number of iterations (see the sources), at which point `^' becomes a no-op. This iteration maximum feature is an alternative way to tests to time out waiting for some particular thing to happen. The `=' command begins a test. It is optionally followed by a number, which is the maximum number of seconds to block in the test before timing out. Immediately following (no whitespace!) is a quoted (with `"') string. Cafard will read from the TTY line and try to find a string matching the test string. If it sucessfully reads the string, Cafard will search for either a `+' or a `~' (once more with feeling, read the cautions about strings) and resume execution at that point. Otherwise, if Cafard's timeout count expires, it will search for either a `-' or a `~'. It is good practice to always include a `~', and is required if only one clause (`+' or `-') is given. If both clauses are given, note that the first one will fall into the second one unless it is in a loop. Loops can be used as control structures by virtue of the `X' command. `E' and `W' are used for synchronization. The `E' command will read all TTY input available now and in the next 3 seconds. This is useful to "eat" some arbitrary unknown large chunk of input. The `W' command will block for 250 ms; this is useful for slowing down characters sent to the line. For example, a Ven-Tel modem expects human typing rates when talking to its dialer and will discard input which is coming in "too fast". OTHER INFORMATION Cafard's high level protocol for sending messages is simply a byte-stream of the Special network format queue file to the remote host followed by an EOF signal. This is done by the $PBIN, $PSOUT, and $PEOF routines. An EOF occuring at the start of the message indicates that no more messages are forthcoming. The low level protocol takes care of flow and error correction as well as providing the out-of-band EOF signal. The current protocol implemented is Cafard Phase I, which is described in CAFPRO.MAC. This is a lock-step protocol which makes extremely conservative decisions in order to talk to systems with inadequate power to handle high-speed TTY bursts for a long period of time. While Phase I should work on any TTY or modem connection, its performance may be suboptimal and it may not deliver satisfactory results on TTY connections going into an X.25 etc. network. Phase II is (as of this writing a future) upwards extension of Phase I. It supports windowing and larger data packets than Phase I as well as negotiated window and data packet sizes. Cafard links talk in Phase I protocol unless a negotiated agreement occures to use Phase II. Phase III is an upwards-compatible extension of Phase II to support bidirectional mail transmission; that is, mail is transmitted simultaneously in both directions and the acknowledgements are piggy-backed on the data packets. It is possible that the milestones established by Phase II and Phase III may be reversed in the actual implementation. Besides the TOPS-20 implementation described here, a server- only implementation of Cafard exists for the WAITS operating system.