Link V0.97 - the EazyLink command-line client
=============================================

Link is a command-line client to be used for the Z88's EazyLink Server 
popdown, available from Rakewell. The main bulk of the programming has 
been done by Gunther Strube of Interlogic. Additional work for porting
it to LINUX (or UNIX) has been implemented by Garry Lancaster.

Link is a FREEWARE program. However, the EazyLink Server popdown is
not free. It is written by Interlogic and can be purchased from Rakewell.

Three versions of Link are currently available, running on DOS (for PC
compatible machines), QDOS/SMSQ (for Sinclair QL and compatibles) and UNIX.
Unless otherwise stated, all features are available on all platforms.

If you wish to port Link to another system, please contact 

	Garry Lancaster (via Z88 Forever!)
or	Gunther Strube <gbs@image.dk>

Link is an original part of the PD version of the Z80 Assembler
Workbench package for the Z88. Therefore, any improvements on Link is
appreciated to be fed back to the developers.

This documentation describes the command line interface and various
other aspects of usage.

Please refer to the "Eazylink.pdd" PipeDream document which describes
the EazyLink Server, translation tables and communication protocol.

This EazyLink Client uses only the extended protocol, not the PC LINK II
protocol. However, the standard PC LINK II client will happily use
the EazyLink Server popdown, since that protocol has been implemented
as well.


Basics
------
Before attempting to use the software, make sure that the EazyLink popdown
is running on your Z88, and that the correct cable is connected from the Z88
to your computer's serial port. By default, Link uses the following device:

        DOS:    COM1:
        QDOS:   ser2hd
        UNIX:   /dev/z88link

If you need to use a different communications port, you should set the
environment variable EAZYLINK_COMPORT to the correct device.

eg:     DOS:    SET EAZYLINK_COMPORT=2          	(use COM2:)
        QDOS:   SET EAZYLINK_COMPORT=ser2hd		(use "ser2hd")
        UNIX:   export EAZYLINK_COMPORT=/dev/cua2	(use /dev/cua2)

NB: If you use UNIX, it is better to simply re-create the symbolic link
/dev/z88link to point to the correct device).

On QDOS, you need to install the env_bin extension file as supplied by the
C68 compilation system to allow for environment variables on QDOS.


Using the client
----------------
Link is a "command-line" client which accepts switches and commands typed
on the same line as the "link" command; after finishing the last command,
it returns to the operating system prompt.

If you start the program with no commands or switches, then some version
information is displayed. Then, after pressing ENTER, Link will attempt to
communicate with the Z88 and report whether or not it received a response.

eg:	link		Attempt to communicate with Z88


Setting server translation options
----------------------------------
Three commands are available to change the translation options provided by
EazyLink Server (these can also be selected when in EazyLink on the Z88).
Please see EazyLink server documentation for further details.

t=<n> - Set auto-translation on (n=1) or off (n=0)

	eg:	link t=1	Set auto-translation on

c=<n> - Set CR/LF translations on (n=1) or off (n=0) (only of use in DOS
	version)

	eg:	link c=1	Set CR/LF translations on

z - Update (reload) translation table file "translate.dat" into EazyLink Server

	eg:	link z


Displaying Z88 information
--------------------------
Several commands are available which give information about the attached
Z88 RAM filing system and other resources. These are as follows:

h - Display a list of the file devices on the Z88

	eg:	link h			Display all file devices

d<z88wildcard> - Display a list of directories matching the wildcard given

	eg:	link d:ram.*//*		Display all directories

n<z88wildcard> - Display a list of files matching the wildcard given

	eg:	link n:ram.0//*.pdd	Display all .pdd files in :RAM.0

f<z88filespec> - Display YES if a file matching the name given is found

	eg:	link f:ram.0/Zetriz.dat	Display YES if :ram.0/Zetriz.dat exists
		link f:ram.1//*		Display YES if any files in :RAM.1

u<z88filespec>
	Display file creation & update timestamps (if a wildcard
	is given, the dates are for the first matching file found)

	eg:	link u:ram.-/link.txt	Display dates for :ram.-/link.txt

x<z88filespec> - Display size of file.

	eg:	link x:ram.1/docs/manual.pdd
					Display size of :ram.1/docs/manual.pdd

v - Display EazyLink Server main program version and file level protocol.

	eg: 	link v			Displays "5.0-05" (or larger)

g - Display default RAM device and directory (Panel settings).

	eg: 	link g

m - Display free memory as subtotal from all RAM cards

	eg:	link m

M<RamDevice> - Display free memory in specified RAM device
			Options are:
			"0" = :RAM.0, "1" = :RAM.1, "2" = :RAM.2
			"3" = :RAM.3, "-" = :RAM.-

	eg:	link M1			Displays free memory in :RAM.1

i - Display Z88 System Clock Date/Time.

	eg:	link i

q - Quit EazyLink Server popdown

	eg:	link q


Setting Z88 information
-----------------------

U - Set Create & Update Date Stamp of specified file (or directory) on Z88.
    Date stamp format is "dd/mm/yyyy hh:mm:ss"
    Please note that it is important to enclose each date/time
    argument in double quotes since date and time segments are separated
    by a space, otherwise the command line parser of the operating system
    will generate the wrong number of arguments.

    eg: link U:ram.1/file "01/01/1998 12:59:59" "07/06/1998 23:59:59"

