ZLink.dsk- Bootable ProDOS disk with ZLink sharewar telecom program ZLink.dsk is a bootable ProDOS 5.25" .dsk disk image This file may be used on an Apple II emulator or converted back to diskette form via a PC-->Apple2 ADT transfer (or, the file may be converted to diskette on a 128k Apple II via DSK2FILE or, on a IIgs, via ASIMOV). See Csa2 File Utilities FAQs. Contents ProDOS v1.9 and BASIC.SYSTEM (128k) Startup Program Selector ZLink (128k and Super Serial Card or software compatible serial port) ____________________ Z-Link Telecommunications for the Apple // by David Whitney DISCLAIMER Copyright (C) 1986,1987,1988,1989,1990 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. Apple, Super Serial Card, Finder, Apple // DeskTop, ProDOS, Apple //, Apple //e, Apple //c, Apple //c+, Apple //GS and Macintosh are trademarks of Apple Computer, Inc. ASCII Express: The Professional and MouseTalk are trademarks of United Software Industries. DataLink is a trademark of Applied Engineering. Contents INTRODUCTION 1 Shareware Notice 1 Virus Alert 3 REQUIRED EQUIPMENT 4 STARTING UP Z-LINK 5 CHOOSING FROM A MENU 6 CHOOSING FILES IN THE STANDARD FILE DIALOG MENU 6 CUSTOMIZING THE TERMINAL 9 Cursor Flashing Speed 9 Serial Port Settings 9 Default Pathnames 10 Toggles 12 The Title Screen 12 Terminal Emulation 13 Control Show 14 Capture Buffer 14 Local Echo 14 Auto Linefeed 15 Chat Mode 15 Saving and Loading Terminal Settings 17 MISCELLANEOUS COMMANDS 18 File Transfer 18 AWAIT Strings 24 BREAK Signal 25 Resetting The Terminal to a Normal State 25 Show The 25th Line 25 Hang up 26 Pause 27 Save The Capture Buffer 27 View The Capture Buffer (or any other text file) 27 Clear The Capture Buffer 28 Help 29 Quitting 29 Disk Maintainence 29 MISCELLANEOUS FEATURES 30 MACROS AND THE MACRO EDITOR 31 UPDATING OLDER SETTINGS FILES 35 DOWNLOAD ERRORS 35 INTRODUCTION 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 including a text capture buffer, robust terminal emulation, and split-screen person to person chat mode. Z-Link can transmit and receive files using several protocols including XMODEM/Checksum, XMODEM/CRC-16, YMODEM/CRC-16, and YMODEM/Batch and it is compatable with Ascii Express: The Professional and MouseTalk. The program runs on an Apple //c, //c+, enhanced //e, or //GS under ProDOS 8. Shareware Notice Z-Link is shareware. Try it out for a few weeks. If you don't like it, delete it. Otherwise, you must send me $25. The program is by no means complete. I am always improving and debugging it. 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: Internet: dcw@goldilocks.lcs.mit.edu CompuServe: >internet:dcw@goldilocks.lcs.mit.edu AppleLink: dcw@goldilocks.lcs.mit.edu@DASNET# or Dave Whitney 141 Rhinecliff Street Arlington, MA 02174 Those who send me the shareware fee should also send me some e-mail plainly stating such. 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 self addressed stamped disk mailer with a disk in it (5.25" or 3.5") and I'll return to you the latest version. Please realize that I am busily working on bugs and improvements 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. Updates to Z-Link also appear at random on GEnie, America Online, USENET, Apple2L, and other services and bulletin boards. Note that I take a kindly response to those who pay for Z-Link. Non-paying customers who send suggestions for improvement are at first ignored and only later even considered. I have received letters which effectively state that the user hasn't paid, but is using the program on a regular basis and has now found a desire for extra features. 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. Bug reports should include: what machine you are using, what version of ProDOS you used, what version of Z-Link you're running (the creation date appears at the top of the screen when you first enter the terminal) and finally, what serial interface you're using (i.e., internal port). Virus Alert In June of 1988 Z-Link was maliciously infected by a virus. If you are unfamiliar with the nature of a computer virus, suffice it to say that they work very much like a virus in a person: the virus spreads from unit to unit rather quickly and after a certain amount of time, damage is done. The infected Z-Link is travelling under the name "Z-Link Plus". DO NOT USE IT. The virus hidden in Z-Link Plus is either CyberAIDS or Festering Hate (there's debate on which one it really is). It spread far and wide very fast and did tremendous damage. Detectors for these viri have also spread very fast. Check out your local bulletin board system or user group for information. 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. 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 (as did happen in 1988), 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. On the other hand, if the virus detector goes off then you can safely assume that you're infected. Cold boot a known clean disk and back everything up (I mean really cold boot it - shut off the power). Then panic. REQUIRED EQUIPMENT Z-Link works on an Apple //c, //c+, //GS, or an enhanced //e with a 128k 80 column board in slot 3 and a Super Serial Card (or hardware 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 up how to do it in your manual. If your card can't generate interrupts, then Z-Link won't work. 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 is capable of generating interrupts. (I really don't know which internal modems are capable of what and how compatible they 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, all is ok. If you are using an Apple //GS then be sure that the control panel is set properly. 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 also 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. 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. If you use the internal port on a //GS then the maximum baud rate you can effectively use is 19,200. If you are using an internal modem or some other serial interface on a //GS, or you are not even using a //GS then the maximum baud rate you can use is 2400. This is because of the way the signals are processed. Z-Link gets notification of a character received a long time after the character actually arrives. If characters come in too fast, then several will be lost. This will disrupt any and every aspect of Z-Link and make it useless. STARTING UP Z-LINK The program is a SYS file which can be launched in a variety of ways. While running the Apple // DeskTop or Finder, double-click on the Z-Link icon; type "-Z.LINK.SYSTEM" from BASIC; or when you quit another application, type the prefix and pathname of Z-Link. You can also make a self-booting disk by putting ProDOS on a blank disk and the file Z.LINK.SYSTEM the second file on the disk (see your ProDOS user's manual for more details). Once loaded, the title screen will be displayed. Hit any key to go into terminal mode. The top of the screen will have the creation date of the copy you have. This date is important to me for determining where bugs are. Refer to this date if you make a bug report. 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 bar is on. Press to abort out of any menu and return to the terminal. Some menus allow you to press other keys in addition to the arrow keys. For example, the upload protocols selection menu allows you 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. 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 Apple //GS 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 having "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, 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 six 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. 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) 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 the name you've typed and proceed with the operation. To stop entering a name, hit either up or down arrow. Once you do, the name you've typed will be cleared out. CUSTOMIZING THE TERMINAL Various parts of the terminal can be customized to your liking, or elements can be turned on or off as required by a particular application. Cursor Flashing Speed Unlike some other packages, Z-Link has a blinking cursor which helps you quickly locate its position on the screen. You can adjust how fast it blinks, or even have it not blink at all by pressing Open Apple Right Arrow to speed it up or Open Apple Left Arrow to slow it down. One of the speeds is "frozen," or no blinking at all. Serial Port Settings You can press Open Apple "W" to change any of the communication parameters, including baud rate, data word size, number of stop bits, parity, and the serial card slot. 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 . Press to abort any changes. Do not make any changes while you are online - the connection will be broken. Note that you can change where Z-Link should expect to find a serial card. Your choices here represent 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. Apple //GS users: You must have the control panel set appropriately for slot selection to work properly. 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 improperly then Z-Link won't identify your card. 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. You must 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 quit. 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 with "/RAM/BUFFER" as the capture buffer path and "/" as both the upload and download directories. You can change any of these by pressing Open Apple "N". The capture buffer path is the file to be used as the capture buffer itself. It is not the default name under which to save the buffer at a later time. For this reason, you do not want to define this path on any physical disk - it will operate too slowly and data will be lost. 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. Refer to your Apple //GS Owner's Guide for details on changing the size of the RAMdisk. Upload and download directories are especially useful for hard disk owners. It makes you 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 files 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, use the DELETE key to rubout and the CLEAR key or Control-X to clear out the entry. Press CLEAR on an empty line to restore the entry to its previous setting. Press TAB to move to the next field. Note that only Apple //GS users have a CLEAR key. 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. Toggles Z-Link has several different state settings that you can easily change. These mostly affect how the output will appear on your screen. All but one of these are toggles, so pressing the key twice has no net effect. The Title Screen As 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 pressing Open Apple "0" once. Then save the current settings (see the section, "Saving and Loading 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. Terminal Emulation Z-Link comes with a terminal emulator that can simulate Heath h19 (otherwise known as VT52) and VT100 (or ANSI) terminals. You can use h19 terminal emulation by pressing Open Apple "T" once. You can use vt100 emulation by pressing OA-T once again. Press OA-T once more to turn emulation off. Be sure that the host end of the connection knows what sort of terminal Z-Link is emulating. Note that DEC computers use a slightly different way of presenting the emulation codes than Z-Link can handle so you should use tell DEC computers that Z-Link is an ANSI terminal - not a vt100 terminal. Z-Link is not directly capable of keyboard emulation. Instead, one can write up a set of macros which will send the correct codes when any particular key is pressed. The file VT200.CONFIG contains a set of macros which simulate a vt220 keyboard. To use these macros, load VT220.CONFIG (see the section, "Loading and Saving Terminal Settings Files" for details). The vt100 emulation is 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. Control Show This is useful for debugging purposes. If the other end is sending codes to your Apple and it's causing strange things to happen, press Open Apple "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 carriage return line feed (CRLF) will be viewed as "^M^J". The control codes will have no effect. As a result, terminal emulation is disabled while control-show is on. Capture Buffer Upon startup, Z-Link opens a file on the /RAM disk called BUFFER. You can turn capturing on by pressing Open Apple "C". 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). An auto-save feature is forthcoming. You can change the name Z-Link uses as the buffer file. See the section, "Default Pathnames" for details. Local Echo If you never see what you're typing, press Open Apple "E" and all will be well again. Local echo "on" routes all typed characters to the screen. Those characters will be sent to the capture buffer if it is enabled. Note 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. Auto Linefeed If what you see is appearing on one line only then you need to have Z-Link add in the line-feeds the other end isn't sending. This usually comes up when talking direct with another person. Press Open Apple "L" to engage auto linefeeding. 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. Chat Mode Chat mode is a split-screen chatting environment which is most useful when being used between two users of Z-Link. Turn chat mode on by pressing Open Apple "K". 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. Saving and Loading Terminal Settings Once you have the terminal configured to your liking, you can save all the settings by pressing Open-Apple "S". A menu will appear with the choices "Load Settings" and "Save Settings." Z-link will then ask for a filename. The contents 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. By saving the settings with the name Z.LINK.CONFIG, you make them the default for the next time you run Z-Link. You can save the settings under any name you like, but only the file Z.LINK.CONFIG will be loaded just as Z-Link starts. You can also override the name Z-Link uses as the default name for the settings file if you use a program launcher such as Davex or ECP. Just launch Z-Link with the alternate settings file name as the first parameter. For example, if the name of the settings file is SAMPLE.CONF, you'd type "Z.LINK.SYSTEM SAMPLE.CONF" and Z-Link will load the file SAMPLE.CONF instead of the file Z.LINK.CONFIG. MISCELLANEOUS COMMANDS In addition to the customization commands, there are a number of commands that cause some action to be carried out. These are the commands that make Z-Link most useful. File Transfer 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 to return to terminal mode. Option 1 is the standard Xmodem transfer mode. Just about every modem program 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 want to talk. Option 3 YMODEM is similar to XMODEM/CRC except that it uses 1k data packets. This reduces the overhead when sending huge files. Regular Xmodem has a 3.75% overhead while Ymodem has a 0.48% overhead. Unlike some packages which 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 starts up his end without typing 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 and you'll see the contents of the default upload directory. See the section, "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 file while Y indicates the total number of errors while sending the current packet. 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 decide you don't want to send a file, you can hit to stop the transfer. 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. Open Apple Down Arrow - Download a file (Receive) This is very much like the Upload command, except that you can't receive an ASCII file (you use the Capture Buffer). Select a protocol and enter the filename as before. The contents of the default download directory appear in the window. If you are using YMODEM/Batch to receive files, 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 then 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 file while Y indicates the total number of errors while sending the current packet. If more than ten errors occur on the current data packet then the transfer will be aborted. To cancel the file currently being sent, press . 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 as it nears the end of the file, this won't occur if the sending program is Z-Link. There are a few other programs which 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 mean. AWAIT Strings An await string is used primarily from within a macro. No dialog window is drawn to save execution time. Press Open Apple "A" to start entering the string. When OA-A is 'typed' by the macro, Z-Link waits for a string (up to 32 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 Z-Link appears stuck because the await string has not arrived from the modem then you can press and have Z-Link return to normal mode. Note that this does not break out of the macro - it only re-engages the keyboard. 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.) Press Open Apple "B" to send a BREAK signal. Resetting The Terminal to a Normal State This is useful in the event of a sudden burst of noise on the phone. When the terminal emulation is turned on, there is a 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, press Open Apple "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). Show The 25th Line Several applications make use of a status line which is normally addressed as the 25th line. In order to see what is currently on the 25th line, press Open Apple "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 screen control for the 25th line, every time a character is printed there the line will briefly flash on the bottom of the screen. Hang Up 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 Open Apple "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 improperly, 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. Pause This option is used primarily from within macros. If you press Open Apple "P", the computer freezes for about 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 . . . Save The Capture Buffer You can use this feature to save the contents of the capture buffer to your disk. After saving, the capture buffer is cleared. When you press Open Apple "D", the standard file dialog will appear with the contents of the default download directory. See the section, "Choosing Files in the Standard File Dialog Menu" for details on moving around the directory structure. View The Capture Buffer (or any other text file) Press Open Apple "Z" to view any text file. When the file dialog appears, it 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 press OA-Z. This presumes that you want to view several files in the same directory. While viewing a file, you can press any key to pause the output. Press any key to continue. 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 wait for you to press a key before going 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, viewing the buffer (or the file you have saved the buffer into) will execute the same emulation sequences. You may have to play with the Auto Linefeed setting to get files to print on more than one line. Clear The Capture Buffer You can clear out the capture buffer by pressing Open Apple "Y". Saving the buffer also clears it. Help Press Open Apple "?" and the help screen will pop up. It will show you the list of commands and the current settings of all the toggle parameters. 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...) Quitting When you are all done using Z-Link, press Open Apple "X". A menu pops up with three choices. 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. Disk Maintainence This command provides you with some basic disk manipulation. Press Open Apple "F" to bring up a menu of three choices: "Delete a File," "Rename a File," and "Create a Subdirectory." Enter or select a 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 filename itself. 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. MISCELLANEOUS FEATURES 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. MACROS AND THE MACRO EDITOR A macro is a system by which a single keystroke takes the place of many keystrokes. You can have the single keystroke Closed Apple cause Z-Link to dial your local bulletin board, login, capture all your mail and then logout. Macros make tedious key sequences easy to handle. In Z-Link, any key you can type can be entered in a macro. This includes invocations of other macros. With a little thought, you can make a very powerful macro. The macro editor was written and graciously donated by David Lyons (of DAVEX fame) and it allows you to 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 your settings 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 of them, and the space alotted for them is roughly 2k. You must run Z-Link and save a terminal settings file before running the editor. Once you run the editor, 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, 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 into Z-Link 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 (^H) 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 starts up the macro defined by the delete key and a backspace is ultimately sent. 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 desired. 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 settings 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 settings 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 settings file and the new file to put the macros in. It will copy all the macro entries out of the old settings file into the new one and then save the update. At this point, you may delete the old settings file. Note that this utility won't move over any other parameters you may have set. Go into Z-Link and load your new settings 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 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. If Z-Link 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 occurs when there was a burst of noise and some data was corrupted. It is entirely possible that the data packet was valid, but the CRC/Checksum was 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.