ATwish - ATNF extension to Tcl/Tk

The following information is for programmers working with the Australia Telescope National Facility extension to the WISH interpreter to the Tcl/Tk language.

A summary of the ATwish commands and procedures can be found by clicking here.

The following set of rules have been instigated for use by ATNF programmers for the generation of user interfaces for telescope control and utility software.

The ATwish program

The ATwish Tk extension

ATwish provides a number of commands in addition to the standard commands provided by the VMS version of the default Tk interpreter WISH. These commands allow the programmer to create a subprocess under the process running a Tk script and interact with that subprocess interactively.
ATwish also provides a timer function to allow programmers to have time triggered events occur in their Tk scripts.
The commands currently supported under ATwish in extension to the normal Tcl and Tk commands are
- at_createproc image proc
- at_setef id
- at_createtimer milliseconds proc
- at_send proc_id string
- at_queryproc item proc_id
- at_stopproc item proc_id
WARNING: These commands may be subject to change as development is still occurring on ATwish. If you need any clarification on ATwish commands, please see Derek.
The following commands are planned but not yet implemented:
- none at this stage
Other command suggestions are welcome.

The ATwish message protocol

The design of ATwish allows the programmer to write server programs that return information to the ATwish script.
All server programs should return whole lines which have the
" greater than" (>) symbol as the column-one (1) character.
Any messages received by the parsing procedure in the Tk script should check for these characters and any that do not conform should be displayed in a messages box. This will ensure that programs pick up messages from image crashes etc. and will make it easier for users to recognize problems as well as programmers to debug them. It may also be appropriate for such no-flagged messages to be accompanied by an audible alarm.
The next element after the > should be the keyword for the operation to be performed.
Spawned images should provide a " greater than" (>) symbol as a prompt.
The Tk scripts should wait for the > prompt as an indication that the subprocess image is ready for input.
Termination of the line with <cr> is not necessary
Each record should be independent of other records.
Where long processing is expected, the user interface should convert the cursor to an appropriate style (e.g. clock/hourglass) to indicate the non-responsiveness of the system.

ATwish server reserved words

The command exit is a reserved word for termination of a subprocess image (where ATNF written). Developers of programs should ensure that the exit command will be recognised and supported at any valid input prompt.
The command init is reserved. Its purpose is cause a general reset of the server program.
The command ping is reserved. The ping command should cause the server to return a line with > character. This can be used to test whether the server is still responding to commands.

The ATwish code management standard

As ATNF moves towards the user interface scheme of server/script, it is desirable to have a standard area for the placement of completed and developing code, both for the Tk scripts and server or standalone executable files.
It is important that all local code maintains the same "look & feel". With this aim in mind, all developed ATwish scripts should include the standard local definitions Tk script. This script will contain the definitions that are deemed to be necessary to all locally generated scripts in the interests of presenting uniformity to our users. To access this script, include the following line as the first executed line of your .ATK main file:
```
       source at\$tk_include:at_defs.atk
       
```
Note the \$; this is because $ is a reserved Tcl/Tk character. For information about the added procedures defined in the AT_DEFS standard, click here.
As it is expected that servers will be written with the aim of serving many programs (e.g. astronomical time coversions), it is required that for each server, a Tk script exists that will drive all of its functions. There are several reasons for this:
- It verifies the message protocol to the server.
- It acts as an example of the server functionality and capability.
- It provides an example of a Tk script to access the server functions
- It makes for uniformity of script-server for all local code.
The script for each server does not have to necessarily be a sophisticated piece of code, not does it need a complex or highly developed user interface.
Each server/script should reside in its own CMS area under OBS$1, as per the normal code standards of the Observatory.
Public released code should reside in AT$RUN. Because of the interpreted natureof the ATwish scripts, any routines that are called should be found in this area (but should eb referred to using the special logical (see the next point)). Note that this includes bitmaps (.XBM files).
The logical AT$TK_INCLUDE will point to AT$RUN. If for developmental reasons, this needs to be changed, the logical should be redefined at the process or job level, and be a multiply defined logical ending with AT$RUN.
ATWISH.EXE will reside in AT$RUN. The developmental version of ATwish will be kept separate. The ATwish code will be a minimal addition to the standard Tcl/Tk distribution. The only changes to pre-existing Tcl/Tk code will be the calling of AT_Init() and the #include that contains the initialisation functions declaration.
Symbols defined to activate programs should be resticted to the program identifier only and should not reference AT, CA, TK, ATK or any other location or code reference. Likewise, window manager controlled decorations should also follow this guideline (e.g. icon names).

The ATwish source code standard

The fact that the programmer is writing code for an interpreter is no excuse to be sloppy. Careful organisation of .ATK files is essential for efficiency and maintainability. Badly written code is not servicable and will more readily be deleted and rewritten than repaired or enhanced.
ATwish scripts should be able to be passed through the DOC automatic software documentation system. With this view, the following header has been proposed:
```
#+
# Title       [tbs]
# Preface     [tbs]
#
# Author      [tbs]
# Date        [tbs]
#-
{
  [tbs]
}
```
This header should be used as the first lines of every Tk script file that acts as a main file (rather than just a set of procedures). In addition, individual procedures within the script should be headed with code like this:
```
#+
# Routine     [tbs]
# Function    [tbs]
#
# Author      [tbs]
# Date        [tbs]
#
# Call
#-
proc xxx_procname {arg1 arg2 arg3}
{
  [tbs]
}
```
At this stage, I can see no easy way of incorporating the proc xxx_procname {arg1 arg2 arg3} into the comment block. One possibility is:
```
# Call
proc xxx_procname {arg1 arg2 arg3}
{
#-
  [tbs]
}
```
but the included { is a little messy. Please feel free to comment on this issue.
Indentation of two (2) spaces is required for each level within the code.
Script procedures should be short and modular. If a procedure is long, split it up into sub-functions.
Avoid using Tcl/Tk commands as procedure and variable names. This may lead to problems with standard script libraries that we later write.
Script names should follow the DEC convention of a program identifier (of ideally three (3) characters) followed by an underscore and then the procedural name. Meaningful procedure names are strongly recomended.
When creating widgets, maintain the hierarchical naming scheme. This makes it easier to make associations when reviewing code.
Thou shalt not use tabs!
To assist in the checking of Tcl/Tk scripts, I have written a small utility program that takes a source file as an argument and examines it for potential problems. These include:
- Using reserved words as procedure names
- Tabs and control characters
- Non-standard file names
- Procedure definition style
This utility can be enhanced. If developers would like to see additional features, then please let me know.

Original: dmckay (30-Nov-1994)
Modified: nmckay (9-Oct-1995)