
___________________

ZeriLink user guide
___________________


User, please note
=================

ZeriLink is Freeware, i.e. it is free software, but not public domain.

Copyright notice
================

The copyrights (c) of this program belong to John Kortink. All rights are
reserved.

You may not make changes to this program (except for documented configuration
changes). If you distribute it, you may only distribute the complete and
unchanged original copy (as you first received it). You may distribute this
program freely, but must obtain written permission from me if it is to be
distributed as part of, or alongside, any product that is meant to generate
profits. This program is provided 'as is'. Fitness of this program for any
particular purpose is not implied. Using it is entirely at your own risk.


//
//
// Introduction
//
//

ZeriLink gives your Acorn or IBM compatible machine the ability to transfer
files to/from another Acorn or IBM compatible machine, at up to 800kB/sec.
ZeriLink's only requirement is that both machines have a parallel port that
supports either 'ECP' or 'PS/2' mode. And you need to make (or buy) a cable.

Most 'recent' Acorn and IBM compatible machines can successfully run ZeriLink.
This includes, among others, the A5000, A4, A7000, Risc PC, and all except very
old IBM compatible machines. ZeriLink has been around for many years, and has
extensively proved itself 'in the field'. By now it serves many users, running
on a wide variety of hardware combinations, providing a robust, fast and cheap
way to transfer files between machines.

Note that several ZeriLink 'frontends' have been written, e.g. by Jochen Lueg
and Howard Dawson, to complement the fairly basic command-line features offered
by ZeriLink. Please refer to an Internet search engine to find their efforts.

In the following, to simplify the text, IBM compatible machines will mostly be
referred to as 'IBM' and Acorn machines as 'Acorn'.


//
//
// Hardware requirements
//
//

Acorn
-----
- A parallel port with ECP or PS/2 support.

IBM
---
- A parallel port with ECP or PS/2 support.
- An Intel 80386 or compatible processor.
- An environment with DPMI support and allowing direct hardware access. The
  latter unfortunately rules out Windows NT derivatives, including Windows XP,
  but OSses like Windows 95 and 98 work fine and have DPMI support built in.
  Under DOS you usually need to run a DOS extender, like CWSDPMI.EXE (which is
  freely available, please refer to an Internet search engine to find a copy).

Additional
----------
- A parallel cable wired to specifications. See below.

Note that ready made ZeriLink cables can be purchased from C.J.E. Micro's in
the U.K. (look up http://www.cjemicros.co.uk).


//
//
// Using ZeriLink
//
//

On an Acorn, the ZeriLink module and its configuration file 'LinkConfig' should
be installed, ideally in the machine's !Boot sequence (if you have one). The
ZeriLink module provides the LinkT, LinkR, LinkConfigure and LinkDiagnostics
*-commands. Acorn installation and use is discussed below.

On an IBM, a configuration file called 'Link.CNF' and two executable files,
'LinkT.EXE' and 'LinkR.EXE', should be installed in one of the directories
pointed to by the OS system variable PATH. IBM compatible installation and use
is discussed below.

It is important to note that the ZeriLink software can provide a link between
any one of three pairs of machine types (Acorn to IBM, Acorn to Acorn, or IBM
to IBM). The 'receiver' software on a machine is capable of interpreting both
'native' files (which will be left untranslated) and 'foreign' files (which
will be suitably translated to 'native' format). The 'transmitter' software
simply sends its 'native' format only.

The cable which connects both sides' parallel port consists of two 'male 25 pin
D type' plugs, connected by a multi-wire *SHIELDED* cable. The cable should be
(re-)wired as follows (pin numbers are marked on the D type plugs, consult your
manuals if in doubt) :

  One side          <--->  Other side

  Pin 1 (nSTROBE)   <--->  Pin 10 (nACK)
  Pin 2 (DATA 0)    <--->  Pin 2 (DATA 0)
  Pin 3 (DATA 1)    <--->  Pin 3 (DATA 1)
  Pin 4 (DATA 2)    <--->  Pin 4 (DATA 2)
  Pin 5 (DATA 3)    <--->  Pin 5 (DATA 3)
  Pin 6 (DATA 4)    <--->  Pin 6 (DATA 4)
  Pin 7 (DATA 5)    <--->  Pin 7 (DATA 5)
  Pin 8 (DATA 6)    <--->  Pin 8 (DATA 6)
  Pin 9 (DATA 7)    <--->  Pin 9 (DATA 7)
  Pin 10 (nACK)     <--->  Pin 1 (nSTROBE)
  Pin 11 (BUSY)     <--->  Pin 14 (nAUTOFD)
  Pin 12 (PE)       <--->  Pin 16 (nINIT)
  Pin 13 (SLCT)     <--->  Pin 17 (nSLCTIN)
  Pin 14 (nAUTOFD)  <--->  Pin 11 (BUSY)
  Pin 16 (nINIT)    <--->  Pin 12 (PE)
  Pin 17 (nSLCTIN)  <--->  Pin 13 (SLCT)
* Pin 18 (0V)       <--->  Pin 18 (0V)
* Pin 19 (0V)       <--->  Pin 19 (0V)
* Pin 20 (0V)       <--->  Pin 20 (0V)
* Pin 21 (0V)       <--->  Pin 21 (0V)
* Pin 22 (0V)       <--->  Pin 22 (0V)
* Pin 23 (0V)       <--->  Pin 23 (0V)
* Pin 24 (0V)       <--->  Pin 24 (0V)
  Pin 25 (0V)       <--->  Pin 25 (0V)

In addition, on each connector seperately, pin 13 (SLCT) should be connected to
pin 15 (nERROR) by a short piece of wire.

Connections marked with a * are not required, but they are recommended. In
addition to these connections, the shielding wire should be soldered to the
plug's metal on both sides (i.e. to the plug itself, not one of its pins).

It is recommended to buy a prefabricated completely wired 'straight' parallel
extension cable (i.e. pin 1 to pin 1, pin 2 to pin 2, ..., pin 25 to pin 25),
which should be widely available in a variety of lengths, and re-wire that to
the specifications above. This saves a lot of soldering. Ensure that both sides
of the prefabricated cable have 'male' plugs (i.e. plugs with pins, not holes),
that the cable is shielded, and that the plug caps can be opened for re-wiring
(some cables have moulded plugs which cannot be opened !).


//
//
// The software on both sides
//
//

The general ZeriLink tranfer concept is as follows :

1) The receiving side issues the 'LinkR' command. It starts waiting for a
   transmission from the other side.
