\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename termRexx-english.guide
@settitle A terminal program for Amiga computers
@c %**end of header

@c $VER: termRexx.texinfo 1.4 (1.10.92)

@setchapternewpage odd
@finalout

@ifinfo
Copyright @copyright{} 1990-1992 Olaf Barthel und MXM
@end ifinfo

@titlepage
@title term
@subtitle A terminal program for Amiga computers
@sp 1
@subtitle ARexx-interface and ARexx-commands explained
@subtitle 1 October 1992
@author by Olaf Barthel
@page
@vskip 0pt plus1filll
Copyright @copyright{} 1990-1992 Olaf Barthel und MXM

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:

@enumerate

@item
The construction, development, production or testing of weapons or weapon
systems of any kind.

@item
The construction, development, production or use of plants/installations which
include the processing of radioactive/fissionable material.

@item
The training of persons to deal with the abovesaid actions.

@end enumerate

`term' may be included with commercial programs as long as no money is made by
including it in the distribution (this also applies to inclusion in AmigaDOS
Enhancer kits, on Workbench/Extras disks or A3x00 hard disk drives).

You @emph{must not} make any money by distributing `term'.  A small copy fee for
data media (US$ 5 maximum) or the inclusion of `term' in Public-Domain
collections such as Fred Fish's Amiga Library of Freely Distributable Software
is permitted though.

@end titlepage
@page


@node Top, term and ARexx, (dir), (dir)

@menu
* term and ARexx::		A brief introduction
* Asynchronous commands::	A table of all asynchronous commands
* Synchronous commands::	A table of all synchronous commands
* The Query command::		The Query command and its parameters
* The Set command::		The Set command and its parameters
* Disclaimer::			Notes on the translation of this
				document
* Index::			Contents index
@end menu


@node term and ARexx, Asynchronous commands, Top, Top
@chapter 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 @cite{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 @kbd{TERM} (accessable via
@kbd{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 @kbd{TERM},
the second one will use @kbd{TERM.1}, the third one @kbd{TERM.2},
etc.).  The name of the host is also displayed in the title bar of
the `term' main screen.

Currently, 46 commands are implemented, which can be divided into
two classes:

@itemize @bullet

@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 itemize


@node Asynchronous commands, Synchronous commands, term and ARexx, Top
@chapter Asynchronous commands

@ftable @samp

@item CLEARDISPLAY
Deletes the contents of the logbook.

@item CLOSEDISPLAY
Closes the logbook window, but keeps the contents.

@item DEFAULT2FRONT
Brings the default screen to the front.  This is usually the
workbench screen.

@item REXX2FRONT
Pops the screen that contains the ARexx-output window to the front.

@item DISPLAY2FRONT
Pops the text buffer screen to the front.

@item TERM2FRONT
Brings the main term program screen to the front.

@item WB2FRONT
Brings the Workbench screen to the front.

@item CLEARDOWNLOADLIST
The list of received files is deleted.

@item QUERY
Ask for several system parameters.  As this command is rather
complex, it will be described later.

@item QUIETEXIT
The output window is closed right away after completion.  Usually,
it waits for the user to confirm the action.

@end ftable


@node Synchronous commands, The Query command, Asynchronous commands, Top
@chapter Synchronous commands

@ftable @samp

@item BDOWNLOAD
Starts a download of a binary file.  A filename is expected, but not
needed for protocols like ZModem.

