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.