XTERM Version 1.3.8 User's Guide
By Bill Andrus 10/17/84

 The following guide should be employed while using XTERM
until you are familiar enough with its features to rely on
the on-line Quick Reference HELP facility.

SYSTEM REQUIREMENTS, HARDWARE
 XTERM is designed to operate on the lowercase-equipped
TRS-80 Models I, III, and 4 (operating in Model III mode),
PMC-80/81, and MAX-80 (in 64 by 16 mode under LDOS) with 48k
memory and one disk drive. An RS-232-C interface is required
for the transmission of data. A MODEM is required to make
telephone transmissions. Telephone auto-dialling requires
one of the following: A LYNX MODEM or MicroConnection MODEM
with the optional dialling feature, a Radio Shack MODEM II,
a HAYES or HAYES-Compatible SmartMODEM, a J-CAT MODEM with
the blue wire at pin 4 (RTS), or the cassette port gizmo 
described in the March 1979 issue of KILOBAUD/Microcomputing.
If you have a soundmaker connected to the cassette port record
line, XTERM will summon you when redialling finally gets a
number and a DFT is completed. MAX-80 and Model 4 builtin
sound facilities are also used. And you must have a printer
to use the spooled printer buffer features, with a printer
driver that responds to @CTL of a NULL with status and is
protected in high memory (if special features of the printer
are to be used).

SYSTEM REQUIREMENTS, OPERATING SYSTEM
 XTERM is developed on Model I and III LDOS 5.1.4, and tested
on Model I TRSDOS 2.3/2.3B, NEWDOS+ (2.1), NEWDOS80 V1/V2/V2.5,
DOSPLUS 3.3/3.4/3.5, DBLDOS 4.23A, and VTOS 3.0.3/4.0.2N;
Model III TRSDOS 1.2/1.3, NEWDOS80 V2/V2.5, and DOSPLUS 
3.4/3.5; and LDOS 5.1.3 on the MAX-80. The CLOCK display must 
be off. The BIGVID driver for the Model 4 80x24 screen while
running in Model III mode is NOT supported, likewise the 
equivalent MAX-80 mods. I can't guarantee that it will operate
elsewhere, but if you can identify specifics, I'll try to
adapt it.

NOTATION
 When you see a labelled key name within "<" and ">", that
means you are to press that key. For example, <BREAK> means
to press the BREAK key. When two or more keys are shown 
together with a "+" connecting them, press them all together in
the sequence shown. For example, <SHIFT>+<CLEAR> means press
down the SHIFT key and, holding it down, press the CLEAR key,
then release them together. When the guide says to enter
a value or string of characters, that means you should press
the <ENTER> key when finished, even if you completely filled
the input field.

GETTING STARTED
 If you want to "fire it up" right away, here we go. These
steps will introduce you to some of the features and logic
behind what is possibly the most powerful TRS-80 Terminal
Facility.
1. Invoke XTERM by typing "XTERM" (without the quotes) and
 pressing <ENTER>.
2. Press <BREAK> to get to the Command Menu. Do this after
 every command option to get back to the Command Menu. At
 the Command Menu itself, pressing <BREAK> will output a
 01H character and take you back to the Terminal Mode. You
 may also press <ENTER> to return to Terminal Mode with the
 saved screen restored, or <SHIFT>+<CLEAR> to clear the
 screen first.
3. From the Command Menu, Press <I> for RS-232-C Initial-
 ization and press the indicated keys to select the
 desired selections.
4. Press <C> for the Configuration option. Press the
 necessary keys to set up your RS-232-C Interface (stock
 Radio Shack, MAX-80, LYNX, or MicroConnection), MODEM
 (Acoustic, Modem II, Hayes, MicroConnection, or J-CAT),
 Dialling [Manual, Cassette Port Gizmo, RTS line for
 LYNX/MicroConnection/J-CAT, Rotary or Tone (for Modem II
 or Hayes)], Dialling Speed (Fast or Slow for Cassette,
 RTS, and Rotary Modem II), Base Port address if LYNX or
 which Port if MAX-80, and your desired printer parameters.