@item BEEP
Displays a `beep' signal, like a sound or screen flash.

@item BREAK
Sends a break signal over to the modem.

@item BUFFER
Initiates different logbook actions.  @code{buffer new file} uses
@samp{file} for logging.  An existing @samp{file} is replaced.
@code{set buffer append file} appends all following logbook actions
to the @samp{file}.  @code{buffer display} will display the current
text buffer.

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

@item CAPTURE
Changes the capture options.  @code{capture close} closes the current
capture file.  @code{capture new file} replaces the @samp{file} with
the new capture.  @code{capture append file} appends the new capture
to the @samp{file}.

@item CLEARSCREEN
Clears the screen.

@item COMMAND
Sends a command sequence over the serial line.

@item CONFIG
Saves or restores the configuration (@code{config save file} to save as
@samp{file}, @code{config load file} to load @samp{file}).

@item 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:

@ftable @samp

@item delay 10 mic
Waits ten microseconds

@item delay 10 sec
Waits ten seconds

@item delay 10 min
Waits ten minutes

@end ftable

@item 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!

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

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

@item GETCLIP
Gets the contents of the clipboard and returns it as a string.

@item GETSTRING
Queries a string from the user.

@item HANGUP
Closes the current connection (if exists) by sending the
hangup-command to the modem.

@item INPUT
Reads a certain number of chars (given when calling the function)
from the port.  If the @code{set timeout} command has been used, this
function will return either after receiving enough chars, or when
the timeout is reached.

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

@item MACROS
Either saves or loads the current function key bindings (@code{macros
save file} or @code{macros load file}).

@item MESSAGE
Displays a text.  This text is not sent over the serial line!

@item 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 @code{firstdownload} or @code{lastdownload} must have been called!

@item PHONE
Saves or loads the current phonebook (@code{phone save file} or @code{phone
load file}).

@item PRINTER
Turns the logfile-printing on (@code{printer on}) or off (@code{printer
off}).

@item PUTCLIP
Stores a string in the clipboard.

@item RESETSTYLES
Restores the terminal emulation to standard, turning all special
attributes off.

@item SAVEILBM
Saves the current screen as an IFF-ILBM-file (filename to be given
by the script).

@item SET
Sets system parameters.  Please check a couple lines down for more
information.

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

@item SPEAK
Speaks a text using the `term' speech synthesizer.  Note that this
feature requires the synthesizer to be enabled.

@item SPEECH
Either saves or loads the current speech synthesizer settings
(@code{speech save file} or @code{speech load file}).

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

@item TDOWNLOAD
Starts a download (as with @samp{BDOWNLOAD}), but expects an ASCII-file
(like a capture).

@item TUPLOAD
Same as @samp{TDOWNLOAD}, but sends a text file.

@item TWOGADREQUEST
Displays a simple `Yes/No' choice requester and returns the user's
selection (@samp{YES} or @samp{NO}).

@item 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 @code{set timeout 10 sec}).  If the
given timeout has gone by without a correct string appearing, this
command will return.  I'd advise @emph{everybody} to use the
timeout, or `term' will @emph{really} wait, even if it takes years
for the string to appear...

Example: @code{waitstring "logon: "}

@item WRITE
Sends the string to the port, but won't display it on term's screen.


@end ftable


@node The Query command, The Set command, Synchronous commands, Top
@chapter The Query command

The following parameters can be queried with the @samp{QUERY}
command (for example @code{query baudrate}):

@ftable @samp

@item ADOWNLOADPATH
The name of the ASCII-Download directory.

@item AUPLOADPATH
The name of the ASCII-Upload directory.

@item AUDBELL
@samp{ON} when set to accoustic signal for the bell characters,
otherwise @samp{OFF}.

@item AUTOCAPTURE
@samp{ON} if term automatically creates a capture file upon Connect,
otherwise @samp{OFF}

@item BAUDRATE
The current transfer speed between computer and modem.

@item BEEPSOUND
The name of the IFF-sound which will be played instead of the
default bell signal.

@item BITSPERCHAR
The number of bits per character.

@item BLINKING
@samp{ON} if the blinking of the terminal is turned on.

@item BREAKLENGTH
Length of the break signal.  (1 million microseconds = 1 second)

@item BDOWNLOADPATH
Name of the binary download directory.

@item BUPLOADPATH
Name of the binary upload directory.

@item BUSY
The character sequence sent by the modem when a busy line is
recognized.

@item CAPTUREFILTER
When @samp{ON}, control sequences won't be saved in the capture file.

@item CAPTUREPATH
Directory, in which the capture files will be saved.

@item CAPTURESTATE
The result will contain the mode of the capture:  @samp{PRINTER} if the
capture is printed, @samp{FILE} if it is sent to a file.  A combination
of both is possible when both modes are activated, and @samp{OFF} is
returned when neither of the two is turned on.

@item CHARACTERWRAP
@samp{ON} if automatic line wrap is turned on.

@item COLOUR
This command will return the hex-value of a certain colour (e.g.
@code{query colour 12}).

@item COLOURMODE
The screen mode currently active (@samp{AMIGA}, @samp{EIGHT},
@samp{SIXTEEN}, @samp{MONO}).

@item COLUMNS
The number of characters per line.

@item CONNECT
The result code return from the modem when a connection was
successfully created.

@item CONNECTAUTOBAUD
@samp{ON} when the transfer rate between modem and computer is calculated
automatically upon connecting.

