OBS-TALK-2

Generic Talker:
User Guide and Design Notes

Guy Rixon

Issue 2.2; 17th July 1995




Royal Greenwich Observatory,
Madingley Road,
Cambridge CB3 0HJ

Telephone (01223) 374000
Fax (01223) 374700
Internet G.Rixon@ast.cam.ac.uk

1 Introduction

1.1 Purpose of this document

A generic talker program is described from three points of view: the end user; application programmers intending to interface to the talker; programmers maintaining the talker. This is not a requirements document: see OBS-TALK-1 for a specification of the talker.

1.2 Scope of the software

The general purpose of talkers is introduced in OBS-TALK-1. The program described here is a generic talker for use with an X-windows display. The program implements all the features required by OBS-TALK-1 and is a specialized interpreter for a set of Tcl/Tk scripts. The utility program jabber, which can be used to generate dialogues with the talker, is also described.

The software described is defined by the bill-of-materials talker.bom. At the time of writing, the current version of the package is 3.4.

1.3 References

[1] Dialogues with the user: general principles
RGO/ING document OBS-TALK-1 by Guy Rixon.

[2] DTCL - Tcl interface to DRAMA
AAO document DTCL_12 by Jeremy Bailey and Tony Farrell.

[3] Parameter-reading facilities for Tcl scripts
RGO/ING document OBS-TCL-1 by Guy Rixon.

2 The end-user's view

The talker is an X-windows application that displays text and dialogue boxes on behalf of other programs. A talker should appear whenever you start one of the Unix-based observing systems at the Issac Newton Group. Normally, there is one talker per point of control, e.g. one for the Observer and one for the Telescope Operator. Figure 1 shows what you're looking for.

The talker's main window logs, with time-stamps, incoming messages and any responses you make to them. The text is editable; that is, one can add comments to it. In the current version, there is no way to save the text to file or print it

; this feature will be added in a later upgrade.

The talker gives you information in the form of comments, alarms and prompts. Comments are written only into the message log; the other types of dialogue involve dialogue boxes.

The talker requires you to acknowledge alarm dialogues within 30 seconds; after that bells start to ring. Prompts should also be answered quickly as a prompt dialogue causes the talker to block, which can shut out alarms and can, ultimately, halt the observing system.

Your response to prompts is written into the message log.

If you enter an observing command and the command sends you messages, those messages only appear on your designated talker; these messages are not copied to all observing stations running talkers.

By default, the talker displays the logged text in 10pt-Helvetica type (the dialogue boxes tend to use larger type). You can vary this default size (and thus the size of the window) using the Type-size menu.

2.1 Starting and stopping talkers

Normally, talkers are started by system start-up scripts; occasionally, you may need to start one from a shell prompt. Guest observers should not need the procedures in this section.

To start a new (or extra) talker manually, find a terminal window that has the observing commands defined and give the command 

% talker [-n net-name] [server-list]
The -n option tells the talker the name with which it is to log into the observing system's message net. This name, for which the default is TALKER, has to be unique; if you get an error saying `name already in use' try TALKER2, TALKER3 etc. The server-list option is a space-separated list of programs which the talker to monitor. This varies with the instrument configuration and is best copied from an existing talker on another console.

To direct messages from observing commands to a specific talker, set the environment variable TALKER to the name by which the talker is logged into the message net. This name is written in the title bar of the talker's window. For example if you have a talker with a title 

TALKER (DRAMA name = FRED)
displayed, then you need to 

% setenv TALKER FRED
This setting only applies to commands you type from the terminal window in which you set the variable.

To stop a talker at the console, choose the Exit option from its File menu. You can also stop a talker by invoking its EXIT action.

2.2 Server connections

As well as fielding messages from the observing commands, the talker also monitors the permanently-resident server programs which do the work. If you get an alarm saying that a server has disconnected, assume that some part of the observing system has shut down or failed. If you restart that server, the talker will automatically re-connect to it within 15 seconds.

You can monitor extra servers to those monitored using the Add server option of the Connections menu. (Guest observers should never need to do this.) If the monitor starts successfully, the talker will log that fact.

2.3 jabber

jabber is a client program that starts dialogues using the talker. It is necessary for testing the talker and may also be useful as a way of contacting the talker from a shell script. Its syntax is 

% jabber dialogue-action text
where dialogue-action is COMMENT, ALARM, PROMPTGONOGO or PROMPTSTRING and text is a quoted string to be displayed by the talker. For example: 

% jabber COMMENT "This is run 1 of 12."
% jabber ALARM "Help help help!  The dome is on fire!"
jabber lists any arguments returned from the dialogue to the terminal from which it was run.

3 Application programmer's view

The talker implements the client (action) and server (parameter) interfaces specified in OBS-TALK-1 issue 1.2. At v3.4 of the talker, the implementation is complete and correct apart from the following points.

z Active alarms do not lock any controls.

