💾 Archived View for spam.works › mirrors › textfiles › apple › DOCUMENTATION › snowterm captured on 2023-06-16 at 21:25:19.
-=-=-=-=-=-=-
SnowTerm
Version 2.05 16-Dec-90
Copyright 1990
By John F. Snow
Snow Software
Introduction
------------
SnowTerm is a communications program for the Apple IIGS computer.
Version 1 of SnowTerm was essentially just a VT100 terminal emulator.
In the documentation for version 1 of SnowTerm, I promised that SnowTerm
would be expanded to become a communications program. This release of
SnowTerm, version 2, is the first step towards fulfilling that
promise.
SnowTerm emulates the Digital Equipment (DEC) VT100 and VT52 terminals.
SnowTerm runs in the super high resolution graphics mode of the Apple
IIGS and uses the desktop user interface. SnowTerm uses the graphics
and color capabilities of the Apple IIGS to accurately emulate the VT100
terminal including bold and blinking character attributes, the line
drawing character set, and double high and double wide characters.
Although the VT100 implements a subset of the ANSI standard, the VT100
and SnowTerm do not implement the (so-called) ANSI color graphics used
by some IBM oriented bulletin boards.
SnowTerm is not free software and it is not in the public domain; it
is shareware. You may try it free for 10 days after which you must
either become a registered user or discontinue use of the software.
To become a registered user, send a check for $20 to:
Snow Software
PO Box 58621
Salt Lake City, UT 84158
In return, you will receive the latest version of SnowTerm on 3.5" disk,
a manual, and technical support via email. Orders outside of North
America please add $5 per copy for shipping. Due to the increased size
of the Apple IIGS system disk, the system disk is no longer shipped as
part of SnowTerm unless you specifically request it. Add $3 to receive
the Apple IIGS system disks (two 3.5" disks).
The SnowTerm disk includes a font editor that allows you to customize
the fonts used by SnowTerm. It also includes, by permission of the
authors, several public domain and shareware programs that complement
SnowTerm.
Once you are a registered user, you may download and use updated
versions of SnowTerm for no charge or you may order updated versions
for a minimal shipping and handling fee. Currently registered users
of SnowTerm may order an update from Snow Software. Several upgrade
options are available:
SnowTerm v2, manual, and latest IIGS System Disk ....... $10
SnowTerm v2, manual, no System Disk .................... $7
SnowTerm v2 disk only, no manual or System Disk ........ $3
SnowTerm v2 manual only, no software ................... $5
These prices are in US dollars and include all shipping and handling
charges for destinations in North America.
You may give a copy of SnowTerm to other users or post it on
electronic bulletin boards for other users to evaluate, as long as
this documentation is included. Distribution of SnowTerm without this
documentation and using SnowTerm after the 10 day trial period without
becoming a registered user are considered copyright violations.
System Requirements
-------------------
To run SnowTerm you must have an Apple IIGS computer with a minimum of
768K of system RAM. 1MB or more of RAM is recommended. A color RGB
monitor is also recommended. This version of SnowTerm will work with an
external modem connected to the built in GS Modem port, the GS Printer
port, or to a Super Serial card compatible interface plugged into one of
the slots. It also will work with internal modem cards that are Super
Serial card compatible.
This version of SnowTerm requires GS/OS version 3.0 or higher (GS
system disk version 5.0.2 or higher). It is recommended that you
obtain and use System Disk 5.0.3. Since SnowTerm uses resources, a new
feature of System Disk 5, SnowTerm will access the program disk more
often during the operation of the program. For this reason, it is
recommended that SnowTerm be used on systems with at least two disk
drives or a hard drive.
Installation
------------
WARNING: The SnowTerm executable file contains both a resource fork and
and a data fork. Many older copy utilities cannot copy such extended
files. Therefore, you should only copy SnowTerm with copy utilities
that you know work correctly with extended files, such as the System Disk
5.0.2 Finder. If the size of the SnowTerm file decreases when you copy
it, the copy utility you used did not copy the resource fork.
If you downloaded SnowTerm from a communication service or BBS system
then SnowTerm will be packed into a .BXY format file which must be
processed with ShrinkIt or ShrinkIt/GS.
After processing with ShrinkIt, there will be several files, one of
which is called SnowTerm.Single. This file must be processed further to
obtain the SnowTerm executable file. There are two methods that may be
used to process SnowTerm.Single. If you are using ShrinkIt/GS, you may
Open the SnowTerm.Single file just like any other archive file and
select the SnowTerm file that is packed in the archive and extract it.
If you are not using ShrinkIt/GS, then you must use the program
UNSINGLEST (which is included in the SnowTerm archive) to convert
SnowTerm.Single into an extended file. Make sure that UNSINGLEST and
SnowTerm.Single are in the same directory (folder). You can launch
UNSINGLEST with the Finder or other program launcher. You will need
about 200 free blocks on the disk in order to unpack SnowTerm.
Again I emphasize, DO NOT copy the SnowTerm executable file with a copy
utility that does not handle extended files.
Hardware Configuration
----------------------
Important: If you are using the built in modem or printer port, you must
use the Apple IIGS control panel to configure the port with the device
connected parameter set to "Modem". Currently the desk top Control
Panel does not allow you to set the device connected parameter. You
must do this from the "Classic" control panel.
You may also need to set the following serial port parameters using the
control panel.
Device Connected: Modem
Line Length: Unlimited
Delete first LF after CR: No
Add LF after CR: No
Echo: No
You may also need to set the DCD handshaking parameter and DSR/DTR
handshaking parameter as required by your modem. One of the main questions
about SnowTerm that I receive is that SnowTerm can't communicate with the
modem connected to the built in serial port. This is almost always caused
by incorrect settings of the DCD or DSR/DTR handshaking parameters.
Experiment with these settings to find the setting that works with your modem.
Remember that any change to the control panel settings will note take
effect until you reboot your computer.
If you are using a Super Serial card or compatible internal modem, you must
configure the card to enable interrupts. On the Super Serial card this
means that switch 6 of switch bank 2 must be in the on or up position.
You must also use the control panel to specify the "Your card" option for
the slot the card is plugged into. SnowTerm works only with cards plugged
into slot 1, 2, 6, or 7.
If your modem is Super Serial card compatible but does not contain a ROM
(such as the Epic Classic modems), SnowTerm will complain that it can't
find a SSC compatible card in the slot you specified. In this case,
click on the "Proceed" button and SnowTerm will assume that the modem is
ROMless.
The Hardware Configuration dialog also allows you to specify a driver for
your printer. SnowTerm uses the GS/OS device driver to communicate
with the printer. A list control in the hardware configuration dialog box
allows you to select which GS/OS device the printer is attached to. Device
drivers are listed by slot number and device type. Listed below are the more
common devices for printers.
No Printer No printer is to be used.
Printer Port Use the built in printer serial port.
Modem Port Use the built in modem serial port.
Generic Apple terminology for a general purpose serial interface
card plugged into a slot.
AT RPM Use the AppleTalk remote printer manager.
Be sure to choose No Printer if no printer is to be used. SnowTerm may
"freeze" up if you do not select the "No Printer" setting.
Several printer related features are controllable from the Hardware
Configuration dialog. The "Generate LF after CR" option controls
whether a line feed character is sent to the printer after each carriage
return. If you get double spacing on your printer, turn this option
off. If everything is printed on the same line, turn this option on.
The Line Length and Page Length option allow long lines to be wrapped
around and printed on the next line and allow the perforation between
sheets to be skipped. Setting either value to zero disables the
corresponding feature.
NOTE: When SnowTerm starts up, it assumes that the printer is currently
at the top of a page and at the left margin. If you want the printer
formatting options to work correctly, you can make sure this is true
by issuing a form feed character in the printer init string. However,
this does cause a page to be ejected from the printer every time
SnowTerm starts up.
The "Init every time" and "Init once" buttons specify when the printer
init string is sent to the printer, every time a print command is
executed or only once, when the SnowTerm first starts up. The "Init
every time" option is useful if you want to start each print job at the
top of a new page. Select "Init every time" and include a form feed
character in the printer init string.
The modem init string is sent to the modem when SnowTerm first starts
up.
The modem init string and the printer init string are "Control strings"
-- a general purpose feature of SnowTerm which allows the user to enter
an ASCII string with special sequences which specify control characters
to be embedded within the string. When you are entering strings in
dialog boxes, various control characters pressed on the keyboard perform
editing operations and thus cannot be used to directly specify
characters to be embedded in a string. Thus, a control character
language of sorts has been developed.
Control strings allow control characters to be specified by two
different means. Control characters can be specified by a two character
sequence consisting of a caret (^) followed by an upper case character
in the range @, A-Z, [, \, ], ^, and _.
For example, the sequence ^A would result in a control-A character ($01)
being embedded in the control string.
The second method of entering control characters will be quite familiar to
C language programmers because it is essentially the C escape sequence
method of specifying character values. A C escape sequence begins with a
back slash character (\). After the back slash there are several options
for specifying the desired character.
First, you may use one of several single character mnemonics. For example,
the \r sequence will generate a carriage return. SnowTerm recognizes the
following mnemonic characters, most of which are the same as defined by C:
\b backspace (BS) - hex 08
\e escape (ESC) - hex 1B
\f form feed (FF) - hex 0C
\l line feed (LF) - hex 0A
\n new line (NL) sequence (CR + LF) - hex 0D 0A
\r carriage return (CR) - hex 0D
\t horizontal tab (HT) - hex 09
\v vertical tab (VT) - hex 0B
\? DEL character - hex 7F
\\ back slash -- interpreted as a single back slash
\^ caret -- allows a caret to be included
Notice that a double back slash inserts one back slash character into
the string and a \^ combination will insert a caret character which would
otherwise be used to indicate a control character. For example, \^A
would generate a caret character followed by an A instead of inserting a
control-A.
Besides using a mnemonic character after the back slash, SnowTerm allows
octal, hexadecimal, or decimal numbers to be used to specify the ASCII
value of the control character (actually any ASCII value between 0 and 255
may be specified).
To specify the ASCII value with an octal number, a THREE digit octal
number must follow the back slash. C programmers take note that, unlike
C, you cannot specify the octal number with just one or two octal
digits, you must use exactly three. For example, the sequence \123
would specify the ASCII character 'S'.
To specify the ASCII value with a decimal number, precede the THREE
digit decimal number with a \d or \0d (both 'd' and 'D' are accepted).
The decimal number must be exactly three digits long. For example, the
sequence \d123 would specify the ASCII character '{'.
To specify the ASCII value with a hex number, you have two options.
First, the standard C method which is to precede the TWO digit hex
number with a \x or \0x (both 'x' and 'X' are accepted). The hex number
must be exactly two digits long. Optionally, you can precede the TWO
digit hex number with a \$. For example, the sequences \0X41, \x41 and
\$41 all specify the ASCII character 'A'.
Control strings may freely mix normal ASCII characters, caret prefixed
control characters, and C style escape sequences together in one string.
For example, the following sequence would set an ImageWriter II printer
into 15 cpi printing mode and slashed zeros mode.
^[q\eD\000\$01
This sequence is interpreted as ESC q ESC D CTRL-@ CTRL-A. For
illustration purposes, I used two methods of specifying the ESC character,
^[ and \e.
Note that when mixing ^ symbols and \ symbols, the order in which they
appear determine how they will be interpretted. For example, ^\ is
interpretted as control-\ while \^ is interpretted as ^. ^\\^ is
interpretted as control-\ ^.
NOTE: Any printable ASCII characters in the control string are sent with
the MSB cleared (low ASCII). The only way to specify high ASCII characters
is by using one of the numerical escape sequences with a value greater than
127.
Running SnowTerm
----------------
SnowTerm can be launched by the Finder or other program launcher.
Special Keys
------------
SnowTerm treats the numeric keypad of the Apple IIGS just like the
VT100 keypad. Thus, under some conditions, the keypad keys will send
escape sequences rather than the ASCII codes for the characters shown
on the keypad. This allows SnowTerm to work correctly with the VMS
operating system.
A break character can be sent using the Send Break menu command or its
key equivalent, command-B. Previous versions of SnowTerm sent a break
when option-B was pressed. This still works in version 2, but may
not work in future versions as the option keys get assigned to other
uses.
The DELETE key will send either a delete character (hex 7F) or a
backspace character (hex 08), depending on the selection made in the
terminal dialog box under the Setup menu. Holding down the option key
and pressing the DELETE key will send the other character (backspace
if the DELETE key normally sends the delete character).
SnowTerm files
--------------
REGFONT and SPECFONT are special font files for SnowTerm. These files
MUST always be in the same directory (folder) as the SnowTerm file.
These files must NOT be placed in the FONTS folder of the system disk.
If you use the Preferences command to save a defaults file, it will be
called ST.DEFAULTS and will be located in the same directory as the
SnowTerm file.
SnowTerm looks for a file called ST.DIALLIST in the directory where
the SnowTerm program is located. If it finds this file, it reads the
list of phone numbers stored in this file for use with the Dial command.
The ST.DIALLIST file is a ProDOS text file and can be created with any
text editor including AppleWorks. If you are using AppleWorks, you must
not save the file as an AppleWorks file. Instead, use the print command to
print the phone numbers to a text file.
The format of the file is one phone number per line. The name comes first
followed by the number with a colon (:) separating them. The name portion
is what appears in the Dial dialog box list and can be up to 16 characters
in length. The number portion can be up to 39 characters in length. A
maximum of 20 phone numbers can be defined in the file. The following is an
example of the contents of a ST.DIALLIST file that contains two phone numbers:
Work:5551212
A BBS system:18005559999
The first phone number defined in the phone list will be used as the initial
default phone number in the dial dialog.
VT100 emulation differences
---------------------------
The VT100 terminal emulation provided by SnowTerm differs from an actual
VT100 in the following ways:
SnowTerm does not support the 132 column mode of the VT100 due to lack
of graphics resolution. A future version will provide horizontal scrolling
to support 132 column mode.
SnowTerm does not transmit an ANSWERBACK message when CTRL-BREAK is pressed.
SnowTerm does not support the underline cursor mode. Only the block cursor
is supported at this time.
SnowTerm does not support the margin bell.
SnowTerm does not support the VT100's smooth scroll mode.
SnowTerm does not respond to any of the VT100's self test escape sequences.
SnowTerm cannot correctly combine the bold and blink character attributes
on the same character. Characters which have been assigned both the
bold and blink attributes will appear as either bold or blinking, but
not both. The user may select whether such characters appear as bold or
blink using the Terminal dialog box.
SnowTerm does not contain a UK character set. The REGFONT and SPECFONT file
contain only the US character set. Registered users also receive REGFONT.UK
and SPECFONT.UK which can be used instead of the normal fonts to provide a UK
character set. However, SnowTerm will not switch between the US and UK
character sets like the VT100 will.
Recording buffer
----------------
The recording buffer is a facility that allows received text to be
captured and then saved to disk, listed on the screen, or printed to the
printer. The 0% display on the left side of the menu bar indicates how
full the recording buffer is and whether it is currently capturing data or
not. If it is RED, data is being captured. If it is black, data is not
being captured.
The buffer preferences dialog allows you to specify features related to
the recording buffer. It is recommended that you ALWAYS use the "Filter
control chars" mode which prevents control characters from being
captured. Since the printer port and the list window both get very
upset by control characters, you should always leave the filtering on.
The "Expand tabs" mode will convert tab characters into enough space
characters to move to the next tab stop. It is recommended that this
mode be used as well.
If "Auto save" is on, the contents of the recording buffer will be
automatically saved to disk when the buffer becomes full. Normally,
this data is saved in a file called ST.CAPBUF in the same directory as
the SnowTerm file. You may change the path and file name for the
autosave file by using the "Set Autosave file..." command.
If "Auto save" is turned off and the buffer becomes full, recording will
be disabled.
The "Recording at start" control specifies whether the recording buffer
is on or off when SnowTerm first started.
The "% display on" and "% position" controls allow control over buffer
status display in the menu bar. You can turn it on and off and position
it within the menu bar. The position is relative to the right edge of
the menu bar.
The scroll bar allows you adjust the size of the recording buffer. Note
that you may set a size that can't be allocated due to memory
fragmentation. In this case, SnowTerm will not resize the recording
buffer.
When listing the recording buffer to the screen, a Text Edit control is
used. This allows rapid scrolling through the data, but also uses lots
of memory because the Text Edit control keeps its own copy of the
recording buffer. If there is insufficient memory to create the Text Edit
control, you may need to reduce the size of the recording buffer.
You may edit the text in the Text Edit control, however any editing done
is not reflected back to the actual recording buffer contents. If you
cut or copy data from the Text Edit control, it will be placed in the
system clipboard and can be read by other programs such as AppleWorks
GS. A Select All commmand in the Edit menu makes it easier to copy all
of the text in a window into the clipboard.
Any font may be used to display the text in the Text Edit control.
However, you may want to use a fixed width font rather than a
proportional font. Since most computer terminals use fixed width fonts,
most screens and listings produced by computers don't look right when
viewed with a proportional font. The Monaco and Courier fonts are two
fixed width fonts that work well in a Text Edit control. If find the
Monaco font more readable and have made it the default font. You are
free to choose whatever font you want to use by using the "Choose Font"
button in the Buffer Preferences dialog box.
Sending Files
-------------
Currently SnowTerm can only send text files and receive text files (using
the recording buffer facility). XMODEM and other protocols will be
added in future releases.
After choosing a file to be sent, a "Text File Send Options" dialog box
allows you to set several options. The Prompt Char option allows you to
specify a single character that SnowTerm will look for before sending
the next line. This prompt character is useful when uploading text to
an editor on the remote machine. This allows the file transfer to be
paced by the receiving machine so that the next line is not sent before
the receiving machine is ready for it.
The prompt character is entered as a SnowTerm control string. Thus, you
may directly enter an ASCII character or may use one of the control string
escape sequences to enter any ASCII value from 0 to 255. Note that if the
control string you enter evaluates to more than one ASCII character, only
the first character is used as the prompt character.
If you are uploading to an editor that does not issue a prompt character
but does echo the text back, you can use a carriage return as the prompt
character and SnowTerm will wait until the remote computer finishes echoing
the line before sending the next line. I have found that some screen
oriented editors, like LSE on VAX computers, do not issue a carriage return
to move the cursor to the next line. Instead they send an escape sequence.
I've found that setting the prompt character to ESC (^[ or \e) works very
well with such editors.
The Character Delay and Line Delay options allow you to specify a delay
to be inserted between characters and lines so that text is not sent
faster than the receiving machine can accept it. These delays are
specified as numbers from 0 (no delay) to 9 (max delay).
The "Add SP to blank lines" option will add a space character to any
blank line. Since some message editors on remote machines detect that
you are finished entering text by the presence of a blank line, this
option allows blank lines to be uploading without erroneously ending the
upload.
You may abort the sending of a text file by pressing the command key (open
Apple) and the period key ('.') simultaneously. You can tell if a file is
still being transferred because the File menu will be highlighted in the
menu bar during the file transfer. A "peep" will announce the successful
completion of a text file transfer.
While a text file is being transferred, any characters received through
the serial port will be displayed on the SnowTerm terminal screen. This
allows you to watch the progress of the text file transfer if the remote
computer is echoing the text back. If you have recording buffer enabled
when you start sending a text file, recording is turned off while the
file is transferred and turned back on when the transfer has been
completed.
Listing and Printing Text Files
-------------------------------
SnowTerm v2 contains commands to list and print text files. The list
facility uses a Text Edit control just like the List Buffer command.
All of the restrictions that apply to the List Buffer Text Edit control
apply to the List File Text Edit Control. The same font is used.
The Open command in the file menu is used to list the contents of a
file. Only one file may be listed at a time. If a file listing window
is open when you select the Open command, the current window will
be closed.
You may also print a text file to the printer.
The use of Text Edit controls will be expanded in future versions of
SnowTerm to provide file editing, multiple file windows, etc.
Echo Received Characters to Printer
-----------------------------------
Received characters can be echoed to the printer. All control
characters will be filtered. This features follows the printer options
supplied in the Hardware Configuration dialog box. It also follows the
"Expand Tabs" option in the Buffer Preferences dialog box to expand tab
characters into spaces if the option is set.
Reset commands
--------------
SnowTerm provides two different reset commands. One resets the serial
port and the other resets the terminal emulation. Both of these are
provided mainly to recover from line noise which may cause problems with
either the terminal emulation or the serial port.
One common error mode occurs when line noise causes the receipt of a
XOFF handshaking character when the remote computer did not send an XOFF
character. The XOFF character will prevent any further transmissions
from your computer to the host computer until the host sends a XON.
Since the remote computer didn't send the XOFF, it won't send a XON.
So there you sit, pressing keys and nothing happens. If you have a
modem with transmit and receive lights, you will notice that pressing a
key does not cause the transmit light to turn on.
The reset serial port command was made to solve this problem. It will
reset the serial port software so that it no longer knows that a XOFF
was received.
Another common failure mode is the erroneous receipt of the control character
which switches the VT100 emulation into special graphics mode. All
lower case characters received are displayed in special graphics mode.
The reset terminal emulation command will reset the VT100 emulation to
its normal state and solve this problem.
New Preferences
---------------
Version 2 has two new controls in the Preferences dialog. The first,
Confirm Quit, specifies whether or not an Alert box will pop up to ask
you to confirm that you really want to quit.
The second new control, Std Colors for NDAs, allows control over a new
feature which will change the screen colors to the standard desktop
colors whenever a NDA is the top window on the screen.
----------------------
Snow Software electronic mail addresses:
GEnie: J.SNOW2 Compuserve: 71550,1152
MCImail: 321-3461 America Online: JohnSnow
UUCP: ..!uunet!utah-cs!esunix!jsnow
INET: esunix!jsnow@cs.utah.edu
Revision History
Version 2.00
------------
Initial release of version SnowTerm v2.
Version 2.01
------------
Fixed a bug that caused the desktop colors to not change to the standard
colors when a NDA was moved and activated.
Changed the hardware dialog box to select printers by GS/OS character
device names rather than by slot number.
Version 2.02
------------
Fixed a bug that caused the Recording On/Off to be in the wrong state if
"Recording at Start" option was selected.
Version 2.03
------------
Fixed serveral bugs dealing with serial port initialization. First, the
modem init string was being sent to the modem before the baud rate specified
in the defaults file was set. SnowTerm now correctly sets the serial port
parameters before sending the modem init string. The "Reset Serial Port"
command was resetting the serial port but not restoring the serial port
parameters specified by the defaults file.
The modem init string has been expanded from a maximum of 14 characters to
a maximum of 39 characters.
The control character filter for the capture buffer and the printer echo
has been improved so that entire escape sequences are now filtered out. If
the control character filter is turned on, all characters of any recognized
escape sequence will be filtered. The recognized escape sequences will vary
with the type of terminal being emulated (i.e. the VT52 emulation will not
filter VT100 escape sequences). In addition, if the terminal wrap around
mode is enabled, a carriage return is inserted into the capture buffer and/or
sent to the printer when the terminal emulation wraps around to the next line.
Version 2.04
------------
When SnowTerm was in half duplex mode, a keypress that generated an escape
sequence was incorrectly echoed to the screen. Only the first character
of the escape sequence (the ESC character) was being echoed.
Version 2.05
------------
Fixed a bug which would sometimes cause SnowTerm to freeze. It would also
cause other programs that would access the serial port to freeze after
SnowTerm was run. This problem was happened more often if the Super Serial
card driver was used.