5. If you have a supported dialling facility, you can go to
 the Dialling option from the Command Menu and try it out.
 Press <M> for manual dialling, and type in the desired
 number. Use "," for a 2-second Pause or Hayes pause.
 If you have everything configured correctly and the call
 dials okay, you can now press <U> to update an entry to
 that number and configuration.
6. If you are satisfied that this set up is worth saving,
 its back to the Configuration option from the Command
 Menu and use the Save option. The default file extension
 is /DAT (if you type XT:2<ENTER>, it will save the current
 Configuration Data in a file called XT/DAT on drive 2).
7. You can save the Configuration Data file at any time, with
 any legal DOS file name you desire. Note that TRSDOS
 requires the file name to be entered in UPPERCASE. XTERM
 saves and loads a LOT of handy stuff for you in that file,
 like the Phone Directory, 10 MacroKeys, 10 Logon strings,
 BAUD rate, Graphics mode, and RS-232-C settings.
8. Well, that's it for getting started. You will discover
 that XTERM has probably the smallest RAM Buffer of any
 TRS-80 Terminal Program. It didn't start out that way,
 its just that all this code kind of doesn't leave a whole
 lot of RAM to use as a buffer. XTERM has a 2048 (2k)
 printer spool buffer, 128-byte type-ahead buffer, 512-byte
 RS-232-C input spool buffer, and 1024 (1k) saved screen
 buffer. In order to provide reasonable space for DOS
 command execution, XTERM itself begins at 6C00H.

ENTRY SYNTAX
 The first time you enter XTERM you can simply type in:
XTERM<ENTER> from the DOS ready prompt. This executes XTERM and
gives you the sign-on Logo and prompt. If you are doing this on
a MAX-80, it is automatically configured for you. (Note:
my version numbering convention will also tell you when you
must bring up a new version of XTERM without previous 
Configuration Data files). Press the <BREAK> key to go to the
Command Menu. Here you can set up all of the parameters you 
wish to use with a particular bulletin board. Change the default
Auto-Logon string to whatever is required for the BBS. You can
use a slash (/) to indicate a Carriage Return whenever you need
one in the string. You may chain strings together by ending one
with a [x] sequence, where x is the next one. You may define 
new  RS-232-C parameters, enter phone numbers, and set 
MacroKeys. Once you have changed everything, you can save the 
data to the disk by selecting option C from the Command Menu, S
to save configuration, and entering a filespec. 

By the way, XTERM uses /DAT as the default file extension
for ALL configuration and buffer files. Now that you have
configured, whenever you enter XTERM you can immediately load
the configuration data by specifying the filespec after XTERM.
For example, suppose I save a Forum-80 configuration data
file with the filespec FOR/DAT. My syntax could then be (from
the DOS ready prompt): XTERM FOR/DAT<ENTER> or XTERM FOR<ENTER>

Either of these will load in the configuration data file 
FOR/DAT. If you exit XTERM prematurely and wish to re-enter it
as it was, say, to recover the contents of the RAM Buffer,
invoke XTERM (from the DOS ready prompt) with an asterisk
(*):  XTERM *<ENTER>

VERSION NUMBERING CONVENTION
 I am employing the following convention in numbering each
new version of XTERM. The number X.Y.Z represents the set
of features X, reassembly Y (either will require building
a new Configuration Data file), and minor reassembly Z (which
will use existing X.Y.n Configuration Data files).

KEYBOARD AND VIDEO DISPLAY
 XTERM uses an interrupt-driven 128-keystroke type-ahead
keyboard routine, with the full 128 ASCII characters and 64
TRS-80 graphics characters available directly from the keyboard.
The video display routine translates the following characters
into graphics on the Model I for better recognition: [, ],
\, ^, and ~. These routines make it possible for XTERM to
keep up with 1200 BAUD transmissions even during clear screen
and most background (Command Menu) activities. Some characters
may be dropped while executing DOS commands under those DOS
which do not attempt to keep the real-time clock accurate,
like TRSDOS and NEWDOS. Note that this doesn't mean that
XTERM supports CLOCK,Y on NEWDOS; it most definately doesn't
support the display of the clock under ANY DOS.