@item CURSOR
Position of the cursor.  The resulting string contains the X- and
Y-position separated by a blank space.

@item CURSORMODE
The mode the cursor keys are interpreted in.  (@samp{STANDARD} or
@samp{APPLICATION}).

@item CURSORWRAP
@samp{ON} if the cursor can be moved without being stopped at screen
boundaries.

@item DEFAULTSTORE
The name of the directory, where all config-files are stored in.

@item DIALPREFIX
The part of the command sequence sent to the modem preceding the
number.

@item DIALRETRIES
The maximum number of dial retries.

@item DIALTIMEOUT
The number of seconds term waits for a connection after sending the
dial string.

@item DISPLAYMODE
The screen displaymode term operates in (@samp{HIRES},
@samp{HIRESLACE}, @samp{SUPERHIRES}, @samp{SUPERHIRESLACE},
@samp{PRODUCT}, @samp{PRODUCTLACE}, @samp{PALHIRES},
@samp{PALHIRESLACE}, @samp{PALSUPERHIRES}, @samp{PALSUPERHIRESLACE},
@samp{NTSCHIRES}, @samp{NTSCHIRESLACE}, @samp{NTSCSUPERHIRES},
@samp{NTSCSUPERHIRESLACE}, @samp{A2024TENHZ}, @samp{A2024FIFTEENHZ}).

@item DOWNLOADS
The number of files downloaded.

@item DSBACKSPACE
Destructive backspace.  If @samp{ON}, a Backspace character will also
delete the character left of the cursor position.

@item DUPLEX
Transfermode.  Either @samp{FULL} or @samp{HALF}.

@item EDITOR
Name of the editor used when calling the `Edit & upload file' function.

@item EMULATION
The currently active terminal emulation (@samp{ANSIVT}, @samp{ATOMIC},
@samp{TTY}).

@item ERROR
The result code sent by the modem when an error has occurred.

@item FONT
The font used (@samp{TOPAZ}, @samp{IBM}).

@item FONTSCALE
Size of the font (@samp{NORMAL}, @samp{HIGHTOP}, @samp{HIGHBOTTOM},
@samp{WIDE}, @samp{HALF}).

@item HANDSHAKING
The handshake mode used (@samp{XONXOFF}, @samp{RTSCTS}, @samp{NONE}).

@item HIGHSPEED
@samp{ON} if the high speed mode of the serial device is turned on.

@item INSERTMODE
@samp{ON} if term is currently using the insert mode.

@item LINE
@samp{ON} if a there is a connection to another modem.

@item LINES
The number of lines displayed on the screen.

@item LOGACTIONS
@samp{ON} if all actions of term are logged in a logfile.

@item LOGFILE
Name of the logfile for @samp{LOGACTIONS}.

@item MACRO
Given the two arguments Qualifier (@kbd{None}, @kbd{Shift},
@kbd{Alternate}, @kbd{Control}) and the number of a function key,
this function will return the definition for that key.  (e.g.:
@code{query macro none 0}).

@item MACROFILE
The name of the currently used function key definition file.

@item MODEMEXIT
The command sequence sent to the modem before term terminates.

@item MODEMHANGUP
The command sequence sent to the modem to end a connection.

@item MODEMINIT
The command sequence sent to the modem to initialize it.

@item NOCARRIER
The string sent by the modem when the connection terminates.

@item NEWLINEMODE
@samp{ON} if term operates in the `New line' mode.

@item NUMERICMODE
The mode the numeric keypad operates in (@samp{STANDARD},
@samp{APPLICATIONS}).

@item OKAY
The string returned by the modem when a command was successfully
executed.

@item PARITY
The current parity mode (@samp{NONE}, @samp{EVEN}, @samp{ODD},
@samp{MARK}, @samp{SPACE}).

@item PROTOCOL
The transfer protocoll currently defined (e.g.
@file{xprzmodem.library}, @file{xprxmodem.library}, etc.).

@item PROTOCOLOPTIONS
The options set for the current protocoll.  Check the libraries'
docs for information on each option.

@item PUBLICSCREEN
@samp{ON} if term's main screen was opened as a public
screen.

@item REDIALDELAY
The delay `term' waits after an unsuccessful dial before it tries
again.

@item REQUESTERS
@samp{ON} if requesters are displayed for the user to confirm certain
actions.

@item RING
The string sent by the modem when an incoming call is detected.

@item SCREENADDRESS
Returns the address of the `term' main screen as a decimal number.

