%OP%JUY
%OP%PL64
%OP%TM1
%OP%BM1
%OP%LM5
%OP%HE/%H2%Z88 Users' Club Software Library
%CO:A,12,70%%C%%H2%XMODEM.DOC - documentation for Z88 XMODEM
%C%Christian Pearson (4662) -  February 1992

%JR%XMODEM is a version of part of the code contained in the Z88COM 
%JL%communications program for the Cambridge Z88 written by Phil Wheeler, 
whose copyright is acknowledged with gratitude.

%JL%     Restrictions on use are pretty simple: Download it, give it 
%JR%away, upload it to bulletin boards -- do anything but sell it.  But 
%JL%Phil Wheeler's copyright notice must be included in all copies; 
%JR%otherwise, you may remove comments, etc.  Modify code and borrow it 
%JL%if you like -- but do so at your own peril; machine code is pretty 
unforgiving!

%JR%XModem is a widely-used data transfer protocol intended to improve 
%JR%transfer reliability by checking each block of data as it is 
%JL%received.  This version has been made for users who need only to send 
%JR%data via cable link, without the modem facilities offered by the full 
Z88COM.  It uses the %H2%Checksum%H2% version of the protocol, but not %H2%CRC%H2%.

%JR%%H2%XMODEM%H2% is written in a combination of BASIC and machine-code, and 
%JR%provides upload and download of any Z88 (binary or ASCII) file, using 
a simple 3-wire lead, and avoiding problems with "hand-shaking".

%H2%Pre-requisites
%JR%A simple RS232C three-wire lead is required to link the two 
%JL%computers; see the User Manual pp.231-2.  An X-modem program is also 
%JL%needed for the other machine.  For PCs there are several shareware 
%JR%and public domain comms programs available, which include X-modem 
%JL%protocol. An example is %H2%CP%H2% which is shareware ($10 to register).  For 
two Z88s, install XMODEM in each machine.

%H2%Operation
%JL%First of all, go to the Panel ([]S) and configure the serial port 
%JR%parameters (the right-hand column) to match those of the other 
%JL%computer.  Any parameters will be suitable, but the fastest transfer 
%JR%will probably be 9600/9600 baud, 8 bits and no parity.  X-on/X-off 
should be set to NO.

Next, LOAD & RUN (or CHAIN) XMODEM.  There are 2 steps involved:
%JL%     (a) Make sure that XMODEM is in the current directory (or prefix 
the file name with %H2%:*//%H2%).
     (b) Go to BASIC ([]B) and type %H2%CHAIN "Z202B"%H2%.

%JR%The first thing you should see on your screen is "Loading... ".  This 
%JL%is needed only once, so long as you do nothing to exit the program; 
%JR%(if you do exit, just RUN again).  This will be followed in about 7 
seconds by a three-line MENU.

%JL%You can now type %H2%R%H2% or %H2%S%H2%, when the screen will prompt for the 
%JR%file-name.  Don't forget to give the %H2%full%H2% (:RAM.N/DIR/filename.ext) 
%JR%name. Before pressing <ENTER> on the Z88, prepare the other computer 
as the communications program in use requires, and connect the cable. 

%P0%
%JR%Press <ENTER> on the receiving computer first, then on the sending 
%JL%machine.  XMODEM indicates the number of blocks (of 1K bytes) to be 
%JL%sent, in %H2%Send%H2% mode, and also transmission or reception of each block 
as transfer proceeds.  The menu returns after transfer is complete.




%H2%Notes

%JL% 1.  Should the program fail to run, %H2%always wait%H2% until the message 
%JR%"Timed out.  Press any key to continue" is displayed (about 20 
%JL%seconds).  Do %H2%not%H2% press [ESC].  If you escape from the program with a 
%JL%file open, there is no way to erase or otherwise use that file 
%JR%without a Soft Reset; in that case all existing suspended activities 
%JL%will be killed, and the computer default values reset.  The program 
%JR%itself can be left as a suspended activity; the %H2%Exit%H2% command frees 
%JL%the Basic workspace for another program to be loaded.  If XMODEM 
%JR%detects a fatal error, it will give a warning and then kill itself.  
The program then needs to be LOADED and RUN again.

%JR% 2.  There is no warning given if there is insufficient space in the 
%JR%RAM device or directory to take the incoming data (or if the 
%JL%directory specified does not exist).  The program will seem to run, 
%JR%but data will not be received.  This can be very annoying when trying 
%JL%to transfer a lengthy file.  The solution is to make sure that there 
%JR%is ample space before beginning the transfer (and remember to allow 
for :RAM.-).

%JL% 3.   Pipedream files are transferred in sequential format, and with 
%JR%constructs (the information between %PC% signs) as described in the User 
%JL%Manual, pp. 240-2.  In this format, the columns of multi-column 
%JL%documents follow one another, which can be confusing if the document 
%JR%is to be edited using a different word-processor.  In this case, it 
%JL%will be an advantage to make a plain text version of the file (load, 
%JR%then save %H2%to a different file-name%H2% with the %H2%Save plain text%H2% option 
%JL%set to "Yes").  This will give text which virtually any other 
%JR%word-processor can handle, though the display on screen as the file 
%JL%is transferred may be peculiar, for Pipedream uses carriage returns, 
but not line-feeds.

%JL% 4.  Because the data are transferred in blocks of 1Kb, the last 
%JR%block will have extra characters (resembling highlighted 3) added to 
%JL%make up any shortfall.  These may need to be deleted from the end of 
the file after transfer.
%CO:B,12,60%%CO:C,12,48%%CO:D,12,36%%CO:E,12,24%%CO:F,12,12%