BREAK KEY
 The BREAK key will return you to the Command Menu from
anywhere else in XTERM, eventually. If you are at the Command
Menu, the BREAK key will output a translated X'01' or SOH
and return to the Terminal mode.

TERMINAL MODE
 When you first enter XTERM, you are in the Terminal Mode.
Everything you type, with a couple of exceptions, will be
sent out the RS-232-C line. You press the <SHIFT> and <DOWN
ARROW> keys together, along with a letter key, to generate
Control Code (CTRL) characters. On appropriately modified
Model Is, XTERM recognizes the Electric Pencil V1.0 Pencil
Control key as well! You press the <CLEAR> key, by itself
or with <SHIFT>, to get to the extended keyboard characters.
Note: Use <CLEAR> plus <A> through <J> to invoke the 
MacroKeys.

COMMAND MODE
 When you press <BREAK> while in the Terminal Mode you enter
the Command Mode and are presented with a large menu of options
to select from. Merely press the corresponding key to select
the desired option. Pressing <BREAK> again will transmit
an SOH or 01H character and return you to Terminal Mode. 
Pressing the <ENTER> key will return you to Terminal Mode
with the last screen restored AND any received characters
updated onto it. Pressing the <SHIFT>+<CLEAR> keys will return
you to Terminal Mode with the screen cleared. Common to most
options within the Command Mode is the Input Field. This
displays as a string of periods, denoting the length of the
maximum input you can make before pressing <ENTER> to complete
the input. This field can be editted with the Left Arrow
key functioning as a Rubout key and the <SHIFT>+Left Arrow
keys as a Cancel (erase input field) key.

COMMAND MENU OPTIONS
SEND A MODEM SPACE (Option A) - You may send a 3-second MODEM
SPACE (if your MODEM supports it, which the Signalman XII
doesn't) with this option. Some Timesharing Systems use this
indication as an interrupt request. This will cause some
MODEMs to hang up, too. The 3-second length was chosen because
it WILL hang up some MODEMs, so the D, H sequence can be 
skipped.

BUFFER ON/OFF AND CLEAR BUFFER (Options B and Z) - There are
two ways in which XTERM will begin to add characters from
the RS-232-C input to your RAM Buffer: Upon the receipt of
a DC2 (or CTRL-R character) or if you use the <B> option to
toggle the Buffer Open. Correspondingly, there are two ways
to close the buffer: Upon receipt of a DC4 (or CTRL-T 
character) or another <B> option to toggle it closed. The 
status of the RAM Buffer is displayed in the lower half of the 
Command Menu screen, including the remaining bytes and current 
checksum . Option <Z> will reset the RAM Buffer pointers, 
effectively clearing it, even while Open.

CONFIGURE XTERM (Option C) - This is where you can set up
XTERM's configuration, Load an old configuration data file,
or Save a new one. You will not be able to use the autodial
and/or most non-standard interface/modem capabilities of XTERM
until you have configured XTERM to use them. The MAX-80,
uConnection or the LYNX RS-232-C interfaces should have already
been set if you are using one. If using a LYNX or MAX-80,
you will have the option to specify the Base Port address
or which serial Port is to be used, respectively. You can
also set different printer values here. Remember, the default
configuration data file extension in XTERM is /DAT.

DIALING DIRECTORY (Option D) - This option permits you to
use the TRS-80 very intelligently. When you update the tele-
phone numbers and parameters, you are able to specify the 
RS-232-C configuration (BAUD, Word Length, Parity, Stop Bits, 
Graphics Mode, XON/XOFF support, Logon string, and Redial 
delay) along with the number. Later, when you dial the number,
the saved parameters are set for you, including an optional Logon string activation. Specifying a directory entry is quite
simple. You specify U, press <ENTER>, specify the entry number,
press <ENTER>, and follow the prompts. You can enter up to 16 
characters of identification (Name) and 16 characters of phone 
number (use a MacroKey to prep MCI first if you need more 
characters). Pressing <ENTER> to any prompt leaves the existing
data intact . Phone numbers may contain the following 
characters, which will be filtered out: "(", ")", "-", and 
spaces. If you desire a Pause (a "," in Hayes, a "P" in Modem 
II), always use a ",". (It will be translated to a "P" for the
Modem II, and the Cassette and RTS modes will execute a 
2-second pause.) From the Dialling option, you may also 
specify Manual dialling of a prompted number (using the current
RS-232 configuration and default Redial delay), put the modem 
On-line after conversing vocally, Redial the last dialled 
number (whether manually entered or selected from the 
directory), and Hangup the phone. In addition, if you first 
specify Continous Redialling before the next dialling selection
number, <M>, or <R>, then XTERM will redial the selection until
it sees a carrier, recycling as specified in the Redialling 
delay. The default of 20 seconds (except for the Radio Shack 
MODEM II, 40 seconds) has been augmented by the <R> key, so 
that if you KNOW the number is busy, merely press <R> to 
perform a nearly immediate redial. During this mode, the 
<CLEAR> key will break you out of the loop within a second, 
and <BREAK> will take you back to the Command Menu. These 
dialling features are one of the reasons so much time was put 
into the development of XTERM in the first place.

ECHO ON/OFF AND FEEDBACK ON/OFF (Options E and F) - These
two toggle switches allow you to set up XTERM for various
non-BBS applications. If the system you are connected to
doesn't operate in Echo-Plex (echo back to you what you have
typed), set your Echo switch ON to see what you are sending
to it. If you desire to act like a proper Host to someone
connected to you, by echoing what they are sending you back
to them, set your Feedback switch ON. The status of both
switches is displayed in the lower half of the Command Menu
screen.

