================================== term =================================== =========================================================================== A Gift-Ware telecommunications program written by Olaf Barthel, © copyright 1990-92 by Olaf Barthel & MXM, All rights reserved. No guarantee of any kind is given that the program(s) described in this document are 100% reliable. You are using this material on your own risk. ============================= term and ARexx ============================== =========================================================================== This document describes the ARexx 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 (I will not comment on the quality of that system) and ported to the Amiga by William S. Hawes. ARexx (or Amiga Rexx) is a commercial product, that 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. The german version was published by the `Carl Hanser Verlag', the english version is probably available from Prentice-Hall. `term' opens an ARexx host with the name "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 name of the host is also displayed in the title bar of the `term' main screen. Currently, 44 commands are implemented, which can be divided into two classes: - Asynchronous commands, which will be executed at once and do not force the executing program to wait. - Synchronous commands, that are executed by `term' itself. This might make it neccessary for the ARexx-program to wait for the completion of the command. ========================= Asynchronous Commands =========================== =========================================================================== CLEARDISPLAY........... Deletes the contents of the logbook. CLOSEDISPLAY........... Closes the logbook window, but keeps the contents. DEFAULT2FRONT.......... Brings the default screen to the front. This is usually the workbench screen. REXX2FRONT............. Pops the screen that contains the ARexx-output window to the front. DISPLAY2FRONT.......... Pops the logbook-screen to the front. TERM2FRONT............. Brings the main term program screen to the front. WB2FRONT............... Brings the WB-screen to the front. CLEARDOWNLOADLIST...... The list of received files is deleted. QUERY.................. Ask for several system parameters. As this command is rather complex, it will be described later. QUIETEXIT.............. The output window is closed right away after completion. Usually, it waits for the user to confirm the action. =========================== The `QUERY' Command =========================== =========================================================================== The following parameters can be queried with the `QUERY' command: Example: query baudrate ADOWNLOADPATH.......... The name of the ASCII-Download directory. AUPLOADPATH............ The name of the ASCII-Upload directory. AUDBELL................ `ON' when set to accoustic signal for the `Bell' characters, otherwise `OFF'. AUTOCAPTURE............ `ON' if term automatically creates a capture file upon Connect, otherwise `OFF' BAUDRATE............... The current transfer speed between computer and modem. BEEPSOUND.............. The name of the IFF-sound which will be played instead of the default Bell-signal. BITSPERCHAR............ The number of bits per character. BLINKING............... `ON' if the blinking of the terminal is turned on. BREAKLENGTH............ Length of the break signal. (1 million micro- seconds = 1 second) BDOWNLOADPATH.......... Name of the binary download directory. BUPLOADPATH............ Name of the binary upload directory. BUSY................... The character sequence sent by the modem when a busy line is recognized. CAPTUREFILTER.......... When `ON', control sequences won't be saved in the capture file. CAPTUREPATH............ Directory, in which the capture files will be saved. CAPTURESTATE........... The result will contain the mode of the capture: `PRINTER' if the capture is printed, `FILE' if it is sent to a file. A combination of both is possible when both modes are activated, and `OFF' is returned when neither of the two is turned on. CHARACTERWRAP.......... `ON' if automatic line wrap is turned on. COLOUR................. This command will return the hex-value of a certain colour (e.g. `query colour 12'). COLOURMODE............. The screen mode currently active (AMIGA, EIGHT, SIXTEEN, MONO). COLUMNS................ The number of characters per line. CONNECT................ The result code return from the modem when a connection was successfully created. CONNECTAUTOBAUD........ `ON' when the transfer rate between modem and computer is calculated automatically upon connecting. CURSOR................. Position of the cursor. The resulting string contains the X- and Y-position separated by a SPACE. CURSORMODE............. The mode the cursor keys are interpreted in. (`STANDARD' or `APPLICATION'). CURSORWRAP............. `ON' if the cursor can be moved without being stopped at screen boundaries. DEFAULTSTORE........... The name of the directory, where all config-files are stored in. DIALPREFIX............. The part of the command sequence sent to the modem preceding the number. DIALRETRIES............ The maximum number of dial retries. DIALTIMEOUT............ The number of seconds term waits for a connection after sending the dial string. DISPLAYMODE............ The screen displaymode term operates in (HIRES, HIRESLACE, SUPERHIRES, SUPERHIRESLACE, PRODUCT, PRODUCTLACE, PALHIRES, PALHIRESLACE, PALSUPERHIRES, PALSUPERHIRESLACE, NTSCHIRES, NTSCHIRESLACE, NTSCSUPERHIRES, NTSCSUPERHIRESLACE, A2024TENHZ, A2024FIFTEENHZ). DOWNLOADS.............. The number of files downloaded. DSBACKSPACE............ Destructive backspace. If `ON', a Backspace character will also delete the character left of the cursor position. DUPLEX................. Transfermode. Either `FULL' or `HALF'. EDITOR................. Name of the editor used when calling the `Edit File' function. EIGHTYCOLUMNS.......... `ON' if the screen is set to 80 × 24 characters. EMULATION.............. The currently active terminal emulation (ANSIVT, ATOMIC,TTY). ERROR.................. The result code sent by the modem when an error has occurred. FONT................... The font used (TOPAZ, IBM). FONTSCALE.............. Size of the font (`NORMAL', `HIGHTOP', `HIGHBOTTOM', `WIDE', `HALF'). HANDSHAKING............ The handshake mode used (XONXOFF, RTSCTS, NONE). HIGHSPEED.............. `ON' if the high speed mode of the serial device is turned on. INSERTMODE............. `ON' if term is currently using the insert mode. LINE................... `ON' if a there is a connection to another modem. LINES.................. The number of lines displayed on the screen. LOGACTIONS............. `ON' if all actions of term are logged in a logfile. LOGFILE................ Name of the logfile for `LOGACTIONS'. MACRO.................. Given the two arguments Qualifier (None, Shift, Alternate, Control) and the number of a function key, this function will return the definition for that key. (e.g.: `query macro none 0'). MACROFILE.............. The name of the currently used function key definition file. MODEMEXIT.............. The command sequence sent to the modem before term terminates. MODEMHANGUP............ The command sequence sent to the modem to end a connection. MODEMINIT.............. The command sequence sent to the modem to initialize it. NOCARRIER.............. The string sent by the modem when the connection terminates. NEWLINEMODE............ `ON' if term operates in the `New Line' mode. NUMERICMODE............ The mode the numeric keypad operates in (`STANDARD', `APPLICATIONS'). OKAY................... The string returned by the modem when a command was successfully executed. PARITY................. The current parity mode (NONE, EVEN, ODD, MARK, SPACE). PROTOCOL............... The transfer protocoll currently defined (e.g. xprzmodem.library, xprxmodem.library, etc.). PROTOCOLOPTIONS........ The options set for the current protocoll. Check the libraries' docs for information on each option. PUBLICSCREEN........... `ON' if term's main screen was opened as a public screen. REDIALDELAY............ The delay term waits after an unsuccessful dial before it tries again. REQUESTERS............. `ON' if requesters are displayed for the user to confirm certain actions. RING................... The string sent by the modem when an incoming call is detected. SCREENADDRESS.......... Returns the address of the `term' main screen as a decimal number. SENDCR................. Send a Carriage Return as line delimiter (IGNORE, ASCR, ASCRLF). SENDLF................. Send a Line Feed as line delimiter (IGNORE, ASLF, ASLFCR). SERIAL................. ON if the serial device is still opened by term, OFF if it has been closed. SERIALDEVICE........... The name of the serial driver. SHANGHAI............... ON if windows normally opened on the Workbench are opened on term's screen. SMOOTHSCROLL........... ON if the screen is scrolled a quarter line at a time. SPEECHFILE............. The name of the current speech configuration file. SPEECH................. ON if the speech synthesizer supplied by `term' has been activated, else OFF. SPEECHRATE............. Returns the speaking speech in words per minute. SPEECHPITCH............ The speech pitch used by the speech synthesizer. SPEECHFREQUENCY........ The speech frequency used by the speech synthesizer. SPEECHVOLUME........... The speech volume used by the speech synthesizer. SPEECHSEX.............. The sex of the voice used by the speech synthesizer (either MALE or FEMALE). STARTUP................ The command sequence executed upon startup of term (or whatever the last connection left in this field). STATUS................. The main status of term (READY, HOLDING, DIALING, UPLOAD, DOWNLOAD, BREAKING, HANGUP). STOPBITS............... The number of stopbits sent. TIMEOUT................ The number of microseconds waited after starting the `INPUT'-command before it is aborted due to a timeout. TDOWNLOADPATH.......... The name of the directory in which received text files will be stored. TUPLOADPATH............ The path to the directory to be used when uploading a text file. TONEDIAL............... Will play a telephone number on the Amiga audio hardware using touch-tone signal encoding. UNITNUMBER............. The unit of the serial device to be used. VISBELL................ ON if a visual signal is to be used when a BELL char is displayed. VOICE.................. The message sent by the modem when a call has been detected that does not come from another modem. ========================== Synchronous Commands =========================== =========================================================================== BDOWNLOAD.............. Starts a download of a binary file. A filename is expected, but not needed for protocols like ZModem. BEEP................... Displays a BEEP signal, like a sound or screen flash. BREAK.................. Sends a BREAK signal over to the modem. BUFFER................. Initiates different logbook actions. `buffer new file' uses `file' for logging. An existing `file' is replaced. `set buffer append file' appends all following logbook actions to the `file'. `buffer display' will display the current logbook. BUPLOAD................ Starts a binary upload. A filename has to be supplied, otherwise the transfer protocol will complain. Only a single filename may be given, for multiple uploads check the wildcard-options. CAPTURE................ Changes the capture options. `capture close' closes the current capture file. `capture new file' replaces the `file' with the new capture. `capture append file' appends the new capture to the `file'. CLEARSCREEN............ Clears the screen (hey, that was simple!). COMMAND................ Sends a command sequence over the serial line. CONFIG................. Saves or restores the konfiguration (`config save file' to save as `file', `config load file' to load `file'). DELAY.................. Suspends script execution for a certain time. There is now way to stop this command, so you shouldn't use to long delays. The delay may be given in microseconds, seconds or minutes: delay 10 mic -> waits ten microseconds delay 10 sec -> waits ten seconds delay 10 min -> waits ten minutes DIAL................... Dials a number. You may also use a name from the phonebook. If a matching entry is found, its number is dialed. Please note: This command only sends the dial command to the modem. Handling of the result has to be done seperately! FILEREQUEST............ Displays a file requester asking the user to select a file. The text passed to this routine will be displayed in the title bar of the file requester window. FIRSTDOWNLOAD.......... The names of all files downloaded during a batch download is kept in a list that can be accessed via ARexx. This command returns the name of the first file in the list. GETCLIP................ Gets the contents of the clipboard and returns it as a string. GETSTRING.............. Queries a string from the user. HANGUP................. Closes the current connection (if exists) by sending the hangup-command to the modem. INPUT.................. Reads a certain number of chars (given when calling the function) from the port. If the `set timeout' command has been used, this function will return either after receiving enough chars, or when the timeout is reached. LASTDOWNLOAD........... The names of all files downloaded during a batch download is kept in a list that can be accessed via ARexx. This command returns the name of the last file in the list. MACROS................. Either saves or loads the current function key bindings. (`macros save file' or `macros load file') MESSAGE................ Displays a text. This text is not sent over the serial line! NEXTDOWNLOAD........... The names of all files downloaded during a batch download is kept in a list that can be accessed via ARexx. This command returns the name of the next file in the list. Before using this command, either `FIRSTDOWNLOAD' or `LASTDOWNLOAD' must have been called! PHONE.................. Saves or loads the current phonebook. (`phone save file' or `phone load file') PRINTER................ Turns the logfile-printing on (`printer on') or off (`printer off'). PUTCLIP................ Stores a string in the clipboard. RESETSTYLES............ Restores the terminal emulation to standard, turning all special attributes off. SAVEILBM............... Saves the current screen as an IFF-ILBM-file (filename to be given by the script). SET.................... Sets system parameters. Please check a couple lines down for more information. SIMPLEREQUEST.......... Displays a simple information requester, such as the one used by `term' when it fails to open the serial driver. SPEAK.................. Speaks a text using the `term' speech synthesizer. Note that this feature requires the synthesizer to be enabled. SPEECH................. Either saves or loads the current speech synthesizer settings (`speech save file' or `speech load file'). TDOWNLOAD.............. Starts a download (as with BDOWNLOAD), but expects an ASCII-file (like a capture..) TUPLOAD................ Same as TDOWNLOAD, but sends a text file. TWOGADREQUEST.......... Displays a simple `Yes/No' choice requester and returns the user's selection (YES or NO). WAITSTRING............. Waits for a certain string to appear from the other side of the line. You can have `term' to wait for almost infinite numbers of different strings. If one of the strings is recognized, it will be returned as result. Case is insignificant. The global timeout is used here, too (e.g. set it with `set timeout 10 sec'). If the given timeout has gone by without a correct string appearing, this command will return. I'd advise _everybody_ to use the timeout, or `term' will _really_ wait, even if it takes years for the string to appear... Example: waitstring "logon: " WRITE.................. Sends the string to the port, but won't display it on term's screen. ============================ The `SET'-Command ============================ =========================================================================== Generally speaking, the `Set' command is the exact opposite of the `Query' command. Every parameter that `Query' takes as an input can be used with `Set' to change that option. For example, `query baudrate' might return `2400', while `set baudrate 2400' would change it. As the author of these lines is currently suffering from back pains, and as he doesn't feel to good after a `Non-Stop-Tour-De-Force- Programming-Marathon', he (that is me) will only note the differences here. Please check the `Query' description for further information. BELL................... Sets the parameters of the Display of the `Bell'-char. Currently, the paramters `AUDIBLE' and `VISIBLE' are recognized. COLOUR................. Changes a colour. The first parameter is the number of the colour (0 through 15), the second the hex-value of the colour. MACRO.................. Sets one of the function keys' binding. The name of the qualifier (none, shift, alternate, control) and the number of the key (0-9), plus the new contents of that key will be needed as parameters. Example: set macro none 0 hello! SCREEN................. This command is the opposite of the two options `PUBLICSCREEN' and `SHANGHAI' (see the Query-command). These two options may be given as parameters. TIMEOUT................ Sets the global timeout. All read-functions will wait this time at most before being canceled. The time can be given as with DELAY, that is microseconds, seconds and minutes. Example: set timeout 10 sec Please note: the Query-options `line', `lines', `columns', `status', `cursor', `downloads' and `beepsound' do not have a counterpiece. Up to now, it is not possible to change the quality of the line and the physical size of the screen via software (if anybody can prove the opposite, please send me the source code!). Positioning of the cursor should rather be done by using control sequences instead of changing internal counters... =============================== Disclaimer ================================ =========================================================================== This text was translated to english by G. Glendown. I have tried to keep it as exact as possible. Also, I have re-read it a couple times to find as many typos as possible. Please forgive me if I didn't succeed in finding 'em all...