`term' 4.3 - A terminal program for Amiga computers Copyright © 1990-1995 Olaf Barthel You may make and distribute verbatim copies of this documentation if the contents are unchanged or the author has agreed to any changes made. No guarantee of any kind is given that the program described in this document are 100% reliable. You are using this material on your own risk. The program `term' and the data received/sent by it must not be used for the following purposes: 1. The construction, development, production or testing of weapons or weapon systems of any kind. 2. The construction, development, production or use of plants/installations which include the processing of radioactive/fissionable material. 3. The training of persons to deal with the abovesaid actions. Listen to your conscience. Changes ******* Previous `term' releases would use a different ARexx host interface implementation. In order to conform to Commodore-endorsed user interface style guidelines it was redesigned from scratch for version 3.0. The design and implementation of the ARexx host interface was suggested by the `Amiga User Interface Style Guide' and strongly influenced by Martin Taillefer's `TurboText' ARexx host interface. Not a simple command has `survived' the revision, the new implementation is no longer compatible with its predecessors, so existing ARexx scripts will have to be adapted or even entirely rewritten. `term' no longer distinguishes explicitely between asynchronous and synchronous commands (i.e. commands which force the main program to wait and commands which need not bother the main program as the ARexx handler process is able to execute them). As of this writing it is safe to assume that almost any command will be processed by the main program, exceptions are noted. term and ARexx ************** This document describes the ARexx(tm) (1) commands supported by `term'. This is not intended to be an introduction to the language itself. Rexx was developed by Mike F. Cowlishaw on an IBM/SP system and ported to the Amiga by William S. Hawes. ARexx (or Amiga Rexx) is a commercial product which is included with the AmigaDOS 2.0 Enhancer Package. If you need a good introduction and description of the language, try to get a hold of the book `The REXX Language A Practical Approach to Programming' by M.F. Cowlishaw, available from Prentice-Hall International, Inc. The section entitled Command execution gives a brief introduction how to write and run ARexx commands. For more information refer to the Release 2 Users Manual `Using the System Software'. By default `term' opens an ARexx host by the name of `TERM' (accessable via `address term'). If more than a single `term' process is running on your machine, the name of the host will be adapted to the number of the program (i.e. the first programm will use `TERM', the second one will use `TERM.1', the third one `TERM.2', etc.). The default name can be overridden by invoking the program with certain parameters (see main program documentation). The name of the host is displayed in the status window (see main program documentation). ---------- Footnotes ---------- (1) ARexx is a registered trademark of Wishful Thinking Development Corp. Command execution ================= In order to invoke any command supported by `term' one usually has to address the host explicitely: /* Address the `term' host. */ ADDRESS term /* Invoke the `beepscreen' commmand. */ BEEPSCREEN However, if an ARexx script is invoked directly by the `term' main program, the script will by default address the main program it was invoked by. Most commands will return results or error codes on failure. To enable result codes, one has to use the `options results' command. The results returned by commands will be placed in the `result' variable: /* We assume that the script will address the host it was invoked from. * * Enable command results. */ OPTIONS RESULTS /* Request a string from the user. */ REQUESTSTRING DEFAULT 'anything' PROMPT 'Enter anything' /* Did the user cancel the requester? */ IF rc ~= 0 THEN SAY 'user cancelled requester' ELSE SAY result /* Output the result . */ Failure codes will always be returned in the `rc' variable (see previous example). In case of failure (variable `rc' >= 10), `term' will leave an error code in the `term.lasterror' variable: /* Enable command results. */ OPTIONS RESULTS /* Produce an error by not supplying any arguments. */ STOPBITS /* Display the error code. */ SAY term.lasterror Rexx tries to tokenize any command parameters, this process involves promoting them to all upper case letters and checking for illegal characters. This feature inhibits the use of the `:' (colon) and blank space characters in parameter names unless the corresponding arguments are enclosed in quotes. To make things even more complicated, the parser will not always accept parameters to contain blank spaces. If a command template accepts the entire command line (such as `TEXT/K/F') a parameter can include any number of blank spaces. A command template to accept just a single parameter (such as `TEXT/K') requires double quotes if blank spaces are included. Text such as `tea or coffee?' thus becomes `'"tea or coffee?"''. /* The following command will fail to send the file `ram:foobar' as the colon * in the path name will cause an error: */ SENDFILE ram:foobar /* Here is how to do it correctly: */ SENDFILE 'ram:foobar' /* The following command will fail to send the file `foo bar' as the * file name is treated as two single files: */ SENDFILE foo bar /* The next line will still fail to send the file `foo bar' * as the ARexx parser will split the argument into two * parameters. */ SENDFILE 'foo bar' /* Here is how to do it correctly: */ SENDFILE '"foo bar"' /* The following command will not transmit the string `Hello sailor' * across the serial line as the single words will be capitalized, * they will be transmitted as `HELLO SAILOR': */ SEND Hello sailor /* Here is how to do it correctly: */ SEND 'Hello sailor' Stopping a command ****************** Programs and commands sometimes fail to do what the user is expecting them to do which makes it necessary to bring program/command execution to a stop. A common ARexx script to call no external functions or host commands one can be halted in the following ways: 1. Executing the `HI' command (located in the `SYS:rexxc' drawer) from Shell. This command will attempt stop *all* currently running ARexx scripts. 2. If the ARexx script to be executed runs in an environment to sport an output window, activate the window and press the `Control + C' keys. A break signal will be sent to the ARexx script, causing it to stop as soon as possible. With host environments such as `term' it may not always be possible to abort a command using the simple measures described above. As for `term' any command to wait (such as the READ, DELAY or WAIT commands) can be aborted by sending `term' itself a break signal in the following fashion: 1. If the `term' program is still attached to a Shell output window, activate the window and press the `Control + D' keys. 2. If the `term' program was invoked from a Shell but is no longer attached to it, enter `status command term' from Shell, remember the number printed, then enter `break ' with `' being the number returned by the `status' command. 3. Press the hotkey combination configured in the program hotkey settings (see main program documentation). The default is `Right Shift + Left Shift + Escape'. This will cause a break signal to be sent to the `term' program. Commands ******** The commands supported by `term' are listed in a table of the following form: `Format:' The command name with its possible calling parameters. In this table parameters are enclosed in brackets and braces, separated by commas and vertical bars; *do not type these special characters along with the parameters!*: `< > (Angle brackets)' Angle brackets enclose parameters whose contents *must not* be omitted in order to make the command work properly. `[ ] (Square brackets)' Square brackets enclose optional parameters. `{ } (Curly braces)' Curly braces enclose items which can be repeated a number of times, such as file name lists. `| (Vertical bar)' Vertical bars separate alternative, mutually exclusive options. `, (Comma)' Commas separate multiple applicable options. `Template:' The command template, similar to the command templates employed by AmigaDOS Shell commands. Possible templates are: `/A' The parameter must always be included in order to get accepted. `