@item SENDCR
Send a carriage return as line delimiter (@samp{IGNORE}, @samp{ASCR},
@samp{ASCRLF}).

@item SENDLF
Send a line feed as line delimiter (@samp{IGNORE}, @samp{ASLF},
@samp{ASLFCR}).

@item SERIAL
@samp{ON} if the serial device is still opened by `term', @samp{OFF}
if it has been closed.

@item SERIALDEVICE
The name of the serial driver.

@item SHANGHAI
@samp{ON} if windows normally opened on the Workbench are opened on term's
screen.

@item SMOOTHSCROLL
@samp{ON} if the screen is scrolled a quarter line at a time.

@item SPEECHFILE
The name of the current speech configuration file.

@item SPEECH
@samp{ON} if the speech synthesizer supplied by `term' has been activated,
else @samp{OFF}.

@item SPEECHRATE
Returns the speaking speech in words per minute.

@item SPEECHPITCH
The speech pitch used by the speech synthesizer.

@item SPEECHFREQUENCY
The speech frequency used by the speech synthesizer.

@item SPEECHVOLUME
The speech volume used by the speech synthesizer.

@item SPEECHSEX
The sex of the voice used by the speech synthesizer (either
@samp{MALE} or @samp{FEMALE}).

@item STARTUP
The command sequence executed upon startup of term (or whatever the
last connection left in this field).

@item STATUS
The main status of term (@samp{READY}, @samp{HOLDING}, @samp{DIALING},
@samp{UPLOAD}, @samp{DOWNLOAD}, @samp{BREAKING}, @samp{HANGUP}).

@item STOPBITS
The number of stopbits sent.

@item TIMEOUT
The number of microseconds waited after starting the @samp{INPUT}
command before it is aborted due to a timeout.

@item TDOWNLOADPATH
The name of the directory in which received text files will be
stored.

@item TUPLOADPATH
The path to the directory to be used when uploading a text file.

@item UNITNUMBER
The unit of the serial device to be used.

@item VISBELL
@samp{ON} if a visual signal is to be used when a bell char is displayed.

@item VOICE
The message sent by the modem when a call has been detected that
does not come from another modem.

@end ftable


@node The Set command, Disclaimer, The Query command, Top
@chapter The Set command

Generally speaking, the @samp{SET} command is the exact opposite of the
@samp{QUERY} command.  Every parameter that @samp{QUERY} takes as an input can
be used with @samp{SET} to change that option.  For example, @code{query
baudrate} might return @samp{2400}, while @code{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 @samp{QUERY} description for further
information.

@ftable @samp

@item BELL
Sets the parameters of the Display of the bell character.  Currently,
the parameters @samp{AUDIBLE} and @samp{VISIBLE} are recognized.

@item COLOUR
Changes a colour.  The first parameter is the number of the colour
(0 through 15), the second the hex-value of the colour.

@item COLUMNS
Set the number of columns to be used for text display. This value is limited by the
current screen resolution and the minimum value of 20 columns. If a value smaller than
20 is specified, the maximum available number of columns will be used.

@item LINES
Set the number of lines to be used for text display. This value is limited by the
current screen resolution and the minimum value of 20 lines. If a value smaller than
20 is specified, the maximum available number of lines will be used.

@item MACRO
Sets one of the function keys' binding.  The name of the qualifier
(@kbd{none}, @kbd{shift}, @kbd{alternate}, @kbd{control}) and the
number of the key (@kbd{0}-@kbd{9}), plus the new contents of that key will be
needed as parameters.

Example: @code{set macro none 0 hello!}

@item SCREEN
This command is the opposite of the two options @samp{PUBLICSCREEN}
and @samp{SHANGHAI} (see the @samp{QUERY}-command).  These two
options may be given as parameters.

@item TIMEOUT
Sets the global timeout.  All read-functions will wait this time at
most before being canceled.  The time can be given as with
@samp{DELAY}, that is microseconds, seconds and minutes.

Example: @code{set timeout 10 sec}

@end ftable

Please note:  the Query-options @samp{line}, @samp{status}, @samp{cursor},
@samp{downloads} and @samp{beepsound} do not have a counterpiece.  Positioning of the
cursor should rather be done by using control sequences instead of changing internal
counters...


@node Disclaimer, Index, The Set command, Top
@chapter 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...

@node Index, , Disclaimer, Top

@unnumbered Index
@printindex fn

@page
@contents
@bye