z The talker blocks partially while waiting for replies to prompts. `Partially' means that interface events such as editing the message log and working the menus can still happen, but the talker will not process other dialogues and will not drain its IMP message-queues. Alarm dialogues do not have this problem. The ALARM action returns status to its caller as soon as the alarm is posted and the acknowledgement of the alarm is handled asynchronously: the talker does not block while waiting for the alarm to be acknowledged.

z There are no facilities for saving the message log to disk.

z The server interface only works on servers that provide the PING action.

All these failings except the first will be corrected in later versions.

V3.4 of the talker offers additional behaviour to that specified in OBS-TALK-1.

z Monitors on servers are automatically re-connected if a server is killed and re-loaded. Re-connection happens within 15 seconds of the server coming on-line.

z The talker reports connections of servers as comments and disconnections as alarms.

z Where a dialogue (action or parameter) has no Time component, the server supplies a time-stamp which is the UT at which the dialogue request was processed.

z Ill-formed dialogue requests - those in which the Text and/or Sender components are unavailable - are completed with good status returned to the client, but no output is made to the user.

z Dialogue requests from clients in which the action name is not COMMENT, ALARM, PROMPTGONOGO or PROMPTSTRING cause no output to the user and a status of DITS__UNKNACT, action not support by this task.

z The name by which the talker logged into the DRAMA message net is displayed in the title-bar of its window.

4 Maintenance programmer's view

4.1 Design

This section contains brief notes on how the talker is constructed. Refer to the prologues of the code components for more details.

The talker consists of a specialized Tcl interpreter-harness, talker.c, and a file of Tcl scripts, talker.tcl. The harness uses code in libcia and the Tcl scripts include the components colours.tcl and monParameter.tcl.

The talker's main() function, in talker.c, logs into the DRAMA message net. The talker is established as a DITS task with an X-windows-compatible notification system and 60 000 bytes of message space. The Tcl script-file talker.tcl is located from the observing system

in the bin sub-directory. The specialized event-loop DtclTkMainLoop() is called in place of DitsMainLoop().

DtckTkMainLoop() [2] establishes a Tcl interpreter with Tk and DTCL commands loaded. The script file talker.tcl, the name of which is an argument to DtclTkMainLoop(), is evaluated; this causes the outer-scope code in the script file to execute immediately and makes the procedures in the file available for later use from call-backs. DtclTkMainLoop() also executes a C function, the address of which is supplied as an argument, which defines new Tcl commands for the talker.

The talker allows no exit from DtclTkMainLoop(); exit is via the exit() function called by the handler for the EXIT action or the Exit menu-item. DtclTkMainLoop() is called from an unconditional, infinite loop. This coding counters bugs in IMP which cause DtclMainLoop() to exit unexpectedly and without a condition code; the net result of these bugs is now to restart the GUI.

Two new Tcl commands are defined for the talker. The command ut returns the current time in the format hh:mm:ss.s. The command servers returns a string

from the variable serverList_l which is a space-separated list of servers to be monitored. This string is set up before DtclTkMainLoop() is called.

The dialogue actions are mapped into DITS before the event loop is started. The standard actions EXIT and PING, using the standard code from libcia, are also enabled. The handler for each of the dialogue actions is textOut() and the actions are distinguished by their numeric codes. The action-handler calls a separate Tcl procedure, from the set defined in talker.tcl, for each action. The procedure is interpreted and executed by Tcl_Eval().

The Tcl code for the dialogues executes partly in the foreground (thus freezing the interface very briefly) and partly in the background in response to X-windows events (thus unfreezing the interface. The sequence of events is outlined below for each type of dialogue.

Comment: the dialogue is executed entirely in the foreground.

z Parse the arguments of the dialogue; abort if Text or Sender is not available.

z Write the comment into the message log.

z Return from Tcl to the action-handler; end the action.

Alarm: the action is executed entirely in the foreground, but the dialogue completes through background processing after the action has finished.

z Parse the arguments of the dialogue; abort if Text or Sender is not available.

z Write the text into the message log.

z Generate and post the dialogue box.

z Make the dialogue box flash to get the user's attention.

z Pass all further processing of the dialogue into the background.

z Return from Tcl to the action-handler; end the action. By returning from the action handler to the event loop, enable processing of the X-windows events in the background.

z When the user acknowledges the alarm, log the acknowledgement and un-post the dialogue box.

Prompts: the action and dialogue are conducted in the foreground. Background processing of X-windows events only (not DRAMA-message events) is possible while waiting for the user to reply to the prompt.

z Parse the arguments of the dialogue; abort if Text or Sender is not available.

z Write the text into the message log.

z Generate and post the dialogue box.

z Make the dialogue box flash to get the user's attention.

z Wait for the user to reply to the prompt. The flashing of the dialogue box is background processing and the X-windows event loop is active at this point; DRAMA messages are not being handled.

z When the user replies to the prompt, save the result and un-post the dialogue box.

z Write the user's reply into the message log.

z Return from Tcl to the action-handler; end the action.

Connection to the servers is handled by the techniques described in OBS-TCL-1. The parameters COMMENT and ALARM are monitored in the servers `by procedure', the procedures being those used for the COMMENT and ALARM actions. The fact that the dialogue scripts abort silently for a dialogue with no Text or Sender argument handles nicely the first message

