💾 Archived View for mirrors.apple2.org.za › archive › ground.icaen.uiowa.edu › upl1999 › Aug99 › ZLi… captured on 2023-01-29 at 11:24:28.
-=-=-=-=-=-=-
ZLink- 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.
Zlink.sdk is a bootable ProDOS disk in shrinked disk form
This file should be unshrinked to 5.25" diskette using
8-bit ShrinkIt.
See Csa2 File Utilities FAQs for more about ShrinkIt.
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 <RETURN> to select the item the bar is on. Press
<ESC> 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 <RETURN> to
select the file or command that is currently highlighted. Press <ESC> 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 <RETURN>. Press <ESC> 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 <ESC> 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 <RETURN> to
store the new position or <ESC> 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 <ESC> 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 <ESC> to stop the
transfer. Within a batch transfer, if things are aborted either by too many
errors or by you hitting <ESC> 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 <ESC>. 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 <RETURN>. Once entered, Z-Link cuts
off keyboard input until the string (not including the <RETURN>) 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<CR>
<OA-A>CONNECT<CR>
<CR> <CR> <OA-A>Login:<CR> Username<CR>
<OA-A>Password:<CR> secretword<CR>
If Z-Link appears stuck because the await string has not arrived from the modem
then you can press <ESC> 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<CR>
<OA-A>CONNECT<CR>
<OA-P><OA-P><CR>
.
.
.
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 <ESC> 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 <ESC> to abort. Press <RETURN> 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 <ESC>. 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-<ESC> (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 <RETURN> 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 <RETURN> 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 -> <ESC>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.