2) The transmitting side issues the 'LinkT <filespec>...' command. It starts
   transmitting files, one by one.
3) The transmitted files are received, interpreted and saved.
4) The transfer is terminated (LinkR exits, LinkT exits).

The receiving side needs to issue 'LinkR' first because ZeriLink software uses
'polled I/O', to make the fastest transfer speeds possible. ZeriLink achieves
transfer speeds of up to 800 KB/sec (ECP mode) or 200 KB/sec (PS/2 mode), for
large-ish files, even when using long cables.

When a file is transmitted, all relevant information about the file is included
in the transmission and is retained (as well as possible) in the target file on
the other side. There are, however, some restrictions, which will be discussed
below. Also, file attributes are *always* ignored. This is because 'locked' or
'read only' files are usually a big pain to work with. If you really need to
preserve file attributes, then simply archive the files at one end, transmit
the archive, and unarchive the files at the other end.

The ZeriLink software can be configured in a very flexible way, by means of a
configuration file ('LinkConfig' (Acorn) and 'Link.CNF' (IBM) are examples of
generally usable configuration files). Configuration of the ZeriLink software
is discussed in detail below (which options are available depends on whether
the software runs on an Acorn or on an IBM). In general, the configuration file
simply consists of a number of lines. If a line starts with a letter, it is a
definition line (i.e. it contains configuration information), else it is a
comment line (i.e. it is ignored). A definition line starts with a keyword, and
is followed by one or more values (seperated from the keyword by spaces). Most
keywords are discussed informally below. Note that the example configuration
files include detailed and/or further explanations of all the keywords.

The keyword 'Mode' is a general keyword. It selects either ECP (value 'ECP') or
PS/2 (value 'BIDIR') mode. It is strongly recommended to first try the 'BIDIR'
setting, and, when this works, the 'ECP' setting (if appropriate). If the
'BIDIR' setting does not work, the 'ECP' setting is also very unlikely to work,
since all ECP capable parallel ports should also be PS/2 capable. Conversely,
if the 'ECP' setting works, the 'BIDIR' setting is very likely to work too.

It is very important to note that file data integrity is ensured by a CRC32
algorithm (32-bit Cyclic Redundancy Check). Both the transmitter and receiver
calculate a number (the CRC) from a file's contents, based on an algorithm
specially designed to check digital transmissions. The transmitter sends the
CRC along with the file data, and the receiver matches it against the CRC it
calculated itself. If the two don't match, the file has been corrupted during
transmission, and the receiver will delete the file. If the CRCs match, it is
extremely unlikely that the file is corrupted. Failure or success in matching
CRCs is reported explicitly by the receiver.

Note that only leafnames of files are transmitted, and directories are not
transmitted or recursed. Directory paths are always discarded. The receiver
writes all files to the 'current directory' on the receiving machine.


//
//
// The software on the Acorn side
//
//

Installation of two files is required. The 'ZLink' file is the ZeriLink module,
and should ideally be loaded (and configured) when booting. The 'LinkConfig'
file contains configuration information for the ZeriLink module, and should be
given to it using '*LinkConfigure LinkConfig'.

A typical installation would be a directory, anywhere you want, containing the
ZLink and LinkConfig files, and a !Run file, and then specifying the !Run file
to the RISC OS configuration utility (section 'Boot' then 'Run'), with the !Run
file (an Obey file) containing :

RMLoad <Obey$Dir>.ZLink
LinkConfigure <Obey$Dir>.LinkConfig

