\documentstyle{article}

\begin{document}
\newcounter{bean}

\newenvironment{defit}[1]{\begin{list}%
{$\bullet$}{\usecounter{bean}
	\settowidth{\labelwidth}{#1}
	\setlength{\leftmargin}{\labelwidth}
	\addtolength{\leftmargin}{\labelsep}
}}{\end{list}}

\title{TERM \& AREXX}
\author{0laf Barthel}

\maketitle

\centerline{A Gift-Ware telecommunications program written by}
\centerline{Olaf Barthel, © copyright 1990-92 by Olaf Barthel \& MXM,}
\centerline{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.

\newpage\tableofcontents

\newpage\section{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 `TERM1',  the
third  one  `TERM2',  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:

\begin{enumerate}

\item Asynchronous  commands,  which  will be executed at once and do not force
  the executing program to wait.

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

\end{enumerate}


\section{Asynchronous Commands}

\begin{defit}{\bf CLEARD0WNL0ADLIST~~~~}

\item[\bf CLEARDISPLAY\hfill] Deletes the contents of the logbook.

\item[\bf CLOSEDISPLAY\hfill] Closes the logbook window, but keeps the contents.

\item[\bf DEFAULT2FRONT\hfill] Brings  the  default  screen to the front.  This is
                        usually the workbench screen.

\item[\bf REXX2FRONT\hfill] Pops  the  screen  that  contains  the ARexx-output
                        window to the front.

\item[\bf DISPLAY2FRONT\hfill] Pops the logbook-screen to the front.

\item[\bf TERM2FRONT\hfill] Brings the main term program screen to the front.

\item[\bf WB2FRONT\hfill] Brings the WB-screen to the front.

\item[\bf CLEARDOWNLOADLIST\hfill] The list of received files is deleted.

\item[\bf QUERY\hfill] Ask for several system parameters.  As this command
                        is rather complex, it will be described later.

\item[\bf QUIETEXIT\hfill] The  output  window  is  closed  right  away  after
                        completion.   Usually,  it  waits  for  the user to
                        confirm the action.
\end{defit}

\section{The `QUERY' Command}

The following parameters can be queried with the `QUERY' command:

   Example: query baudrate

\begin{defit}{\bf CONNECTAUTOBAUD~~~}

\item[\bf ADOWNLOADPATH\hfill] The name of the ASCII-Download directory.

\item[\bf AUPLOADPATH\hfill] The name of the ASCII-Upload directory.

\item[\bf AUDBELL\hfill] `ON'  when  set  to accoustic signal for the `Bell'
                        characters, otherwise `OFF'.

\item[\bf AUTOCAPTURE\hfill] `ON'  if  term automatically creates a capture file
                        upon Connect, otherwise `OFF'

\item[\bf BAUDRATE\hfill] The  current  transfer  speed  between computer and
                        modem.

\item[\bf BEEPSOUND\hfill] The  name  of  the  IFF-sound  which will be played
                        instead of the default Bell-signal.

\item[\bf BITSPERCHAR\hfill] The number of bits per character.

\item[\bf BLINKING\hfill] `ON' if the blinking of the terminal is turned on.

\item[\bf BREAKLENGTH\hfill] Length  of  the  break  signal.   (1 million micro-
                        seconds = 1 second)

\item[\bf BDOWNLOADPATH\hfill] Name of the binary download directory.

\item[\bf BUPLOADPATH\hfill] Name of the binary upload directory.

\item[\bf BUSY\hfill] The  character  sequence  sent  by the modem when a
                        busy line is recognized.

\item[\bf CAPTUREFILTER\hfill] When  `ON', control sequences won't be saved in the
                        capture file.

\item[\bf CAPTUREPATH\hfill] Directory,  in  which  the  capture  files  will be
                        saved.

\item[\bf CAPTURESTATE\hfill] 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.

\item[\bf CHARACTERWRAP\hfill] `ON' if automatic line wrap is turned on.

\item[\bf COLOUR\hfill] This command will return the hex-value of a certain
                        colour (e.g. `query colour 12').

\item[\bf COLOURMODE\hfill] The  screen  mode  currently  active (AMIGA, EIGHT,
                        SIXTEEN, MONO).

\item[\bf COLUMNS\hfill] The number of characters per line.

\item[\bf CONNECT\hfill] The  result  code  return  from  the  modem  when a
                        connection was successfully created.

\item[\bf CONNECTAUTOBAUD\hfill] `ON'  when  the  transfer  rate  between  modem and
                        computer    is    calculated   automatically   upon
                        connecting.

\item[\bf CURSOR\hfill] Position  of  the  cursor.   The  resulting  string
                        contains  the  X-  and  Y-position  separated  by a
                        SPACE.

\item[\bf CURSORMODE\hfill] The  mode  the  cursor  keys  are  interpreted  in.
                        (`STANDARD' or `APPLICATION').

\item[\bf CURSORWRAP\hfill] `ON'  if  the  cursor  can  be  moved without being
                        stopped at screen boundaries.

\item[\bf DEFAULTSTORE\hfill] The  name  of the directory, where all config-files
                        are stored in.

\item[\bf DIALPREFIX\hfill] The  part of the command sequence sent to the modem
                        preceding the number.

\item[\bf DIALRETRIES\hfill] The maximum number of dial retries.

\item[\bf DIALTIMEOUT\hfill] The  number  of seconds term waits for a connection
                        after sending the dial string.

\item[\bf DISPLAYMODE\hfill] The  screen  displaymode  term  operates in (HIRES,
                        HIRESLACE,   SUPERHIRES,  SUPERHIRESLACE,  PRODUCT,
                        PRODUCTLACE, PALHIRES, PALHIRESLACE, PALSUPERHIRES,
                        PALSUPERHIRESLACE,     NTSCHIRES,    NTSCHIRESLACE,
                        NTSCSUPERHIRES,   NTSCSUPERHIRESLACE,   A2024TENHZ,
                        A2024FIFTEENHZ).

\item[\bf DOWNLOADS\hfill] The number of files downloaded.

\item[\bf DSBACKSPACE\hfill] Destructive   backspace.    If  `ON',  a  Backspace
                        character  will  also  delete the character left of
                        the cursor position.

\item[\bf DUPLEX\hfill] Transfermode. Either `FULL' or `HALF'.

\item[\bf EDITOR\hfill] Name  of  the  editor  used  when calling the `Edit
                        File' function.

\item[\bf EIGHTYCOLUMNS\hfill] `ON' if the screen is set to 80 × 24 characters.

\item[\bf EMULATION\hfill] The  currently  active  terminal emulation (ANSIVT,
                        ATOMIC,TTY).

\item[\bf ERROR\hfill] The result code sent by the modem when an error has
                        occurred.

\item[\bf FONT\hfill] The font used (TOPAZ, IBM).

\item[\bf FONTSCALE\hfill] Size    of    the    font   (`NORMAL',   `HIGHTOP',
                        `HIGHBOTTOM', `WIDE', `HALF').

\item[\bf HANDSHAKING\hfill] The handshake mode used (XONXOFF, RTSCTS, NONE).

\item[\bf HIGHSPEED\hfill] `ON' if the high speed mode of the serial device is
                        turned on.

\item[\bf INSERTMODE\hfill] `ON' if term is currently using the insert mode.

\item[\bf LINE\hfill] `ON' if a there is a connection to another modem.

\item[\bf LINES\hfill] The number of lines displayed on the screen.

\item[\bf LOGACTIONS\hfill] `ON'  if  all  actions  of  term  are  logged  in a
                        logfile.

\item[\bf LOGFILE\hfill] Name of the logfile for `LOGACTIONS'.

\item[\bf MACRO\hfill] 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').

\item[\bf MACROFILE\hfill] The   name  of  the  currently  used  function  key
                        definition file.

\item[\bf MODEMEXIT\hfill] The  command sequence sent to the modem before term
                        terminates.

\item[\bf MODEMHANGUP\hfill] The  command  sequence  sent  to the modem to end a
                        connection.

\item[\bf MODEMINIT\hfill] The   command   sequence   sent  to  the  modem  to
                        initialize it.

\item[\bf NOCARRIER\hfill] The  string  sent  by the modem when the connection
                        terminates.

\item[\bf NEWLINEMODE\hfill] `ON' if term operates in the `New Line' mode.

\item[\bf NUMERICMODE\hfill] The   mode   the   numeric   keypad   operates   in
                        (`STANDARD', `APPLICATIONS').

\item[\bf OKAY\hfill] The string returned by the modem when a command was
                        successfully executed.

\item[\bf PARITY\hfill] The  current  parity  mode  (NONE, EVEN, ODD, MARK,
                        SPACE).

\item[\bf PROTOCOL\hfill] The  transfer  protocoll  currently  defined  (e.g.
                        xprzmodem.library, xprxmodem.library, etc.).

\item[\bf PROTOCOLOPTIONS\hfill] The  options  set for the current protocoll.  Check
                        the libraries' docs for information on each option.

\item[\bf PUBLICSCREEN\hfill] `ON'  if  term's main screen was opened as a public
                         screen.

\item[\bf REDIALDELAY\hfill] The  delay  term  waits  after an unsuccessful dial
                        before it tries again.

\item[\bf REQUESTERS\hfill] `ON'  if  requesters  are displayed for the user to
                        confirm certain actions.

\item[\bf RING\hfill] The  string sent by the modem when an incoming call
                        is detected.

\item[\bf SCREENADDRESS\hfill] Returns  the address of the `term' main screen as a
                        decimal number.

\item[\bf SENDCR\hfill] Send  a  Carriage Return as line delimiter (IGNORE,
                        ASCR, ASCRLF).

\item[\bf SENDLF\hfill] Send  a  Line Feed as line delimiter (IGNORE, ASLF,
                        ASLFCR).

\item[\bf SERIAL\hfill] ON  if  the  serial device is still opened by term,
                        OFF if it has been closed.

\item[\bf SERIALDEVICE\hfill] The name of the serial driver.

\item[\bf SHANGHAI\hfill] ON  if windows normally opened on the Workbench are
                        opened on term's screen.

\item[\bf SMOOTHSCROLL\hfill] ON  if  the  screen is scrolled a quarter line at a
                        time.

\item[\bf SPEECHFILE\hfill] The name of the current speech configuration file.

\item[\bf SPEECH\hfill] ON if the speech synthesizer supplied by `term' has
                        been activated, else OFF.

\item[\bf SPEECHRATE\hfill] Returns the speaking speech in words per minute.

\item[\bf SPEECHPITCH\hfill] The speech pitch used by the speech synthesizer.

\item[\bf SPEECHFREQUENCY\hfill] The   speech   frequency   used   by   the   speech
                        synthesizer.

\item[\bf SPEECHVOLUME\hfill] The speech volume used by the speech synthesizer.

\item[\bf SPEECHSEX\hfill] The sex of the voice used by the speech synthesizer
                        (either MALE or FEMALE).

\item[\bf STARTUP\hfill] The  command sequence executed upon startup of term
                        (or  whatever  the  last  connection  left  in this
                        field).

\item[\bf STATUS\hfill] The  main  status of term (READY, HOLDING, DIALING,
                        UPLOAD, DOWNLOAD, BREAKING, HANGUP).

\item[\bf STOPBITS\hfill] The number of stopbits sent.

\item[\bf TIMEOUT\hfill] The  number  of  microseconds waited after starting
                        the  `INPUT'-command  before it is aborted due to a
                        timeout.

\item[\bf TDOWNLOADPATH\hfill] The  name  of  the directory in which received text
                        files will be stored.

\item[\bf TUPLOADPATH\hfill] The path to the directory to be used when uploading
                        a text file.

\item[\bf TONEDIAL\hfill] Will  play  a  telephone  number on the Amiga audio
                        hardware using touch-tone signal encoding.

\item[\bf UNITNUMBER\hfill] The unit of the serial device to be used.

\item[\bf VISBELL\hfill] ON  if  a  visual  signal is to be used when a BELL
                        char is displayed.

\item[\bf VOICE\hfill] The  message sent by the modem when a call has been
                        detected that does not come from another modem.

\end{defit}

\section{Synchronous Commands}

\begin{defit}{\bf TWOGADREQUEST~~~}

\item[\bf BDOWNLOAD\hfill] Starts  a download of a binary file.  A filename is
                        expected, but not needed for protocols like ZModem.

\item[\bf BEEP\hfill] Displays  a  BEEP signal,  like  a  sound or screen
                        flash.

\item[\bf BREAK\hfill] Sends a BREAK signal over to the modem.

\item[\bf BUFFER\hfill] 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.

\item[\bf BUPLOAD\hfill] 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.

\item[\bf CAPTURE\hfill] 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'.

\item[\bf CLEARSCREEN\hfill] Clears the screen (hey, that was simple!).

\item[\bf COMMAND\hfill] Sends a command sequence over the serial line.

\item[\bf CONFIG\hfill] Saves  or  restores the konfiguration (`config save
                        file' to save as `file', `config load file' to load
                        `file').

\item[\bf DELAY\hfill] 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:

\begin{tabular}{lcl}
delay 10 mic & \verb+->+ & waits ten microseconds   \\
delay 10 sec & \verb+->+ & waits ten seconds        \\
delay 10 min & \verb+->+ & waits ten minutes        \\
\end{tabular}

\item[\bf DIAL\hfill] 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!

\item[\bf FILEREQUEST\hfill] 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.

\item[\bf FIRSTDOWNLOAD\hfill] 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.

\item[\bf GETCLIP\hfill] Gets  the  contents of the clipboard and returns it
                        as a string.

\item[\bf GETSTRING\hfill] Queries a string from the user.

\item[\bf HANGUP\hfill] Closes   the  current  connection  (if  exists)  by
                        sending the hangup-command to the modem.

\item[\bf INPUT\hfill] 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.

\item[\bf LASTDOWNLOAD\hfill] 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.

\item[\bf MACROS\hfill] Either  saves  or  loads  the  current function key
                        bindings.  (`macros  save  file'  or  `macros  load
                        file')

\item[\bf MESSAGE\hfill] Displays  a  text.   This text is not sent over the
                        serial line!

\item[\bf NEXTDOWNLOAD\hfill] 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!

\item[\bf PHONE\hfill] Saves or loads the current phonebook.  (`phone save
                        file' or `phone load file')

\item[\bf PRINTER\hfill] Turns the logfile-printing on (`printer on') or off
                        (`printer off').

\item[\bf PUTCLIP\hfill] Stores a string in the clipboard.

\item[\bf RESETSTYLES\hfill] Restores   the   terminal  emulation  to  standard,
                        turning all special attributes off.

\item[\bf SAVEILBM\hfill] Saves   the  current  screen  as  an  IFF-ILBM-file
                        (filename to be given by the script).

\item[\bf SET\hfill] Sets  system  parameters.   Please  check  a couple
                        lines down for more information.

\item[\bf SIMPLEREQUEST\hfill] Displays  a  simple  information requester, such as
                        the  one  used  by `term' when it fails to open the
                        serial driver.

\item[\bf SPEAK\hfill] Speaks  a text using the `term' speech synthesizer.
                        Note  that this feature requires the synthesizer to
                        be enabled.

\item[\bf SPEECH\hfill] Either   saves   or   loads   the   current  speech
                        synthesizer settings (`speech save file' or `speech
                        load file').

\item[\bf TDOWNLOAD\hfill] Starts  a download (as with BDOWNLOAD), but expects
                        an ASCII-file (like a capture..)

\item[\bf TUPLOAD\hfill] Same as TDOWNLOAD, but sends a text file.

\item[\bf TWOGADREQUEST\hfill] Displays  a  simple  `Yes/No'  choice requester and
                        returns the user's selection (YES or NO).

\item[\bf WAITSTRING\hfill] 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: "

\item[\bf WRITE\hfill] Sends  the string to the port, but won't display it
                        on term's screen.

\end{defit}

\section{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.

\begin{defit}{\bf TIME0UT~~~}

\item[\bf BELL\hfill] Sets   the   parameters   of  the  Display  of  the
                        `Bell'-char.   Currently,  the  paramters `AUDIBLE'
                        and `VISIBLE' are recognized.

\item[\bf COLOUR\hfill] Changes a colour. The first parameter is the number
                        of  the  colour  (0  through  15),  the  second the
                        hex-value of the colour.

\item[\bf MACRO\hfill] 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!

\item[\bf SCREEN\hfill] This  command  is  the  opposite of the two options
                        `PUBLICSCREEN'     and    `SHANGHAI'    (see    the
                        Query-command).   These two options may be given as
                        parameters.

\item[\bf TIMEOUT\hfill] 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

\end{defit}

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


\section{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...


\section{An author's request \& gift-\-ware-\-remuneration}

The  development  of  `term'  required conciderable expense.  The effort to
find  out  by  trial and error and with a little help from the DevCon-Disks
and the Includes \& Autodocs the operating principles of some routines would
alone  be  worth  a remuneration to the author (it's simply bad luck if the
Atlanta-DevCon records arrive with considerable delay).
   The  author is susceptible to all kinds of donation and gifts so long as
it  is  assured  that  they are useful to him (these nice little sacks with
elephant  food  are  better  sent  to  the Hannover zoo).  Therefore anyone
pleased  by  `term'  or  who  works  with  the  source  code  is welcome to
remunerate  my  programming  efforts  as  he/she  thinks that it matches my
efforts (If you've got no ideas yet:  I am looking for old Infocom games --
with  the  exception  of  `Zork Zero,I,II \& III' `Journey', `A mind forever
voyaging', `Hollywood Hijinx', `Wishbringer' and `The lurking horror' which
I already own -- old CinemaWare games -- with the exception of `Defender of
the Crown' and `Sinbad' -- the source code to `ARJ' or a Modula-2 compiler)
- a lot of thanks!

\begin{center}
                                My address:

                               Olaf Barthel
                             Brabeckstrasse 35
                            D-3000 Hannover 71

                        Federal Republic of Germany

\begin{defit}{\bf Usenet~~}

\item[\bf Z-Net\hfill] O.BARTHEL@A-Link-H

\item[\bf Usenet\hfill] o.barthel@a-link-h.zer.sub.org \\

                          cbmvax.commodore.com!cbmehq!sourcery!olsen
\end{defit}
\end{center}

   Would  those  people  looking at the source code to extend it or do some
modifications  here  and there please contact me before publication so that
our efforts can be coordinated.
   If  someone  should  have  a  brilliant  idea  to  improve or extend the
structure and contents of this manual, he/she may do it with my blessing (I
haven't had the enthusiasm up to now to \TeX ify the text).

\end{document}
