Z-Link: Telecommunications for the Apple // ------------------------------------------- Z-Link is a program for the Apple // that is small, fast, and powerful. It includes everything you'd expect from a good modem program - a text capture buffer, robust terminal emulation, a split-screen person to person chat mode, and the ability to transmit and receive files using several different transfer protocols including XMODEM/Checksum, XMODEM/CRC-16, YMODEM/CRC-16, and YMODEM/Batch as well as compatability with Ascii Express Pro and Mousetalk. The program currently runs on an Apple //c and //c+, Apple //e, or Apple //GS under ProDOS 8. This program is shareware. Try it out for a few weeks. If you don't like it, just delete it. Otherwise, send me $25. Required equipment ------------------ Z-Link will work on a //c or //c+, a //GS, or an enhanced //e with a 128k 80 column board in slot 3 and a Super Serial Card (or exact equivalent). If you are using a Super Serial Card, you'll need to set the switches on the card appropriately. Set switches 1-5, 1-6, 1-7, 2-6, and 2-7 ON. The other switch settings don't matter. If you don't own a Super Serial Card, you'll need to engage interrupts on your card (SW2-6 on the SSC does this.) Look it up in your manual. If your card can't generate interrupts, then Z-Link won't work with your card. If you are using an internal modem (such as the DataLink by Applied Engineering), be sure that it "looks" like a Super Serial Card and it is capable of generating interrupts. (I really don't know which internal modems are capable of what and how compatible they each may be). If you have no idea whether or not your card generates interrupts, just try Z-Link. If the commands you send to the modem echo properly, and the modem responds, then all is ok. If you are using an Apple //GS, then be sure that the control panel is set apporpriately. If you plan to use an internal modem, be sure that the control panel setting for the slot the card sits in is set to "Your card." You may use either of the built in serial ports. Just be sure that the control panel setting is set to "Printer Port" for slot 1 or to "Modem Port" for slot 2. I recommend using the built in port on a //GS, as the firmware in the computer is much better at managing things. Note that the control panel settings for either port (such as baud rate, etc.) are ignored. Z-Link overrides all the settings, but does not permanently change any of them. Starting up ----------- The program is a SYS file which can be launched in a variety of ways: from the Apple // DeskTop or Finder, from BASIC, by quitting another application, or by making it the first SYS file in your directory to cause it to automatically load during booting. Once loaded, the title screen holding my plea and address will be displayed. Hit any key to go into terminal mode. Note: In June of 1988, Z-Link was invaded by a virus. If you are unfamiliar with the nature of a computer virus, it is sufficient to know that they work very much like a virus in a person: it spreads from unit to unit rather quickly and after a certain amount of time, damage is done. The poisonous Z-Link is travelling under the name "Z-Link Plus". Avoid it like the plague. The virus hidden in Z-Link Plus spread far and wide very fast, and it did tremendous damage. As a result, Z-Link includes some rudimentary virus checking. If Z-Link has been infected by a virus, you will be automatically warned within a reasonable degree of certainty. Delete your current copy and get the latest version by sending a self addressed stamped disk mailer with a disk (either 5.25" or 3.5") and the $25 shareware fee and I'll send you a fresh, uninfected copy. Obviously, you may send me a disk any time for an update of Z-Link. Please remember that I am a busy student and it may be some time bewteen when I get your disk and when I actually return it to you - however, I *will* return it to you. Also note that I am not likely to return to you a copy of Z-link if you haven't yet paid the shareware fee. I try to avoid freeloaders. The virus detection is only useful in the event a virus already present in your system tries to infect Z-Link. Should a malicious person manually infect Z-link, or any other program, he could easily remove any detector present in that program. Therefore, don't accept Z-link from any questionable source, and practice safe computing. Commands -------- Once in terminal mode, you can press Open-Apple and "?" for a help window. The window contains a list of commands currently available. Toggle-parameters also have their current state shown. A description of the commands follows: Open-Apple T - Toggle terminal emulation Z-Link comes with a terminal emulator that can handle Heath h19 (otherwise known as VT52) and VT100 (or ANSI) terminals. If you don't plan on using a mainframe with Z-Link, terminal emulation will most likely be useless to you. If you are using a mainframe, you can use h19 terminal emulation by pressing OA-T once. You can use vt100 emulation by pressing OA-T once again. Press OA-T once more to turn emulation off. If you've directed Z-Link to emulate an h19, then tell the mainframe you are using an h19, HEATH, or vt52 terminal. If you've directed Z-Link to emulate a vt100, tell the mainframe you are using a vt100, vt102, or ANSI terminal. Note that DEC computers use a slightly different way of presenting the emulation codes than Z-Link can handle so you should use ANSI on DEC computers. Note that only screen emulation is available by direct code within Z-Link. A good vt220 keyboard re-mapping was written and distributed and it does much of the necessary work for me. The vt100 emulation is currently quite robust, but bugs exist. I am constantly finding and fixing obscure bugs. If you locate a bug, let me know. I may have already dealt with it. Open-Apple V - Toggle control-show This is pretty useful for debugging purposes. If the other end is sending codes to your Apple and it's causing strange things to happen, just hit OA-V. While control-show is on, all characters received with ASCII codes less than 32 will be printed to the screen with a carat just before them. For example, a CRLF will be viewed as "^M^J". Absolutely no control codes will have any sort of effect. As a result, terminal emulation is disabled while control-show is on. Open-Apple C - Toggle capture buffer Upon startup, Z-Link opens a file on the /RAM disk called BUFFER. (This is why you need 128k: Prodos otherwise won't make the /RAM disk, and bad things will happen after that...) While capture is on, all characters received will be saved to the file /RAM/BUFFER. Once the whole /RAM disk is filled, Capture will be turned off. At this point, you should save the buffer to disk (which clears out the buffer). (Yes, I will put in an auto-save feature, but that's not available right now.) Note that you can change the name Z-Link uses as the buffer file. See the section, "Changing Default Pathnames" for details. Open-Apple E - Toggle local echo If you don't ever see what you're typing, hit OA-E and all will be well again. Local echo "on" just re-routes all typed characters right back to the screen. Note that this means that those characters will be sent to the capture buffer if it is enabled. Note also that you can play with the terminal emulator by manually typing the code sequences if you know them. IIff eevveerryytthhiinngg iiss ddoouubblleedd,, then turn off local echo. Open-Apple L - Toggle auto-linefeed If what you see is appearing on one line only, then you need to have Z-Link add in the line-feeds that the other end isn't sending. This usually comes up when talking direct with another person. If everything is coming out double-spaced, then the other end is sending the linefeeds, and Z-Link doesn't need to supply them. Turn auto linefeed off if this happens. Open-Apple K - Toggle chat mode Chat mode is a split-screen chatting environment which is most useful when being used between two users of Z-Link. In chat mode, everything you type will appear in the upper half of the screen. Everything the person on the other end types will appear on the lower half. Terminal emulation is disabled by chat mode, and auto linefeed and local echo are automatically turned on. If you have the capture buffer turned on, the characters will be stored in the order they are printed on the screen. What tends to happen is you'll get a buffer full of semi-garbled gook. "WelDol,n't hotalkw ato mere nyow!ou?" If the person on the other end isn't using Z-Link, or doesn't have chat mode turned on, then his screen will look pretty bad too. Simulataneous typing is allowed in chat mode, and things will be properly separated for someone in chat mode. Obviously, people who don't have chat mode will see gook on their screen. By pressing Open Apple while in chat mode, you can adjust the position of the border between the top and bottom halves of the screen. Just use the up and down arrows to position the border where you want it and press to store the new position or to restore it to its old position. Auto linefeed is automatically turned on with its old state saved away. (When you quit chat mode, the auto linefeed state will be restored.) This affects only the bottom half of the screen. Auto linefeeding always happens on the top half. If you use chat mode in conjunction with particular online utilities (such as those found on GEnie) and the bottom half is being printed in double space, turn auto-linefeed OFF. Open-Apple-up arrow - Upload a file (Send) This starts up file transfer for transmission. You can pick any of the protocols in the window. If you decide to cop out, hit . It will return you to terminal mode. See the section, "Choosing From a Menu" for details on how you can choose things. Option 1 is the standard Xmodem transfer mode. Just about every modem program worth the space it takes supports Xmodem. If you don't know what protocol to use, choose this option as it is most likely to work. Note that the receiving end dictates whether CRC or Checksum error detection will be used. Checksum error detection is pretty simplistic, and provides adequate error detection. Basically, as each byte is sent, its value is added into a running sum. (This sum starts off at zero for each packet.) After the packet has been sent, the lowest 8 bits of the total sum is sent. The receiving side performs the same addition and compares its result to the one received. If the results don't match, an error is signalled and the packet is resent. CRC is an acronym for "Cyclical Redundancy Check." One considers all the bits in each packet to be the coefficients of a polynomial (which is of the order x^1023 for 128-byte packets and order x^8191 for 1024-byte packets). The polynomial is multiplied by x^16 and then divided by x^16 + x^12 + x^5 + 1 using modulo 2 arithmatic. The coefficients of the remainder of this division are used to make up the bits of an encoded message. In CRC-16, the lowest 16 bits of the encoded message are sent. The receiving side performs the same calculation and compares its result to the one received. If the results don't match, an error is signalled and the packet is resent. This method detects all single and double bit errors, all errors with an odd number of bits, all burst errors of length 16 or less, 99.997% of all 17-bit bursts, and 99.998% of all 18-bit and longer bursts. In other words, it's very reliable. Option 2 is an Ascii Express/MouseTalk compatable transfer mode. The AE protocol is a slight addition to the XMODEM/Checksum protocol in that it sends ProDOS file attributes after the file contents have been sent. AE will step down to XMODEM/Checksum if the other end doesn't seem to want to talk. Option 3 is similar to XMODEM/CRC except that it uses 1k data packets. This reduces the time overhead when sending huge files. Regular Xmodem has a 3.75% overhead while Ymodem has a 0.48% overhead. Unlike other packages which may implement YMODEM/CRC, Z-Link automatically reduces the packet size to 128 bytes as it gets to the last 1k to transmit. This makes disk overhead on the receiving computer no worse than when using XMODEM. Option 4 is a new batch transfer protocol developed by Chuck Forsberg. The UNIX programs rb and sb support YMODEM/Batch, as do several programs in the IBM world. Because of its ease-of-use, I decided that it would be an excellent addition to Z-Link. It allows the transfer of several files (hence Batch) while retaining all file attributes. Also, only the sending user has to type filenames - the names are transmitted along with the attributes before the file contents are sent, so the receiving side must only start up his end without having to type filenames. Option 5 is a straight ASCII dump. It is intended for sending text files only. No error detection is used. It's as if you become a master typist. After choosing a protocol, a standard file dialog appears. This dialog is similar to the one in ShrinkIT (a very handy archive utility by Andy Nicholas). When the dialog appears, you'll see the contents of the default upload directory. See the section, "Changing Default Pathnames" for details on setting the upload directory to your choice. See the section, "Choosing Files in the Standard File Dialog Menu" for details on selecting files. Once the name(s) are entered, the file(s) will be transferred according to the protocol selected. If an error should occur, the computer will beep and increment its error count. The progress display shows the number of bytes that have been successfully sent as well as the byte location of the last error. The error count is shown as two numbers: "x/y". X indicates the number of errors while trying to transmit the current packet while Y indicates the total number of errors while sending the current file. ASCII uploading has no error detection method. If an error occurs during an ASCII upload, tough luck. If more than ten errors should occur within the same data packet, the transfer will be aborted. This is a rare occurance, and only happens with a really bad phone connection. Because the transmitting end is never the source of an error signal, the type of error can't be reported. If you for some reason decide you don't want to send that file, you can hit to stop the transfer. Note that within a batch transfer, if things are aborted either by too many errors, or by you hitting , the whole transfer will stop, not just the current file. Because the different transfer protocols use different packet sizes, transfer progress is reported in Bytes Sent. If you are using XMODEM, packet size is 128 bytes. YMODEM uses 1024 byte packets, but automatically drops to 128 bytes per packet when there is less than 1024 bytes left to transfer. This eliminates the old "send the 1k packet holding 30 bytes of data" problem. Open-Apple-down arrow - Download a file (Receive) This is very much like the Upload section, except that you can't do ASCII receive here (you would noramlly use the Capture Buffer). Select a protocol and enter the filename as before. Note that the contents of the default download directory appear in the window. If you are using YMODEM/Batch to receive files, then the window will only show subdirectories. When the current prefix is set to your satisfaction, choose "Select Current." All incoming files are preceded by their name and they will be stored under that name in the directory you specified. Note that filenames received will be coerced to the ProDOS naming convention (15 or fewer characters in the file name or less than 64 characters in the whole pathname; first character is alphabetic; only alphanumeric characters and "." allowed in the name). If a name does not conform to the ProDOS rules, proper measures are taken to avoid dumb errors. Once the transfer has started, a progress report window will appear. Because there can be several causes of a transmission error, Z-Link will notify you of the exact cause of any error that might occur. As always, errors are rare unless there is a very noisy phone connection or there are long delays on the other end (this happens primarily with mainframes). The error count is shown as two numbers: "x/y". X indicates the number of errors while trying to transmit the current packet while Y indicates the total number of errors while sending the current file. If more than ten errors occur on the current data packet, then the transfer will be aborted. To cancel the file currently being sent, just press . Note that within a batch transfer, the whole batch will be stopped. If you are using YMODEM/CRC to receive files, and the transmitting program is NOT Z-Link, then the file saved on your disk may occupy up to 1k extra space on your disk. Because Z-Link reduces the transmitted packet size toward the end of the file, this won't occur if the sending program is Z-Link. Note however that there are a few smart programs out there, and they will reduce the packet size as well. See the section, "Error Codes" for a description of the various errors that can occur and what they really mean. Open-Apple left arrow - Slow down cursor blink rate This, and the next option, is for your taste. If you don't like the speed at which the cursor blinks, then you can slow it down by pressing OA-left arrow or- Open-Apple right arrow - Speed up cursor blink rate speed it up by pressing OA-right arrow. Note also that one of the "speeds" is no blinking at all. Open-Apple A - Enter an AWAIT string This option is primarily for use from within a macro. No dialog window is drawn to save execution time. When OA-A is 'typed' by the macro, Z-Link waits for a string (up to 20 characters). The string is terminated by a . Once entered, Z-Link cuts off keyboard input until the string (not including the ) is received from the modem. Cutting the keyboard effectively freezes the execution of the macro. This allows for very powerful macros. For example, to dial the modem, wait for connect, and login, a typical macro would be: ATDT5551234 CONNECT Login: Username Password: secretword If, for some reason, things go sour while a macro is running, just hit to break out of it. You will be returned to normal mode. Open-Apple 0 - Toggle title screen printing As some of you become more acquainted with Z-Link, you may become tired of seeing the title screen all the time. The current state of this toggle is not shown in the help screen because it is to be used so rarely, and once the program has started, its setting is irrelevant. To put this feature to good use, set up your terminal the way you want it and shut off the logo screen printing by hitting OA-0 once. Then save the current settings (see the section, "Save/Load Terminal Settings" for details) under the name "Z.LINK.CONFIG." The next time you boot, the title page will be skipped and you'll be put directly into terminal mode. Open-Apple B - Send BREAK signal Some systems require you to send a BREAK signal so that they can recognize how your terminal is set up (baud, parity, etc.) To send a BREAK signal, just hit OA-B. Open-Apple S - Save/Load terminal settings This feature allows you to save and later re-load the current settings of Z-Link. For example, on bootup Z-Link sets the serial port to 1200 baud, 8 data bits, no parity, and 1 stop bit. You can change these values, but they will be changed back the next time you run Z-Link. By saving the terminal settings, any changes you make can be loaded back in when you want them. Note that on bootup, Z-Link checks for a file called Z.LINK.CONFIG, which you can make by starting up Z-Link, configuring it the way you like it (perhaps a higher baud rate) and then saving the terminal under the name Z.LINK.CONFIG. Now, your favorite settings will be loaded automatically every time you run Z-Link. Note also that versions of Z-Link dated before June 1989 used an outdated structure for saving terminal settings. You must run the utility MACRO.UPADTE (See the section, "Updating Settings Files" for details) on any settings file created by an older version of Z-link. To load or save the current settings, press OA-S. A menu will appear with the choices "Load Settings" and "Save Settings." See the section, "Choosing From a Menu" for details on choosing things. Z-link will then ask for a filename. The conents of the directory where Z.LINK.SYSTEM resides will come up. Note that only settings files and subdirectories are visible. Either select the file to load or enter the name of the file to save. See the section, "Choosing Files in the Standard File Dialog Menu" for details. Open-Apple R - Reset terminal state to normal This is useful in the event of a sudden burst of noise of the phone: "Dear, what's that strange sound on the phone?" When the terminal emulation is turned on, there is the slightly odd chance that the noise on the line will represent several emulation codes and this will direct Z-Link to do strange things. If you suddenly have a white screen and the characters are illegible, hit OA-R to set things straight. This option does not affect any of the settings in Z-Link (such as baud rate, etc). You must make any such changes yourself. It does, however reset certain flags that may have been set by the terminal emulator (such as insert-character mode). I'm not sure how this will affect whatever program you may be running on the host (such as Emacs). Open-Apple W - Change data word format Pressing OA-W will allow you to change any of the communcation parameters, including baud rate, data word size, number of stop bits, parity, and the serial card slot. Set them to your heart's desire, or whatever that BBS requires. To change a particular value, use the left and right arrow keys. To switch fields, use the up and down arrow keys. When you're satisfied with the values, press . Note that you can change where Z-Link should expect to find a serial card. Your choices here are represented by where you actually have a serial card. Unfortunately, serial cards, parallel cards, and AppleTalk cards all look alike to Z-Link. Be careful not to try to use an AppleTalk card as a serial card. It plain won't work. Apple //GS users: You *must* have the control panel set appropriately for this to work. If your serial card is in slot 4, then slot 4 must be set to "Your card" and not to "Mouse port." Z-Link identifies the cards in the various slots by looking at the ID bytes there. If you have the control panel set wrong, then Z-Link won't identify your card. As a feature, if upon bootup Z-Link doesn't find a serial card in the slot where it's supposed to look, then this window will appear. The first thing you should do is set the correct slot. When you quit the dialog, Z-Link will continue the startup process. If you don't have any cards that can be identified as a serial card, then Z-Link will complain and then quit back to ProDOS. Open-Apple 2 - Show the 25th line Several applications make use of a status line which is normally addressed as the 25th line. The Apple // does not support a 25th line in any way, shape, or form. In order to see what is currently on the 25th line, press OA-2. The screen will scroll up one line and the contents of the 25th line will be visible at the bottom. Press any key to scroll the screen back down and hide the 25th line. Note: in order to properly implement every nook and cranny of screen control for the 25th line, every time a character is printed on the 25th line, the entire 25th line will briefly flash on the bottom of the screen. This may get annoying. I'll work on it. Open-Apple H - Hang up the modem (cuts DTR) This is useful if, for some reason, the host you are connected to suddenly decides not to talk to you any more. If things get locked up, you can force the modem to hang up by pressing OA-H. This actually cuts the DTR signal on the serial line to the modem. Most modems will hang up the phone if DTR is cut off. Some modems have a switch which causes them to ignore the state of the DTR line. With this switch set properly, you can make this command useless. Be sure that the modem is not set to ignore the DTR signal. There are also some serial cables which tie the DTR line permanently high. These will also make this command useless. Note: if you are using a //e or a //c, pressing RESET will also cut off DTR. On a //GS, pressing RESET will not cut DTR. The dialog will remain on the screen until you press a key. This is so you can keep DTR cut off until you actually want it back on. Most modems will not auto-answer if they do not see a DTR signal. Therefore, this is a simple way of quickly killing auto-answer and quickly re-establishing it. Open-Apple P - Pause briefly This option is used primarily from within macros. If you press OA-P, the computer freezes for abou a half second. This is useful for those systems that require that you hit return a few moments after the connection is established. A typical macro would be: ATDT5551234 CONNECT . . . Open-Apple N - Change default pathnames Z-Link contains a few default pathnames which hold the path to the capture buffer, an uploads directory and a downloads directory. Z-Link comes set up as "/RAM/BUFFER" is the capture buffer path and the upload and download directories are both "/" (undefined). If you have a //GS, you could configure your RAMdisk to be bigger than 64k. In such event, you'd want to change the capture buffer pathname to /RAM5/BUFFER. Don't have your capture buffer on disk. This sounds tempting, but ProDOS shuts off interrupts for too long when writing to the disk. You'd lose an awful lot of data. Upload and download directories are especially useful for hard disk owners. It sort of forces you to be slightly more organized. You would ordinarily place everything to be uploaded into the upload directory and then send them off. Everything you download would land in your download directory. This makes it easier to find where all the downloaded stuff went. Note that you are not really forced into anything: you can edit the pathname just before you download a file (see the section, "Choosing Files in the Standard File Dialog Menu"). To change any field, just use the DELETE key to rubout. Press the CLEAR key or Control-X to clear out the entry. Press it again to restore the entry to its previous setting. Press TAB to move to the next field. Although it isn't checked for (yet), you should not enter anything but a directory name for the default upload and download directories. The capture buffer path should point to a file on a RAMdisk. If the capture buffer file does not exist, it is created. If it does exist, then further capturing will be appended to the end of the file. Open-Apple D - Save capture buffer to disk You can use this feature to save the contents of the capture buffer to your disk. After saving, the capture buffer is cleared. This routine uses the standard "get-name" dialog used throughout. See the section, "Choosing Files in the Standard File Dialog Menu" for details. Note that the default download prefix comes up. Open-Apple Z - View capture buffer This is really a generic "view a text file" feature. It automatically presents you with the pathname of the capture buffer. You can view any other text file by moving around the disks and directories (see the section, "Choosing Files in the Standard File Dialog Menu" for details). Whatever file you view, its prefix will be stored as the default for the next time you hit OA-Z. This feature exists on the presumption that you want to view several files that sit in the same directory. While viewing a file, you can press any key to pause the output. Just press any key to continue the output. If you've seen enough of the the file, press to stop. After the whole file has been printed, the computer will pause briefly and then wait for you to press a key to go back to terminal mode. Press any key, and the screen will restore itself to its old state. Note that the characters printed from the file are sent through the same routine that handles screen output during regular execution of Z-Link. Therefore, if you've captured text which contained lots of emulation codes, then viewing the buffer (or the file you may have saved the buffer into) will execute the same emulation sequences. This can be quite amusing. Note also that you may have to play with the Auto Linefeed setting to get files to print on more than one line. Open-Apple ? - Help Hit OA-? and the help screen will pop up. It will show you the list of current commands and the title of that command. The titles in the help window are the same as in this document. The current settings of all the toggle parameters will be shown next to the command description. Also, the terminal type that the emulator is doing will be displayed (h19 or vt100 or OFF). While the help window is up, you may type one of the OA-commands to execute that command (no need to press some other key to escape to the terminal first...) Open-Apple X - Exit Z-Link When you are all done using Z-Link, hit OA-X. A menu pops up with three choices. See the section, "Choosing From a Menu" for details on how make a choice. If you choose "Quit DTR ON", then Z-Link will quit back to ProDOS, but it will maintain the connection to the modem. This is handy for running some other utility without going through the hassle of logging out and then logging right back in. If you choose "Return", then you will be returned to terminal mode. You'd do this in the event of accidentally hitting OA-X. If you choose "Quit DTR OFF" then Z-Link will close the connection to the modem and clean up and then quit to ProDOS. You'd choose this to really quit Z-Link. Note that older versions of Z-Link had a yes/no question for this dialog. To keep older users happy, the old keystrokes still work. Hit 'N' for "Return," 'Y' for "Quit DTR OFF," and 'X' for "Quit DTR ON." Open-Apple Y - Clear capture buffer This option allows you to clear out the capture buffer. Saving the buffer also clears it. Open-Apple F - DOS commands This command provides you with some basic disk manipulation. A menu appears with three choices: "Delete a File," "Rename a File," and "Create a Subdirectory." See the section, "Choosing From a Menu" for details on making a choice. Enter or select file to operate on (see the section, "Choosing Files in the Standard File Dialog Menu" for details). If you choose to delete a file, Z-Link will ask for confirmation before deleting anything. You must type a 'y' to delete the file. If you choose to rename a file, a new dialog will appear. The complete pathname of the file you selected appears in the window. You may now edit only the part of the path which represents the file. If you do nothing at all, then the file will not be renamed. You may press to abort. Press when you have the file named as you like. If you choose to create a subdirectory, then the directory you specify will be created. Choosing From a Menu -------------------- All menus in Z-Link operate in the same fashion. Use the up and down arrows to move the selection bar. Press to select the item the selection bar is on. Press to abort out of any menu and return to the terminal. Some menus allow you to press other keys as well as the standard ones. For example, the uploads protocol selection menu allows you to to type the number of the item you wish to choose. This is for ease of use for those who have been using older versions of Z-Link (namely, me). All menus that experienced users are accustomed to still work the way they used to. I am deferring telling new users what the old keys were to make it easier for me to change things in the future. Choosing Files in the Standard File Dialog Menu ----------------------------------------------- The standard file dialog is an attempt to emulate the SFGetFile dialog available to //GS users and Macintosh users. The window consists of four fields: the command field, the path field, the file list, and the typed filename. Because Z-Link doesn't use a mouse, the commands needed to move around the directory structure are implemented in the file list (as opposed to have "buttons" to click on). Regular files appear in the list without any graphic identifying them. Subdirectories and disks have a folder graphic preceding the name. Commands in the file list are identified by a double-greater-than (">>") graphic preceding the name. The current commands are "Parent Prefix," "Scan Disks," "Start Upload," "View List," and "Select Current." A command only appears if it is appropriate to the function. For example, "View List" only appears if you are to choose several files. If you choose View List, then the list of files you have selected so far (up to 32 of them) will appear. Selecting "Parent Prefix" moves you one level higher in the directory structure. If you are at the top level and you select Parent Prefix, then the list of available disks appears. The command "Parent Prefix" disappears and is replaced by "Scan Disks." You would scan disks if you eject a disk and insert a new one. "Start Upload" only appears while you are selecting files for a batch upload. The current system allows you to select up to 32 files for batch upload. Once you select 32 names, the upload starts automatically. To send only five or so files, you would select the files and then select "Start Upload" to proceed. "Select Current" only appears while you are selecting a location for a batch download. Once the prefix is set to your desire, you would choose "Select Current" to start the download. The file list will display only files relevant to the current operation. For example, if you're loading a terminal settings file, only terminal settings files and subdirectories will appear in the file list. This is put in to prevent you from trying to load a directory as a terminal settings file. Use the up and down arrow keys to move through the file list. Press to select the file or command that is currently highlighted. Press at any time to abort and go back to the terminal. If you select a subdirectory, then that directory will be added to the prefix, and the contents of the directory will be displayed. This means that you can't select a directory itself for any operation (such as Delete or Rename). For any operation that requires you to create a new file (such as saving a terminal settings file), then the file dialog will have a slight change. Two arrows will indicate that you are to enter a filename. Once you start typing a filename, pressing RETURN will not select the item in the file list currently highlighted; it will instead enter that name and proceed with the operation. To stop entering a name, hit either up or down arrow. Once you do, the name will be cleared out. Some hidden features -------------------- Z-Link filters out unwanted control characters so that they don't botch the 80 column screen. Even though they're never "printed", they will go into the capture buffer file if the capture buffer is on. Z-Link has a few random macros built in which will be described below. Z-Link also supports an automatic macro. When Z-Link starts, it looks for the macro defitition Closed Apple . If that macro exists, it is run. This macro would typically be some modem initialization commands, but it could be anything. Just define the macro CA- (see below) and that macro will be executed at startup or whenever the settings file containing the macro is loaded. The Macro Editor ---------------- There is a separate macro editor written and graciously donated by David Lyons (of DAVEX fame) which will allow you set up macros to do just about anything. Note that the current version works only on settings files created by a version of Z-Link dated after September 1, 1989. If you config file is too old, then run MACRO.UPDATE (see the section, "Updating settings files"). Any key or key+modifier (such as Closed Apple) can be turned into a macro key. Exactly what you program it to do is limitless (almost). Macros can call other macros, up to 127 levels deep. You can program in as many as 256 macros, and the space alotted for macros is roughly 2k (I can expand it if need be). In order to use the editor, you must first run Z-Link and save a terminal settings file and then run the editor. Once the program has started, you must load the settings file from disk. Choose option 1 to do this. The editor will prompt you for a filename to edit with the default of "z.link.config." Type the same name you used to save the settings from Z-Link or hit to choose "z.link.config." You can now view all the defined macros in this file, add new ones, or delete ones you don't want. Once you've completed all the changes you wish to make, choose the Save option. The next time you load that settings file, it will bring in the macros you defined. When viewing (or entering) macros, the program uses certain conventions. "CA-" is printed to indicate that the Closed Apple (Option) key is being pressed in conjuction with some other key. "OA-" means the Open Apple key; "KP-" means the key pressed was on the numeric keypad (for those using ADB keyboards - that's //GS people); "space" means the space bar; "delete" means the delete key; "return" means the return key - you get the picture. Control characters (not including Backspace and Return) are printed with a carat (^) appearing just before the character. For example, control-L will be printed as "^L". This is just like in the control-show mode of Z-Link. Select the Add new macro command to add another macro. Fisrt, you must specify the key combination to be the inducer of the macro. You can type any key or key combo which does not include the Open Apple key. Open Apple combos are reserved for Z-Link commands. Now, enter the string that this key is to simulate. Note that anything you can type in Z-Link can appear within a macro definition - including text, Z-Link commands, and even another macro call. Macros can call macros like subroutines as many as 127 levels deep. As you type characters, they appear as they would when you View Current Macros. If you make a mistake, you can rubout by hitting Open-Apple-Delete. To finish off entering the macro, hit Open-Apple-Return. Note that every key typed while running Z-Link in terminal mode is checked if it is a macro inducer key. For this reason, you may have wound your way into a corner by inadvertently writing a loop. Here's an example: You've made the Delete key a macro inducer that just sends the backspace character and now you want it so Closed Apple-Delete will send a real delete code. The only problem is this: When you type Closed-Apple-Delete, a Delete key is imaginarily typed by the macro system. This of course is mapped into a backspace. In order to avoid this problem, the macro entry mode has a special key. Hit Open-Apple-X to cause the next character entered to be ignored by the macro-inducer mechanism. (It also has the effect of making the macro entry routine ignore what it is. This way, you can enter an Open-Apple Return or Open-Apple Delete into the string.) Here's how you would enter the previous example: Make the macro to have the Delete key type a Backspace. Now, create the macro for Closed-Apple Delete, only when you enter the string for it, type Open-Apple X then Delete. Now, when you type Closed-Apple Delete, the system looks up the macro and sees that it is specially marked. The Delete key is imaginarily typed, but it is forcibly *not* looked up in the table. The delete code will be sent as expected. If you have macros defined that you don't want, you can delete them by selecting the Delete a macro option. Enter the key combo representing the macro, the the associated macro will be removed from the list. The following macros are included with Z-Link: CA-forward arrow -> ^F CA-back arrow -> ^B CA-up arrow -> ^P CA-down arrow -> ^N and for //GS people (keys on the keypad): 8 -> ^P These are the basic motion commands in EMACS. 4 -> ^B The position of these keys on the keypad 6 -> ^F ought to make the functions obvious. 2 -> ^N CA-8 -> v CA-4 -> ^A CA-6 -> ^E CA-2 -> ^V Updating older Settings Files ----------------------------- The MACRO.UPDATE program was designed to bring the macro entries out of config files created by version of Z-Link dated before August 1, 1989 into the more up-to-date arrangement. I have done all I can to make updating as painless as possible. In order for this program to be of value, you must start up Z-Link fresh (ie, no Z.LINK.CONFIG file present) and save as many config files as there are files to be updated. This creates the template for updating. Now run the MACRO.UPDATE program. Enter the name of the old config file and the new file to put the macros in. It will copy all the macro entries out of the old config file into the new one and then save the update. At this point, you may delete the old config file. Note that this utility won't move over any other paramters you may have set. Go into Z-Link and load your new config file and set the other parameters as you wish. Note that you do not need to go through this procedure for any settings file created by a version of Z-Link dated after September 1, 1989. Download a file errors ---------------------- The errors that can occur are: Timeout error SOH error Block number error Short block error Long block error CRC/Checksum error The timeout error occurs at the beginning of a block. If Z-Link doesn't receive any indication that a block is on the way (it timed out), it will send an error code (a NAK character) and wait some more. A SOH error is an error with the Start Of Header character. The character received was not ASCII $01 or $02 - the only valid values at this time. A block number error occurs if a) the block number sent to Z-Link isn't the one it was expecting or b) the error checking on the block number failed. A short block error occurs when there isn't enough data to fill out the block and CRC/Checksum. It figures this happens by using a timeout check when waiting for the CRC/Checksum. If it times out while waiting for the CRC/Checksum code(s), it means that a byte was lost somewhere. A long block error occurs only if the CRC/Checksum check failed AND there is more data in the queue. More data in the queue indicates that a byte was inserted somewhere and now there's too much data. A CRC/Checksum error is reported when the check fails and there is no more data in the queue. This error usually means a line hit and some data was corrupted. It is entirely possible that the data packet was valid, but the CRC/Checksum got corrupted. Either way, a NAK is sent and the block should be re-sent. The display shows an error count as two values: x/y. 'x' indicates the total number of errors that have occurred on this file while 'y' indicates the number of errors while attempting to receive the current packet. If more than ten errors occur on the current packet, the transfer is aborted. --- I have received a few suggestions for improvement, and I'll be working on them. They are: Binary II transfer and other smaller-scale things. Feel free to send any suggestions/comments/bug reports to: dcw@goldilocks.mit.edu (Internet) or Dave Whitney 450 Memorial Drive Cambridge MA 02139 I use Z-Link exclusively, and quite frequently. If you do find a bug, I am interested as a developer *and* as an end-user. P.S. Don't forget the $25 shareware fee. Those who do send me a check should also send me some e-mail plainly stating you've sent me $25. You will then receive updates and improvements by direct e-mail as I make them. If you don't have net access to the above address, you can send a SASE with a disk in it (5.25" or 3.5") and I'll return to you the latest version. Updates to Z-Link appear at random on GEnie, AppleLink, USENET, Apple2L, and other services and BBSs. Note that I take a kindly response to those who pay for Z-Link. I tend to gripe and moan when I get suggestions for improvements from people who have not yet paid. I *have* received letters which say something like "Well, Dave, I've been using Z-Link for a couple of months now, and it has a bug under these very obscure conditions." I feel that people who have used Z-Link for a couple of months are regular users and they ought to pay up. All suggestions for improvement are eventually added (if they're feasable), but suggestions given by paying customers are dealt with first, and they get first crack at the new versions. And now, a word from my legal sense: Copyright (C) 1987,1988 by David Whitney. All rights reserved. I (David Whitney) MAKE NO WARRANTY ON THIS MANUAL OR SOFTWARE, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO QUALITY, MANUAL'S ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL I BE HELD RESPONSIBLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OF THE SOFTWARE OR INACCURACY IN THE MANUAL. In other words, I have tested the program to the best of my ability, and I find that as distributed by me, it is safe for general use. It isn't necessarily bug-free, and as a result, loss of data, however unlikely, is entirely possible. Use at your own risk, but also for your own enjoyment.