in each monitor.

Server connections are established by the outer-scope code in talker.tcl. When a server breaks connection, the fact is reported as an alarm dialogue and monConnectToTask is called to remake the connection. The result of this is a polling of each server, at 15-second intervals until the connections are remade.

The talker is packages with the utility client jabber in one bill-of-materials; the two programs share the same version number and makefile. The bill-of-materials talker.bom defines the talker/jabber package; the bill builds and installs both programs.

The makefile, talker.mk, has major targets talker, jabber, install, deinstall and clean.

talker builds the executable program talker in the current directory; it does not fetch the associate Tcl scripts.

jabber builds the executable program jabber in the current directory.

install moves talker, jabber and the Tcl scripts into $OBSSYS/bin. It builds talker and jabber if they are not present in the current directory.

deinstall deletes talker, jabber and the Tcl scripts from $OBSSYS/bin. It deletes the script files colours.tcl and monParameter.tcl which may be used by other programs.

clean removes intermediate and source files, but not the executable programs. If clean is `built' after a successful install, all files relating to the package will have been remove from the build directory.

To build talker or jabber, you must have libcia installed at v4 or higher. To run talker, you must have the program ofind installed (it is used to locate the subordinate files needed by talker.tcl).

4.2 Testing

Test scripts are provided for the talker. Currently, these cover path testing of talker.tcl and stress testing of the talker. Functional and interface requirements are implictly tested by the path tests, which exercise all the talker's features.

To run the path tests you need the dtcl program from the DRAMA release and access to a server program which uses the talker-server interface described in OBS-TALK-1; this server must also support the actions EXIT and PING. You must have the IMP master-task running to do these tests. To start the path tests, extract from SCCS

the script file talkTestPath.tcl and execute the commands 

% $IMP_LIB/master &
% $DTCL_LIB/dtcl -t talkTestPath.tcl
(You need to define IMP_LIB and DTCL_LIB first; you can do this with the /drama/dramastart command). The script will give detailed instructions as it goes along.

The main point of the path tests is to exercise every branch and statement in talker.tcl and so eliminate the possibility of syntax errors.

The given script achieves C1+C2 coverage and so will find all syntactic traps. Coincidentally, the path tests exercise all the advertised features of the talker. Where the test script asks the tester to check output, it is the nature and sense of the output that should be checked; the exact wording is not important.

To test the additional paths involved with the menus, manually

select each of the menu items. You will need to run the Add-server item twice to exercise both the Ok and Cancel options. Some of the type-size options may have not effect if the X-server doesn't have the full range of fonts.

To run the first of the two stress tests you need the server used for the path tests and the program extask but not dtcl. Fetch from SCCS the script file talkTestStress1 and execute it: 

% teskTestStress1
This script loads and kills the server process every five seconds, causing continual connection and disconnection from the talker. Two types of bug may be revealed: the talker may lose IMP resources and be unable to reconnect; the pressure of many alarm dialogues (from the reports of disconnections) may overload the talker and stall it. This test needs to run for at least 30 minutes and the alarms become very noisy after about the first two minutes; it's best to run it over lunchtime in an unused office!

To run the second stress test you need only talker and jabber. Extract from SCCS the script talkTestStress2 and run two or more copies (the number of copies increases the visciousness of the test) in the background of the shell: 

% talkTestStress2 n &
% talkTestStress2 n &
% talkTestStress2 n &
where n is the total number of messages to be sent by each script. You need to choose an acceptable level of load handling for the talker. I suggest that it should survive 500 messages from each of three copies of the test script and 20000 messages

from one copy. The test scripts will exit when all their messages have been sent.

5 Future developments

The description above applies to talker v3, due for release in the summer of 1995. Substantial improvements are planned for future versions.

z A new dialogue type `HIGHLIGHT' may be introduced to match the highlight attribute in ERS. These dialogues would be intermediate in urgency between comments and alarms.

z A facility to print and/or save the message log will provided.

z Some consideration will be given to making the talker configurable

through X-windows resources. For example, the widget colours, the window size and the font used in the message log might be configurable.

z The probing for loaded servers will be changed so that there is no need for the server to provide the PING action.

z The talker will have to be restructured to stop it blocking during prompts. This will probably mean a move away from DITS and DTCL and providing a custom event-loop. The return messages from client dialogues would be generated in Tcl commands invoked as event handlers.

z Once the talker has a custom event-loop, it may be possible to provide the standard dialogues with an interface other than DRAMA; for example, named pipes might be supported. This would allow shell-scripts and PERL programs to communicate with the talker without going through jabber.

Appendix A. Document history

Issue 1.1 07/07/95 First issue, describing talker v2.2.

Issue 2.1 13/07/95 The section on testing was added. Talker v2.2 was current at the time of this issue.

Issue 2.2 17/07/95 Corrections to descriptions of tests. A new graphic is provided for the talker, showing a dialogue box. The DRAMA name in the talker's title-bar is noted. This issue applied to talker v3.4.