e - Delete Z88 file or directory. The file will not be deleted if in
    use by the system. Equally, you cannot delete a directory that
    contains files (errors will be reported by the EazyLink Client).

    eg: link e:ram.1/file.dat 	{a file}
        link e:ram.1/subdir		{a directory}

w - Rename file or directory. The file will not be renamed if in use.
    You can always rename directories. Both types convey to 12+3 standard.

    eg: link w:ram.1/manual.pdd tmp {rename manual.pdd to tmp}

y - Create directory in RAM filing system. Automatic recursive path creation.
    In other words, specifying a directory path of several segments will 
    automatically be created. You therefore do not need to start with
    creating the root directory, followed by each segment:
    eg: link y:ram.1/subdir1/subdir2/subdir3

p - Set Z88 System Clock. Date format is "dd/mm/yyyy", Time format is "hh:mm:ss".
    Date and time argument are separated by space.

    eg: link p 30/06/1998 23:59:59


Sending files to the Z88
------------------------
When sending files from the host computer to the Z88, two switches are
available:

	-r	Recurse host subdirectories (DOS only)
	-d<n>	Use default Z88 device :RAM.n if no Z88 path is
		specified (otherwise :RAM.1 is used)

Multiple host files can be specified when sending, either by using
wildcards or by giving a list of files (or a mixture of these two
methods).

s=<z88file> <hostfile> - Send single host file to Z88 as <z88file>
	eg:	link s=:ram.-/test.txt old.txt
	Send the file "old.txt" to the Z88, storing as ":ram.-/test.txt"

s=<z88path> <hostfiles...> - Send multiple host files to Z88 path
	eg:	link s=:ram.1/data/ diary.dat current.pdd
	Send "diary.dat" and "current.pdd" to ":ram.1/data/" directory
		link -r s=:ram.1/ z88files\*.*
	Send files in "z88files" & subdirectories to ":ram.1/"

s <hostfiles...> - Send multiple host files to Z88, converting paths
	eg:	link -d2 -r s z88files\*.*
	Send files in "z88files" & subdirectories to :RAM.2, retaining
	subdirectory structure


Receiving files from the Z88
----------------------------
Two commands are available for receiving files from the Z88: the receive
command (r) and the backup command (b). These are identical, except that
the backup command only sends files from the Z88 which have equal creation
& update datestamps, modifying the update datestamp to the current date &
time for every file which is transferred. This means that subsequent
backup commands only transfer new or updated files, whereas receive
commands always transfer all files specified.
In the following examples, the receive (r) command is always given; the
backup command is identical in each case (replace "r" with "b").

r<z88wildcard> - Receive Z88 files and display to standard output

	eg:	link r:ram.0/config.dat
	Display the contents of the file ":ram.0/config.dat"

r<z88wildcard>=. - Receive Z88 files to current directory

	eg:	link r:ram.1//*=.
	Receive all files in :RAM.1 to current directory

r<z88wildcard>=<hostpath> - Receive Z88 files to host path, 
	preserving Z88 directory structure

	eg:	link r:ram.1//*=z88backup/
	Receive all files & directories in :RAM.1 to "z88backup" directory
	creating subdirectories as necessary


Notes on filename conversions
-----------------------------
As all systems use differing filename conventions, the following
guidelines are followed when transferring files:

Z88 to DOS:	
	Filenames are truncated to 8.3 format
	Directory separators "/" are converted to "\"

DOS to Z88:	
	Filenames are transferred unchanged

Z88 to QDOS:	
	Extension separators "." are converted to "_"
	Directory separators "/" are converted to "_"

QDOS to Z88:	
	Separators "_" are converted to "/" for directory
	structures and "." final extension if 3 or less chars

Z88 to UNIX:	
	Filenames are transferred unchanged

UNIX to Z88:	
	Filenames are truncated to 12.3 format (further extensions
	are dropped)


Future enhancements
-------------------
Link is a work-in-progress. If you have any suggestions for 
improvements, bugs to report or would like to be kept up to date 
on new releases, please contact :

	Garry Lancaster (via Z88 Forever!)
or	Gunther Strube <gbs@image.dk>

The latest version of the software can always be found on the
"Z88 Forever!" website.


Source files
------------
The Zip file is contains directory specifiers which separate
platform compile files. You will see the following structure:

.		The root contains the "link.c" and "link.h" files
		and this documentation file.
		These are the common source files for all platforms.
		Inside "link.h" you will see the appropriate #define
		for each platform. Please modify this before
		recompiling.

/DOS/	This contains additional source files for the MSDOS
		platform, and the executable.
		All is kept in a single ZIP file in this directory.
		A .PRJ file has been included for the Borland C
		DOS compiler (V3.x or later).

/LINUX/	This contains additional source files for the UNIX
                platform, and addtional documentation.
		All is kept in a single ZIP file in this directory.
		No executable is provided - you should build one to suit
		your system using the supplied Makefile.

/QDOS/	This contains additional source files for the QDOS
		SMSQ(/E) platform, and the executable.
		All is kept in a single ZIP file in this directory.
		Source files are compiled by C68 using supplied 
		makefile.

When you need to compile, copy the "link.c" and "link.h" to
the rest of the source files of your particular platform and
recompile from there.