GRAPHICS ON/OFF (Option G) - Some BBS have the facility to
provide full 256-character output, which allows messages to
contain graphics, even some animation! Toggle this switch
off if you are getting garbage on the screen in 8-bit word
length mode. It is ignored internally when in shorter word
lengths. The status of this switch will be displayed as a
G or blank to the right of the Word Length number in the lower
half of the Command Menu screen.

PRINTER OPTIONS (Options H and P) - You can toggle the On-line
spooled printer switch (option P) or print the contents of
the RAM Buffer (option H). Since the On-line printing is
spooled through a 2K (2048 character) buffer, the printer
need not be able to keep up with the incoming data. Printing
the buffer will use the parameters specified in the Configu-
ration section for lines per page and the number of characters
per line. The printer spool buffer must be empty before the
RAM Buffer begins to print.

INITIALIZE RS-232 (Option I) - This option permits you to
specify any changes to the current configuration. Press <ENTER>
to skip to the next parameter without change. The current
settings are always reflected in the lower half of the Command
Menu screen.

LOAD AND SAVE BUFFER (Options J and K) - These options allow
you to load a disk file into the RAM Buffer, or save the RAM
Buffer to a disk file. The file extension default is /DAT.

OUTPUT LOGON (Option L) - This option will cause the current
active Logon string to be sent out the RS-232 line and return
you to the Terminal Mode display.