The ZeriLink module provides four *-commands : LinkR, LinkT, LinkConfigure and
LinkDiagnostics. *LinkR needs no further explanation. '*LinkT <filespec>...'
transmits all the files that match <filespec>. Wildcards may be used freely,
and multiple filespecs may be given, seperated by spaces (e.g. '*LinkT
$.A.B.C.* RAMFS:D* E*').

When receiving 'Acorn' files, translations are as follows :

- The leafname is scanned for characters that are illegal in Acorn leafnames
  (see the 'MapChar' configuration keyword). If any are found, they are
  replaced by the configured corresponding 'legal' leafname characters.
- The leafname is then truncated, if needed, to a fixed number of characters
  (see the 'LeafLength' configuration keyword).
- The file's attributes are ignored (and set to 'WRwr' instead).
- All other file information is retained.

The first two translations do not usually change the leafname, but are
performed for reasons of safety and convenience. In general, Acorn file
information is fully retained, except for file attributes.

When receiving 'DOS' files, translations are as follows :

- The leafname is scanned for a recognised extension (see the 'ExtToType'
  configuration keyword). If a match is found, the extension, including the
  leading '.', is removed from the leafname, and the Acorn filetype is set to
  the configured corresponding filetype. If no match is found, the leafname
  remains untouched and the Acorn filetype is set to a default value (see the
  'NoExtToType' configuration keyword).
- The leafname is then scanned for characters that are illegal in Acorn
  leafnames (see the 'MapChar' configuration keyword). If any are found, they
  are replaced by the configured corresponding 'legal' leafname characters.
- The leafname is then truncated, if needed, to a fixed number of characters
  (see the 'LeafLength' configuration keyword).
- The file's time stamp is translated to Acorn format, if possible.
- The file's attributes are ignored (and set to 'WRwr' instead).

The configuration file 'LinkConfig' contains example configuration settings and
its contents are mostly self-explanatory when you have read the above.


//
//
// The software on the IBM side
//
//

Installation of three files is required. The 'LinkT.EXE' and 'LinkR.EXE' files
are executable files and should be copied to one of the directories specified
in the PATH system variable on your system, so they can be readily executed.
The 'Link.CNF' configuration file should be put in the same directory. If you
are running a DOS environment that supports long filenames (e.g. an MSDOS box
under Windows 98) you may need to set the system variable 'LFN' to 'Y' (e.g.,
add the line 'set LFN=Y' to your AUTOEXEC.BAT file). Failing to do this may
result in the usual troubles with long filenames, e.g. automatic truncation to
something like 'BLAHBL~1', etc..

Rather obviously, the 'LinkT.EXE' executable provides the 'LinkT' command, and
the 'LinkR.EXE' executable provides the 'LinkR' command. Like on the Acorn,
'LinkT <filespec>...' transmits all the files that match <filespec>. Wildcards
may be used freely, and multiple filespecs may be given, seperated by spaces
(e.g. 'LinkT C:\A\B\C\*.* D:\D*.* E*.*').

When receiving 'DOS' files, translations are as follows :

- The leafname is scanned for characters that are illegal in DOS leafnames (see
  the 'MapChar' configuration keyword). If any are found, they are replaced by
  the configured corresponding 'legal' leafname characters.
- The leafname is then truncated, if needed, to a fixed number of characters
  (see the 'LeafLength' configuration keyword).
- The file's attributes are ignored (and set to 'A' instead).
- All other file information is retained.

The first two translations do not usually change the leafname, but are
performed for reasons of safety and convenience. In general, DOS file
information is fully retained, except for file attributes.

When receiving 'Acorn' files, translations are as follows :

- The leafname is scanned for characters that are illegal in DOS leafnames (see
  the 'MapChar' configuration keyword). If any are found, they are replaced by
  the configured corresponding 'legal' leafname characters.
- Then the Acorn filetype, if present, is looked up in a table (see the
  'TypeToExt' configuration keyword). If a match is found, the configured
  corresponding extension is appended to the leafname, including a leading '.'.
  If no match is found, the leafname remains untouched.
- The leafname is then truncated, if needed, to a fixed number of characters
  (see the 'LeafLength' configuration keyword).
- The file's time stamp, if present, is translated to DOS format, if possible.
- The file's attributes are ignored (and set to 'A' instead).

The configuration file 'Link.CNF' contains example configuration settings and
its contents are mostly self-explanatory when you have read the above.

The 'LinkPort' configuration keyword allows you to specify the parallel port to
be used by ZeriLink. The value needs to be the (hexadecimal) port number of the
parallel port (practically always one of 278, 378 or 3BC). Consult the BIOS
settings of your machine to find out what port number to use, and ensure that
the port mode is configured to, preferrably, ECP ('Extended Capabilities Port')
or else PS/2 ('bidirectional').


//
//
// Epilogue
//
//

Updates of ZeriLink (if any appear) will be made available by (in order of
preference) :

- World Wide Web : visit www.inter.nl.net/users/J.Kortink.
- Electronic mail : email kortink@inter.nl.net.

Enjoy !


John Kortink

