mirror of https://github.com/wwarthen/RomWBW.git
Browse Source
- Restore cursor on normal program exit. - Revert original HBIOS conout and default console code as there is no associated facility for direct HBIOS conin. - Allow setting port 0 and port 1 CIO device from command line ZMP 2 sets comms port to CIO 2. Can set primary and secondary i.e. ZMP 21 but only primary supported on this ZMP version. Untested on Ron Murrays ZMP15 - Space getting short so messages shortened.pull/234/head
b1ackmai1er
4 years ago
4 changed files with 449 additions and 34 deletions
@ -0,0 +1,389 @@ |
|||
** ZMP Documentation ** |
|||
|
|||
1. Introduction. |
|||
|
|||
ZMP is a communications/file transfer program for CP/M which |
|||
performs Xmodem, Xmodem-1k (often erroneously called Ymodem), |
|||
true Ymodem and Zmodem file transfer protocols. Although tested |
|||
with Z80DOS, ZRDOS and CP/M 2.2, there seems to be no reason why |
|||
it shouldn't work with CP/M 3 as well. The only requirements are |
|||
a Z80 processor (sorry about that!), a computer running CP/M in |
|||
one of its various guises, with at least 45k of TPA (but the more |
|||
the better!), and a modem. |
|||
When you try to pack this many features into one program, |
|||
you end up with a pretty large file. The big problem occurs when |
|||
file transfers are attempted: unless you have at least 4-8k of |
|||
buffer size, you might as well use xmodem protocol. The approach |
|||
taken in ZMP is to use overlays for various functions, accepting |
|||
the time taken to load these from disk. Thus performance will |
|||
vary depending on your disk setup: if you have a hard disk and a |
|||
fast processor you will likely not notice the difference. If, on |
|||
the other hand, you are running a Commodore 128 with CP/M on a |
|||
1571 drive, there is no physical reason why ZMP won't work, but |
|||
you might consider investing in a book to read while the overlays |
|||
load. (A suitable book to read might be a computer catalogue!). |
|||
The curious amongst you may notice that the beginning of the |
|||
ZMPX.COM file has the magic 'Z3ENV' string, but don't let this |
|||
fool you into thinking that you don't need to add terminal |
|||
characteristics into the overlay if you have a ZCPR3 system. It |
|||
has proved possible to persuade this particular C compiler to |
|||
access ZCPR3's environment descriptor, but not for ZMP. Yet. |
|||
Perhaps later. In the meantime, the startup code is there for it. |
|||
In order to produce a program which would work with most |
|||
CP/M systems, the Zmodem protocol performed by ZMP is fairly |
|||
simple. The transmit section uses 'Full Streaming with Reverse |
|||
Interrupt', as Chuck Forsberg calls it in his description of the |
|||
Zmodem protocol. The receive section uses 'Segmented Streaming'. |
|||
This means that, if your system can do serial I/O and disk I/O at |
|||
the same time, ZMP does not take advantage of the faster transfer |
|||
rate which this capability provides. Since, however, I can't |
|||
write and listen at the same time, and neither can my computer, |
|||
and neither can the vast majority of CP/M computers, it seemed |
|||
the best approach to take. Segmented Streaming means that the |
|||
receive program tells the transmit program how big its buffer is. |
|||
The transmit program then sends just that much data, then waits |
|||
for an acknowledge from the receiver. We have encountered some |
|||
Zmodem programs which send too much data in this case: errors |
|||
will appear if this happens, but the protocol should recover and |
|||
the file will be received intact (we hope!). |
|||
The string which ZMP passes to the receiving program to |
|||
interrupt in case of errors is likewise simple. Basically it |
|||
causes the receiving program to send a control-C character and |
|||
then wait for one second. The receiver will then send its ZRPOS |
|||
string, by which time ZMP, as the transmitter, should be ready to |
|||
receive it. |
|||
|
|||
|
|||
2. Customisation. |
|||
|
|||
ZMP must be customised to suit your system. This involves |
|||
overlaying the un-installed copy of ZMP.COM (contained in this |
|||
library as ZMPX.COM) with a user-written installation overlay. |
|||
Some hints on writing this are given below; there is a blank |
|||
overlay file in this library, or you may be able to obtain one |
|||
for your computer from the same place you got this library. |
|||
This value is set at 0145 hex, and should stay there permanently. |
|||
See the notes in this document, and also the ZMP-OVL.UPD file, |
|||
for more details on how to set up your overlay. |
|||
Once the installation overlay is written, assemble it with |
|||
M80 (or SLR or whatever), use RELHEX to create a .HEX file, and |
|||
use MLOAD to overlay it over the ZMPX.COM file to produce your |
|||
very own ZMP.COM. |
|||
|
|||
3. Operation. |
|||
|
|||
The following files must be on the same disk and user area, |
|||
which must be specified in your customisation overlay: |
|||
|
|||
ZMCONFIG.OVR -- the configuration overlay |
|||
ZMINIT.OVR -- the initialisation overlay |
|||
ZMTERM.OVR -- the terminal overlay |
|||
ZMXFER.OVR -- the file transfer overlay |
|||
ZMP.HLP -- the help file (recommended). |
|||
|
|||
Start the program with ZMP. The screen should clear, then a |
|||
title message is printed, then ZMP enters terminal mode. You may |
|||
type escape-H for help at this point. When you first run the |
|||
program, the first thing you need to do is to enter the |
|||
configuration overlay (type escape-C) and set all the defaults |
|||
and others to suit your system as required. If you don't know |
|||
whether to change something or not, it's probably better to leave |
|||
it alone. When you exit the configuration program, answer 'Y' to |
|||
the 'Make changes permanent' question. ZMP.FON and ZMP.CFG will |
|||
be produced on your disk, in the same drive/user area as the |
|||
above files. |
|||
|
|||
Operation of the program is controlled by escape sequences |
|||
entered in terminal mode. Escape-H gives you a list of options. |
|||
Most of these are self-explanatory, but they will be summarized |
|||
here. |
|||
|
|||
B - Send Break to modem. |
|||
If your overlay has been set up to send a break command |
|||
to your UART, this command will perform this function. (Some |
|||
remote systems may require a break sent to them to interrupt |
|||
Zmodem transfers). |
|||
|
|||
C - Configure system. |
|||
This function is designed to set system defaults, save |
|||
phone numbers etc. Changing baud rates etc. for a particular |
|||
call are better handled with the escape-L option. If you |
|||
answer Y or y to the 'make changes permanent?' question, the |
|||
new configuration will be saved in a ZMP.CFG file, and the |
|||
phone numbers in a ZMP.FON file for later use. The .CFG file |
|||
is read, if it exists, when ZMP is first started. |
|||
|
|||
D - Get disk Directory. |
|||
Gets a directory of the current drive and user area. |
|||
Change to another with the escape-F command, described |
|||
below. The directory will be sorted and will include |
|||
filesizes unless you have so many files on the current |
|||
drive/user area that there is insufficient memory available |
|||
to sort them. In this case an unsorted directory, without |
|||
file sizes, will be printed. |
|||
|
|||
F - Disk/File operations. |
|||
This command is used to change the current drive/user |
|||
area, to reset a disk in the current drive, and to view, |
|||
erase, print or rename files. There are also options to give |
|||
a directory of the current drive/user area, and to supply a |
|||
new filename for the capture file. This filename may specify |
|||
a different drive/user area than the current one. If capture |
|||
mode is on, the status line printed when terminal mode is |
|||
entered will state the capture file name. |
|||
|
|||
H - Get Help. |
|||
Prints the ZMP.HLP file. You may then either type CR to |
|||
return to terminal mode, or enter the required function key. |
|||
|
|||
I - Initiate phone call. |
|||
Reads the ZMP.FON file, if any, and prints it. You have |
|||
four seconds after typing ESC I, during which you may enter |
|||
the letter corresponding to the required number, in which |
|||
case ZMP will dial it without printing a list. Otherwise the |
|||
full phone list will be printed, and you will be asked which |
|||
number you want. Enter the identifying letter of the number |
|||
you wish to call. You can also enter numbers not in the |
|||
list. Multiple numbers can be called by entering them separ- |
|||
ated with commas. Dialling will then commence, and will |
|||
continue until one of the numbers answers, or until you |
|||
abort the process with the escape key. Note that the baud |
|||
rate used for the call is that in the .FON file for that |
|||
number, or the current one if a new number is entered. This |
|||
function works best if the strings in the .CFG file have |
|||
been set up for your modem, and the initialisation string |
|||
sent to the modem sets it into verbose mode for status |
|||
messages (ATV1). |
|||
|
|||
K - Display Keyboard macros. |
|||
The configuration option allows up to ten macro keys to |
|||
be defined, and these are recalled by typing escape followed |
|||
by the numbers 0 to 9. This function prints the current |
|||
assignments. |
|||
|
|||
L - Change Line settings. |
|||
This function allows temporary changes of baud rate, |
|||
stop bits, and data bits. There is also an option to operate |
|||
terminal mode in full duplex (locally typed characters are |
|||
sent but not displayed on the screen), half duplex (locally |
|||
typed characters are sent and also displayed on the screen), |
|||
or echo mode (as for half duplex, but received characters |
|||
are echoed to the remote system as well as being displayed). |
|||
Don't have two computers talking to each other in echo mode |
|||
unless you're bored. There are also options to allow/dis- |
|||
allow control characters above CR to be displayed in term- |
|||
inal mode, to strip the parity bit in terminal mode, and to |
|||
re-initialise the currently selected UART and modem at the |
|||
current baud rate. |
|||
Like IMP, ZMP uses location 003C hex to store a value |
|||
corresponding to the present baud rate. Then, if you leave |
|||
ZMP and later re-enter, it checks location 003C. If it |
|||
contains a legal value, then that baud rate is set for you, |
|||
otherwise it sets the default baud rate as selected in the |
|||
.CFG file. |
|||
|
|||
M - Toggle capture mode in Memory. |
|||
Received characters will be saved in a buffer and saved |
|||
in a file named 'ZMP.LOG' when the buffer fills or when the |
|||
command is entered again. A control-S/control-Q sequence is |
|||
sent to the remote computer while the buffer is being saved |
|||
in an attempt to stop it sending more data. |
|||
|
|||
P - Toggle Printer. |
|||
This is similar to the 'M' command, except incoming |
|||
characters are sent to the printer. This functions best if |
|||
your system performs the BIOS 'List Status' function |
|||
correctly. |
|||
|
|||
Q - Quit the program. |
|||
Obvious. You will be asked if this is really what you |
|||
want. Any entry other than N or n will exit to CP/M. |
|||
|
|||
R - Receive a file. |
|||
You will be asked which protocol you wish to use. The |
|||
default is ZMODEM. The <X>modem option will allow either |
|||
128-byte blocks (standard XMODEM) or 1k blocks (XMODEM-1k), |
|||
since this is decided by the transmit end. If an attempt is |
|||
made to receive a file which has the same name as a file on |
|||
the current drive/user area, the current one will be renamed |
|||
to .BAK and the new one will then be received normally. |
|||
(However, see below for the transfer resumption feature in |
|||
ZMP v1.5 and above). |
|||
Note that the byte count on the screen is not kept up- |
|||
to-date on Zmodem receive. This is because the data arrives |
|||
non-stop and there is simply no time available with non- |
|||
interrupt driven computers to update the screen. An update |
|||
is performed if errors occur, and when the computer pauses |
|||
to write to the disk. |
|||
Starting with version 1.4, Zmodem file receive will |
|||
commence automatically upon receipt of the sender's ZRQINIT |
|||
string. Thus all you need to do is have the sender initiate |
|||
the transfer, select the drive and user area you wish |
|||
the file(s) to be received on, and wait.. |
|||
ZMP v1.5 adds the ability to resume an interrupted |
|||
Zmodem transfer. If a Zmodem receive attempt fails (either |
|||
because of manual cancellation or massive errors), you will |
|||
be asked if you wish to save the portion of the file already |
|||
received. If not, it will be erased. If so, and a subsequent |
|||
Zmodem receive attempt would result in a file of the same |
|||
name, you are asked if you wish to resume the transfer. If |
|||
you do, transfer will start at the end of the file. |
|||
Otherwise the old file will be renamed to .BAK as before. |
|||
Since this feature is a function of the receiver, it should |
|||
work with any Zmodem implementation which conforms |
|||
reasonably closely to Chuck Forsberg's standard. It has been |
|||
tested with ZMP and RZMP, and I would like to hear of any |
|||
programs with which it doesn't work. No attempt is made to |
|||
determine if the files are the same up to the commencement |
|||
point: the Zmodem protocol provides two ways in which this |
|||
may be determined (file date and CRC), but neither has yet |
|||
been implemented in ZMP. |
|||
|
|||
S - Send a file. |
|||
Operation is similar to the receive function. |
|||
Additional options available are ASCII send and the |
|||
capability of distinguishing between normal Xmodem and |
|||
Xmodem-1k. In Ymodem and Zmodem modes, wildcard filenames |
|||
and multiple filenames are allowed. Multiple filenames |
|||
should be entered separated by spaces. In all cases, files |
|||
on different drives/user areas may be specified by supplying |
|||
a zcpr3-style du: prefix (e.g. C7:NEATPROG.WOW). |
|||
Byte count information is displayed in Zmodem mode on |
|||
transmit. This causes noticeable breaks between packets, but |
|||
it is felt that this is outweighed by the usefulness of the |
|||
information. ZMP's Zmodem mode is capable of CRC-32 opera- |
|||
tion, although CRC-16 mode is used if the receiver is incap- |
|||
able of CRC-32. Some other terminal programs, however, do |
|||
strange things when faced with a receiving program which |
|||
claims it can do CRC-32 (we have encountered one for the |
|||
Amiga which exhibits this problem). If this happens, the |
|||
esc-L menu and the configuration overlay have an option to |
|||
disable CRC-32. |
|||
|
|||
X - Hangup. |
|||
This function causes the modem to disconnect from the |
|||
phone line, by momentarily dropping DTR. |
|||
|
|||
Y - Print screen. |
|||
Allows the current screen to be dumped to printer. Note |
|||
that this must be supported in the overlay: most terminals |
|||
are incapable of this function. The standard overlay prints |
|||
'This function not supported.'. If you can make it work on |
|||
your system, good luck! |
|||
|
|||
Z - Clear screen. |
|||
Allows the screen to be cleared. Useful if it fills |
|||
with rubbish. |
|||
|
|||
|
|||
4. Other information. |
|||
|
|||
a) ZMP at higher baud rates. |
|||
When I first produced ZMP, I was more interested in |
|||
producing a universal Zmodem program than anything else. |
|||
Originally (several C compilers ago!) I had difficulty get- |
|||
ting it to work even at 300 baud, and so little thought was |
|||
given to accommodate higher transmission speeds. In partic- |
|||
ular, there is a "designed-in" bug/feature which would prob- |
|||
ably preclude ZMP working at much over 4800 baud. The prob- |
|||
lem is in the user overlay, in the mrd: routine. The requ- |
|||
irement here is to have a routine which returns either when |
|||
a character is available at the modem (in which case we |
|||
return TRUE), or 100 mS has elapsed (in which case we return |
|||
FALSE). The catch is that I used 100 x 1 mS waits, between |
|||
which we test for a character. A little calculation will |
|||
show that a 9600 baud character will take a little over 1 mS |
|||
to transfer, and 19200 baud characters take half this time. |
|||
Thus we are practically guaranteed to miss characters at |
|||
19200 baud, and even 9600 baud characters leave little |
|||
processing timeto spare. Two possible ways to overcome this |
|||
are: |
|||
|
|||
i) Make the wait time shorter. Thus we could wait 1000 x |
|||
100 uS periods instead. This, however, makes the actual |
|||
wait time more unpredictable, since subroutine |
|||
call/return times are comparable to the wait time. It |
|||
also just puts off the evil day. |
|||
|
|||
ii) Use a hardware timer to determine whether 100 mS has |
|||
elapsed. This is the preferred approach. Thus the mrd: |
|||
routine would loop continuously, exiting when either |
|||
there was a character at the modem or when the hardware |
|||
timer expired. An embryo CP/M-68K version of ZMP using |
|||
this approach has proved capable of reliable transfers |
|||
at 19,200 baud (although one must admit that it IS |
|||
running a 68010 at 10 MHz!). |
|||
|
|||
I would like to hear from anyone who has had any |
|||
success with either of these two approaches. |
|||
|
|||
5. Acknowledgements. |
|||
|
|||
ZMP was developed from Hal Maney's Heath-specific HMODEM II. |
|||
I would like to thank Hal for writing HMODEM: CP/M users have |
|||
been without ZMODEM capability for far too long. As requested in |
|||
the source file, acknowledgement is given to him therein. |
|||
Appreciations also go to the authors of the Hi-Tech C compiler, |
|||
which proved to be capable of producing fast and compact code for |
|||
Z80 machines. |
|||
ZMP in its various incarnations is refined by suggestions |
|||
from you, the user. In particular, I would like to thank Mike |
|||
Allen, Richard Kopplin and Fred Haines for their invaluable |
|||
suggestions. I may sometimes be a little slow at implementation, |
|||
but I usually get there eventually! Fred Haines has also kindly |
|||
offered to be the U.S. collection point for bug reports, |
|||
suggestions etc. His address appears at the bottom of this |
|||
document, and he'll forward them to me via what he calls 'U.S. |
|||
Snail'. I will try and respond using what I call 'Australia |
|||
Pest'. |
|||
I would also like to thank Lindsay Allen, sysop of Z-Node |
|||
62. His name was removed from the original zmp11 title screen at |
|||
his own request, since I had done most of the work in modifying |
|||
Hmodem to work on other machines. Without Lindsay's encouragement |
|||
at difficult times, suggestions as to how to go about |
|||
recalcitrant procedures, and experience in file transfers, ZMP |
|||
would not have been produced. Thank you. |
|||
|
|||
|
|||
6. Finally... |
|||
The files contained in this library are placed in the public |
|||
domain. Just don't sell it, claim you wrote it, or do anything |
|||
similar that might annoy me. Above all, don't bother trying to |
|||
sue me if it doesn't work, or you tripped over the disk, or |
|||
anything similar. I haven't distributed the source files partly |
|||
due to the size of them, partly due to the fact that compilation |
|||
is messy (several modifications were needed to "standard" library |
|||
functions!), and partly due to the fact that there's still work |
|||
to do on them. Besides, I feel a certain fatherly feeling towards |
|||
ZMP, having spent most of my spare time for the last four months |
|||
working on it. So here's the deal: I will continue to support ZMP |
|||
(and RZMP) until I get sick of it. This could take an unknown |
|||
amount of time! At that point, I will release the sources into |
|||
the RCP/M community, and you may make of them what you will. |
|||
ZMP has a remote system relative, called RZMP. This allows |
|||
Zmodem transfers to and from remote systems. It should be |
|||
available from the same place from which you obtained ZMP. |
|||
I have also produced an extremely cut-down version of ZMP |
|||
which runs under CP/M-68K, currently running quite well as a |
|||
single .68K file (no overlays!) on a system with 128k bytes of |
|||
memory. If there is enough interest from CP/M-68k users (are |
|||
there any??), I could be persuaded to upgrade this version to the |
|||
point where it could be released. |
|||
Comments and suggestions are welcome. Bug reports are not so |
|||
welcome, but we'd like them anyway! Send either to: |
|||
|
|||
Z-Node 62 |
|||
Perth, Western Australia |
|||
(061+) 09-450-0200 |
|||
(Soon to be on FidoNet) |
|||
|
|||
U.S. users may send reports/comments to: |
|||
|
|||
Fred Haines, |
|||
733 North King's Road, Apt. 356 |
|||
Los Angeles, California 90069 |
|||
|
|||
-- Ron Murray |
|||
26th March, 1989 |
|||
te systems. It should be |
|||
available from the same place fr |
|||
Loading…
Reference in new issue