Amiga Elysian Archive/AmigaElysianArchive.iso/comm/term23_1.lha/termRexx.doc

Text File | 1992-08-23 | 18KB | 609 lines

Copyright (C) 1990-1992 Olaf Barthel und MXM



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 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.

   `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 name of the host is
also displayed in the title bar of the `term' main screen.

   Currently, 47 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 text buffer screen to the front.

`TERM2FRONT'
     Brings the main term program screen to the front.

`WB2FRONT'
     Brings the Workbench 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.


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 text buffer.

`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.

`COMMAND'
     Sends a command sequence over the serial line.

`CONFIG'
     Saves or restores the configuration (`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').

`TERMEXIT'
     Terminates the program, just as if one had selected the `Quit' menu
     item in the main menu.

`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 Query command
******************

   The following parameters can be queried with the `QUERY' command
(for 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 microseconds = 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 blank 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 & upload file'
     function.

`EIGHTYCOLUMNS'
     `ON' if the screen is set to 80 x 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.


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 character.
     Currently, the parameters `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...