XTERM Version 1.3.A User's Guide
By Bill Andrus 01/17/85

   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.


DIALLING DIRECTORY (Option D) - This option permits you to use the TRS-80 very intelligently.  When you update the telephone 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 so(c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  (c) 1980 Tandy  