TermWorks 1.29 A terminal program for Macintosh Copyright 1986, James Rhodes - Horizon Software Thanks to Paul Blackwell for work on the manual and David Stovall for hours of testing. Introduction TermWorks is a data communications package for Macintosh designed to cut through the frustration and confusion which seems to plague most such software. You will use it to communicate through a modem with other computers, bulletin boards, and larger communication services such as Compuserve, GEnie, and The Source. Operating parameters are tailored to these types of services, making the complex business of data communications as painless as possible. How to use this manual This disk-based manual is also designed with simplicity in mind. The novice user may wish to print it out for ready reference. Those more experienced with the Macintosh and data communications probably won't need it at all except perhaps to occasionally check on some specific function or investigate the program's shortcuts. MacWrite's Find command can be useful for this. For example, to find out what 'Send xmodem' means, simply select Find (in the Search menu), type in Send xmodem and click Find Next. MacWrite will locate the appropriate section for you. To find information on any menu item, enter the menu entry in the Find what dialog box in all caps. This will bypass any reference to the menu in the tutorial and take you to the appropriate reference section. The first section of this manual titled Using TermWorks is a tutorial for the neophyte. It requires no previous knowledge of data communications; however, it assumes familiarity with basic Macintosh functions as covered in the Macintosh Users Manual. The Reference section covers all features of the program in a format suitable for the advanced user. Using TermWorks Getting Started When you Open TermWorks, you will be greeted with a document window and six menu headings. The document window is where information will be displayed and stored as it is sent and received by TermWorks. TermWorks documents may be Saved and Opened like any other Macintosh document. The New selection also works the way you are used to - to create a new TermWorks document. When you select New from the File menu, a dialog box will appear asking you for the name of the file to be used to store the new document in. If the name you enter is the same as an existing file, TermWorks will ask you to confirm it with the Replace Existing? alert box. If you answer Yes, the old file will be lost. Next, pull down the Settings menu and check that Record Text is selected (you can tell if it is selected by the check mark next to it). Now anything you type or anything TermWorks receives from a remote computer will be saved on the disk. Setting the parameters Once you have a new document opened, you must configure TermWorks to match the computer you intend to communicate with. The first step will be to set the baud rate. Baud rate is simply the speed at which information will be transmitted. This will usually be determined by your modem. Most BBS's (bulletin board service) and commercial communication services will automatically adjust to what ever baud rate you are using. Some smaller BBS's may be limited to 300 baud. In this case, you will have to set the baud rate to 300 even if your modem is capable of 1200 or 2400 baud communication. The current baud rate is displayed a little to the left of the center of the screen, just below and to the left of the window title. As you click on the displayed rate, the setting changes. Continue clicking until the desired baud rate appears. Other options you might need to set are in the Settings menu. The Slow and Fast Scroll selections are mostly a matter of preference. The Slow Scroll is easier to read at 300 baud because the text scrolls up two pixels at a time instead of jumping a line at a time. Fast Scroll makes the text advance one line at a time instead of by two pixels at a time. The option allows TermWorks to keep up with very high baud rates, although it makes the text harder to read than Slow Scroll. Another item you need to be aware of is Local Echo, also in the Settings menu. This selection, when checked, tells TermWorks to echo the characters you type to the screen as they are transmitted. Normally, the characters you type will be displayed when the remote computer sends them back to you so the default is local echo off (not checked). It is very easy to tell if this setting is correct - if it is, every character you type on the keyboard will be answered by one and only one character on the Macintosh screen. If the characters you type appear twice on the screen, turn local echo off. If the characters don't appear at all, turn local echo on. There is one more selection on the Settings menu that you need to be concerned with. The Advanced Settings selection allows the experienced terminal user to set the number of data bits, number of stop bits, parity, and the port TermWorks will use (modem or printer). Most novice users will not need to use this option. That's all there is to setting the communication parameters! If you've tried to wade through the morass of options on some of the other terminal packages, you're probably thinking it can't be that easy. In some cases you're right. Some remote computers may require protocols not supported by TermWorks, but for the vast majority of the independent BBS's and popular commercial services, these few settings are all you need. Making the Connection The next step is to tell your modem to dial the remote computer. TermWorks offers a handy dialing service to take care of this job. Select Dial Service from the Phone menu. A dialog box appears with a place for the name for the remote system, the phone number and a button marked Dial. Enter the name, the phone number and click Tone or Pulse to match your local phone system. Now click on the Dial button. TermWorks will instruct your modem to dial the number. If the line is busy, TermWorks will hang up and try again until a connection is established. To abort the dialing, press the mouse button once. When the connection is established, the Macintosh will beep twice and the remote computer will usually start sending some kind of log-on message. Making it easy TermWorks can remember the names and numbers for 10 remote systems in its directory. To make a new entry, choose one of the ten options in the Phone menu (labeled Untitled). Now choose Dial Service and fill in the name and phone number as before. When you click Dial the name and number will be recorded along with the current settings for baud rate, scroll rate, local echo, record text, and the advanced settings. The next time you wish to call that particular service, just select it from the Phone menu (remember that a selected entry is marked by a check mark), select Dial Service, and click Dial. Editing The information in a TermWorks document can be edited using the standard Macintosh editing commands. For example, if, while browsing through the news section of a BBS, you happened across an ad for a 512K Macintosh system with external drive, Imagewriter and modem for $1000.00, you might want to make a note of it. Just highlight the section with the mouse as usual, choose Copy from the Edit menu and then open the notebook or scrapbook desk accessory and Paste the selection in. You can use these editing commands to copy information between any Macintosh applications. Sending Files TermWorks provides facilities for sending files as well as text typed on the keyboard. Suppose, for example, that you wish to send a birthday greeting to a friend's electronic mailbox on a BBS that you both frequent. Rather than spend a lot of expensive long distance time or connect time composing the message, you can write it beforehand in MacWrite. When you're satisfied, save the file as Text Only (click the Text Only box in the Save dialog box in MacWrite). Now boot TermWorks, log onto the BBS and prepare to send mail. When you are ready to start typing the message, choose Send Text File from the File menu. Use the Drive and Eject buttons in the dialog box to select the File you previously saved just as you do in any other Macintosh program. When satisfied, click Open. Another dialog box will appear next. This dialog allows you to determine how the file will be sent. It provides two different means of "hand-shaking" so the send will not result in characters being lost. The first is by using line delays. A line delay of 20/60 (1/3 of a second) is usually plenty for most systems. If it is suspected the characters are being lost due to TermWorks sending the file too fast, it can be slowed down simply by changing the delay. A character delay is also provided, but is probably not necessary in most cases. The other method of "hand-shaking" is called line prompts. When this option is used, TermWorks will pause and look for the prompt character character specified in the dialog before sending each line. For example, in E-mail on GEnie, the prompt to be used is the > (greater than) symbol. The method is desirable over the line delays because it allows the text send to be as fast as possible where as the other method would have to allow for a worst case on each line. The file is sent as if you were typing it on the keyboard. This facility is also useful for sending the same message to several people. Also, TermWorks will remember the line prompt, line delay, and character delay settings for the next time you use them. Once they are set up for the service, they will continue to work in the future. You can also send Macintosh applications and documents with TermWorks. This is traditionally called 'Uploading' files. To do this, prepare the remote to receive file (the computer will tell you how with menu options) and then select Send xmodem from the File menu. Select the file you want to send as usual and click Open. The dialog box will appear apprising you of the status of the transfer. Receiving Files Receive xmodem is used to 'download' files from the remote computer. Most BBS's and commercial services offer various kinds of files which you can download for your own use. To do this, tell the remote computer that you wish to download a file. Most services have menus to guide you. When the remote says it is ready to begin transfer, choose receive xmodem from the File menu. TermWorks will ask you for a name for the file. Enter the name and click Save. After a few seconds, a message will tell you that the transfer is in progress and give the the elapsed time and estimated remaining time. When the transfer is complete, a message will inform you that the file was received successfully. The file is now on the disk you selected when you entered the name for the file. TermWorks automatically detects the format of the file and automatically uses the correct conversion. This means that if the file you receive is a Macintosh file then it will be ready to use with your Macintosh. If the file sent was in text format, then the file you receive will also be text. Breaking the Connection When you've finished communicating with a remote computer, there are two things you should do. First be sure to Log-Off. The remote system should tell you how to do this. It usually involves sending a command such as Quit or Bye. It's important to do this to prevent tying up a remote system so that others can't access it. Most systems will eventually give up on you and disconnect anyway, but it may take many minutes. Also, if you are connected to a commercial service, you may be charged for connect time long after you've quit and gone to bed! Secondly, you should hang up the phone. To do this, select Hang up from the Phone menu. TermWorks will break the connection and hang up. Other Features TermWorks has other features not mentioned in this tutorial. Please be sure to look through the reference section once you're familiar with these basic operations. Where to Start Your first telecommunication attempt can be an intimidating experience. For this reason it might be a good idea to begin with a nice free local BBS. You can usually get the numbers of one or two at your local computer store or from any gathering of Macintosh enthusiasts. The Piney Woods BBS is such a board located in Lufkin, Texas and run by the author of TermWorks. It is available 24 hours a day for free. The phone number is (409) 637-2286. €€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€ Reference This section of the manual contains information on all features of TermWorks. It is organized according to the five menus available in the program: File, Edit, Baud, Settings, and Macros. In addition to the menu reference, there are short sections on program short cuts and keyboard mapping. The Menus The FILE Menu NEW: New creates a new text document in which to record a TermWorks document. A dialog box asks for the name for the file to be created. If the named of an existing file is entered, an alert box asks 'Replace existing?' If you click 'Yes' the previous file will be lost. Untitled is the default document name used by TermWorks. TermWorks will open the last 'Untitled' document when you start the program. OPEN: Open is used to open an existing TermWorks document so that incoming text can be directed to the end of that file. This allows related information to be organized into one file. Note: TermWorks documents can be edited with MacWrite or other text editor as long as the edited copy is saved as Text Only. RECEIVE XMODEM: Receive xmodem is used for receiving files using xmodem protocol. TermWorks uses the correct format conversion for the file being received. In other words, a file being sent in MacBinary format will be received in MacBinary. No binhex conversion is necessary. If the file being sent is Text Only, it will be received as such. Note: Some older systems may have files in old binhex formats, older than version 5.0. TermWorks can not convert these files on its own. SEND XMODEM: Send xmodem is used to send files using xmodem protocol. As with receive xmodem, send xmodem detects the file type and automatically uses the correct format conversion. If the file is of type Text, TermWorks sends only the data fork unformatted. If the file is of any other type, both the data fork and the resource fork are sent using the MacBinary file format. Thus the file does not need to be converted using a binhex program. SEND TEXT FILE: Send Text transfers files of type TEXT with no protocol. It is useful for sending the same text to several recipients or for saving on-line editing time. Generate a 'text only' file with MacWrite or other text editing program. Select Send Text File, click on the name of the file in the dialog box and click 'Send'. The file is sent as if it were being typed on the keyboard. QUIT: Quit is used to exit TermWorks and return to the finder. Quit does not hang up the modem. If you are connected through the modem, be sure to 'Hang Up' using the Phone menu before you select 'Quit' The EDIT Menu UNDO: Undo is not currently supported by TermWorks. It is included solely for the use of desk accessories. CUT: Cut is not currently supported by TermWorks. It is included solely for the use of desk accessories. COPY: Copy works with TermWorks the way it works with all Macintosh applications. When copy is chosen, any highlighted text is copied to the clipboard. PASTE: Paste works with TermWorks the way it works with all Macintosh applications. When paste is chosen, text in the clipboard will be pasted into the open TermWorks document. TermWorks does not currently support graphics. The SETTINGS menu Note: all selected options in TermWorks are marked with a check mark by the menu item. SLOW SCROLL: Slow scroll causes the text in the TermWorks window to scroll up two pixels at a time. This makes the text easier to read as it is being received from a remote computer at low baud rates. Slow scroll is the default setting. FAST SCROLL: Fast scroll feeds text up normally one line at a time. RECORD TEXT: Record text, when selected, causes TermWorks to save incoming text into the currently open document. If Record text is not selected, the text will not be saved. The default setting is Record text on. LOCAL ECHO: Local echo, when selected, tells TermWorks to echo text to the Macintosh screen as it is transmitted. The proper setting for this option depends on the remote computer. Local echo on corresponds to half duplex on some systems and local echo off corresponds to full duplex. The proper setting can be determined by watching the screen as you type. If characters appear double, turn local echo off. If characters don't appear at all, turn local echo on. The default setting is local echo off. ADVANCED SETTINGS: Brings up a dialog box that allows you to select advanced communications settings including data bits, stop bits, parity, and the serial port TermWorks should use. Warning: You should not use a serial port that is being used by some other device such as a hard disk, printer, or AppleTalk. The PHONE menu: DIAL SERVICE: Dial service is used for dialing a remote system. When selected, a dialog box appears for entry of the name of the remote computer and the phone number. If the dial button is clicked, TermWorks will try to dial the number until a connection is established. Press the mouse button once to abort the dial. This function is also used to edit entries in the phone directory. If one of the ten directory listings is selected (a check mark denotes a selected entry) the information pertinent to that entry will appear in the dialog box. Any changes to that information will be stored in the directory when the Dial button is clicked. Auto-logon In the dialog box under Dial Service, there is a place for an auto-logon procedure. The procedure language is a simple set of one-letter commands followed by one parameter. An auto-logon procedure is very useful, easy to make, and store permanently with the service. The commands that can be used are as follows: T - Type a specified string of characters. L - Look for a specified string of characters. M - Type a specified macro key (0-9). W - Wait for a specified number of 1/60ths of a second. The following example would wait 1 second, type a carriage return, look for "?", type a the first name "Joe", look for "?", type the last name "Smith", look for "ord:" (end of Password:), and type the password "QQQWWW". W60 T"^M" L"?" T"Joe^M" L"?" T"Smith^M" L"ord:" T"QQQWWW^M" This would successfully log-on Joe Smith with the password QQQWWW to the Piney Woods BBS. HANG UP: Hang up is used to break the modem connection with a remote computer and hang up the phone. The proper log-off command should be executed first. The other ten entries under the Phone menu are for the phone directory. By selecting one of these entries, the name, phone number, baud rate, scroll rate, and Local echo setting for that service are recalled. Just click Dial to proceed with the connection. The MACROS Menu Macros are short commands, usually 10 to 30 characters long, that can be entered into TermWorks and then recalled by pressing one key. Use macros for any sequence of key-strokes that are used repeatedly. Name, password, and other log-on sequences are candidates for macros. EDIT MACROS: Edit macros is used to enter the macro commands. A dialog box opens allowing up to 40 characters to be entered for each macro. When satisfied, click 'OK'. and the macros are ready for use. MACROS 1 through 10: To use a macro, either select it from the menu or hold down the command key and press the appropriate number. The macro will be sent just as if it were being typed from the keyboard. The short cuts TermWorks offers several short cuts for the advanced user. None of these are essential to the program. They merely provide faster access to some of its features. QUIT: Hold down the command key and TermWorks will eject both drives and re-boot the Mac instead of quitting to Finder. DIAL SERVICE: Hold down the command key and select a service and TermWorks will dial the service immediately by-passing the dialog box usually presented. THE TERMINAL WINDOW: Hold down the command key and you can click all options in the terminal window without it being brought to the front of other windows. Keyboard mapping The keyboard is always configured to be a standard ASCII or TTY terminal. The backspace key is used to generate a BS code (Hex 08). The " ` " key in the upper left-hand corner of the keyboard generates an ESC code (Hex 1B). To generate CTRL codes, hold down the Command key (the clover-leaf key) and press any key from A-Z. If a service you are connected to says you should use CTRL-C to cancel text output, you would press Command-C. Notes from the Author TermWorks will continue to be upgraded and improved for some time to come. This documentation will be revised as needed. Version 1.29 will probably be the last Shareware version of TermWorks. I plan on making TermWorks a commercial product and a full-blown communications program. Don't worry, I will include as part of the commercial package the simpler version of TermWorks which will be very similar to 1.29 with a few improvements. TermWorks is being distributed under the Shareware system with a twist. It works like this. You receive a copy of this program from a friend. You try it out and decide that it's a pretty good job and that you want to use it. You fill out the registration form in the distribution notice in the Apple menu and send it in with your check for $20.00. You receive a disk by return mail with the latest copy of TermWorks, this documentation and a unique serial number registered in your name. The registration form you send in had the serial number on it of the person who registered that copy. He will receive $5.00 as a finder's fee. You then make copies of your disk with your serial number on it and distribute them to your friends. If any of them registers TermWorks, you will get the $5.00 finder's fee. Get four people to register and your copy is free! llllllllllllllll