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