MACROKEY/LOGON STRINGS (Option M) - XTERM allows you to have
10 MacroKey strings which can be sent out by pressing <CLEAR>
plus a letter from A to J at the same time. Each string can
be up to 50 characters in length. Each string can contain
ANY character except "/", which represents a Carriage Return
or <ENTER> character. MacroKeys and Logon strings can activate
specific Logon strings, chain to them, or chain to MacroKeys,
if desired. In fact, Logon strings and MacroKey strings can
invoke each other. Just be careful not to create a loop!
Remember that every Logon string reference makes it the current
Active one. You weave this magic like this. If a Logon or
MacroKey string has a character sequence of [n], where n is
0 through 9, then the n becomes the current Active Logon.
If the sequence is at the very end of the string, XTERM chains
to that Logon string and continues output! If a Logon string
or MacroKey string contains a sequence [A]-[J] or [a]-[j],
XTERM will immediately chain to that MacroKey string. You
may also include comments in a string by preceding them with
an apostrophe ('). XTERM will ignore the rest of the string
and stop output. The contents of all 10 MacroKey strings
and all 10 Logon strings are saved as part of the 
configuration.

OUTPUT DISK/BUFFER (Option O) - This option allows you to
transmit the contents of your RAM Buffer in either Prompted
mode or XON/XOFF mode. If you specify XON/XOFF, answer the
Wait for Prompt (Y/N)? question with No and XTERM will check
for the appropriate XON/XOFF codes. This option will also
eventually allow you to specify a Disk File to be sent in
ASCII mode, buffered through the RAM Buffer, under Prompted
or XON/XOFF controls.

QUIT TO DOS (Option Q) - This quietly slips you back to DOS.

RECEIVE AND SEND DISK FILE (Options R and S) - This is the
feature that sets XTERM apart from all other TRS-80 terminal
programs. XTERM supports the XMODEM/MODEM7 checksum file
transfer protocol and the better (by a magnitude of error
detection) CRC-16 protocol found on many newer RCP/M BBS and
Towne Crier 2.0 (V). Should an error occur during the transfer
of a block the number will remain on the screen, followed
by an asterisk (*). The checksum protocol is fully compatible
with Towne Crier 2.0 (V), TBBS 1.2/1.3, Forum-80, Bullet-80,
XMODEM, MODEM-80, SMODEM39, MODEM4, and MODEM7.

TYPE INTO BUFFER (Option T) - Some folks like to use this
option to prepare messages off-line, because of the speed
and editting it provides (not to mention the fact that all
128 ASCII and 64 Graphics characters can be entered here),
and then logon and transmit the message from the RAM Buffer
with the O option in Block mode.

UPDATE CONVERSION TABLES (Option U) - You have three tables,
Incoming data, Outgoing data, and Printer data. One byte
you might consider changing is byte 0AH (10). This is the
linefeed byte and will cause a Carriage Return to occur on
the TRS-80. If you null out the byte (change it to a 00)
you will not get a Carriage Return when a linefeed is sent.
(Some computers require a 13 and the 10 sent to have a 
Carriage Return.)

VIEW/EDIT BUFFER (Option V) - You have the option to view
the contents of the RAM Buffer in either ASCII or HEX/ASCII
format (similiar to the way disk sectors are displayed). 
If you select HEX/ASCII you can use the four arrow keys to
scroll the Buffer in all four directions. You are NOT limited
to just the RAM Buffer memory, you can look at any byte of
RAM or ROM. By pressing the <M> key you can modify the current
ly displayed RAM screen in either ASCII or HEX. Again, by
using the arrow keys, you can move the cursor around to the
particular byte on the current screen you want to modify.
Pressing <BREAK> will return you back to the display, and
then to the Command Menu.

WRITE INPUT TO DISK (Option W) - This option, when operational,
will permit you to receive ASCII files from systems which
honor XON/XOFF pacing. When active and the RAM Buffer is
almost full,an XOFF will be sent, the previously designated
file will receive the contents of the full RAM Buffer at its
end, the RAM Buffer will be cleared, and an XON sent to the
sending system, all automatically. The RAM Buffer will be
flushed to end of the file when you toggle this mode off.

EXECUTE DOS COMMAND (Option X) - This option allows you to
perform several DOS commands without leaving XTERM. It may
not function with MultiDOS because your author doesn't have
the current version to test it with. It DOES operate correctly
with TRSDOS (2.3, 2.3B, 2.8DD, 1.2, and 1.3), LDOS 5.1.3 and
5.1.4, NEWDOS (Plus, 80V1, 80V2.0, 80V2.5), DOSPLUS (3.3S/D,
3.4S/D, 3.5), TDOS, and DBLDOS 4.23A. Do NOT invoke programs
or DOS commands which do not honor HIMEM or load into memory
above 6C00H.

CONCLUSION - XTERM is still growing and is slowly becoming
a more universal program for telecommunications. If you have
any comments or suggestions concerning XTERM please drop me
a line on Systems Exchange at (703) 323-7654 in Fairfax, VA
(Monday to Friday, 7 AM to 3 PM EST except Federal Holidays)
or write me at:

Bill Andrus
10021 Commonwealth Blvd
Fairfax, VA 22032
                                                                                                      3-7654 in Fairfax, VA
(Monday to Friday, 7 AM to