CP/M v2.2 and 3.1 for the PCW16 - version 1.00        John Elliott, March 1999
===============================================================================

Legal bits
==========
  If you are just going to use CP/M, the licensing issues need not concern 
you; but if you want to give or sell it to anyone, you will need to consult 
the detailed section entitled "COPYING" at the end of this document. 

Overview
========

  Unlike previous PCWs, the PCW16 was not supplied with CP/M. This program
provides a CP/M environment.

What will run:                   What won't run:
--------------                   ---------------
BASIC and BASIC programs         Any graphical programs
Programs written for CP/M 2      Programs that try to control the PCW's 
Programs written for CP/M 3      hardware directly (eg: DISCKIT)


Installation
============

  If you have downloaded these files from the Internet, you will need to 
write out two "disc image" files (PCW720.RAW and CPMDISC.RAW) to 720k 
floppy discs. To do this under DOS, you need to use RAWRITE.EXE; under Unix, 
use a command similar to:

  dd if=pcw720.raw  of=/dev/fd0
  dd if=cpmdisc.raw of=/dev/fd0

(RAWRITE.EXE can be obtained by ftp to sunsite.doc.ic.ac.uk, as:

         /computing/operating-systems/unix/FreeBSD/tools/rawrite.exe

. Under Windows 95, RAWRITE only works in DOS mode.)

  If you received this program on disc, there should be at least two floppies 
- the "program" disc and the "start-of-day" disc.

Running CP/M
============

  With the PCW16 screen displaying the Desktop, press TASK and F7 together. 
Insert the "program" disc, and click "Disc" on screen. The list of programs
below will include "CPM for the PCW16"; highlight it and press the green key.

  When prompted (and not before) insert your "start-of-day" disc and press 
the green key again. You will then see the CP/M sign-on message, followed by
a number of other messages describing what facilities are available.

  The CP/M version at this point will be 2.2, as opposed to 3.1 on the
earlier PCWs. To switch to version 3.1, follow the instructions below.

  When you have finished using CP/M, type DESK to return to the Desktop.
 
  Although I refer to "CP/M 2.2" in this documentation, the actual BDOS and 
CCP are the third-party replacements SUPRBDOS and ZCPR-D&J (as supplied with 
YAZE). This is to avoid problems of copyright. 

  Similarly, the CP/M 3 BDOS supplied is Simeon Cran's ZPM3 - see ZPM3DIST.TXT 
for copyright details. 

Switching to CP/M 3
===================

  To switch to ZPM3, you will need to have access to an old-style PCW. 
Start CP/M on the old-style PCW, insert a _copy_ of your PCW16 start-of-day 
disc, and type:

         SUBMIT MAKECPM3

  - this will convert the disc to a ZPM3 start-of-day disc. To switch back to 
   CP/M 2, type the command:

         SUBMIT MAKECPM2

  If you are using ZPM3, you will find that the arrow keys don't react 
correctly at the A> prompt. This can be cured by the command

    LOADKEYS ZPM3.KEY

but you will then find that programs like BASIC won't recognise the arrow
keys; you have to hold down SHIFT while using them.

Supplied programs
=================

  None of the CP/M 2 or 3 tools has been supplied in this release; you can 
download them from <http://cws86.kyamk.fi/mirrors/cpm/>, or get them from the 
system discs of an old-style PCW. Again, this is for reasons of copyright. 
  Note that the CP/M 3 tools at cws86.kyamk.fi are more recent versions than
those on the PCW system discs, having been updated by your humble servant for 
Year 2000 compliance and other bug fixes. 

The following programs are present on the disc:

* DESK    .COM - Return to the Rosanne desktop.
* CRTFONT .COM - Load/save screen fonts.
* LOADKEYS.COM - Load/save keyboard layouts. 
* DU55    .COM - Disc format/copy/verify program, use instead of DISCKIT.
                 Note: DU55 requires CP/M 3 or ZPM3.
* DU55    .DOC - Instructions for DU55.
* DU55CON .COM - Format editor for DU55.
* LANGUAGE.COM - Select the national character set.
* SET24X80.COM - Switch to the 24x80 screen, or back to the 30x80 screen.
* SETLST  .COM - Send a sequence of characters to the printer.
* SETSIO  .COM - Set up the serial port.
* PALETTE .COM - Set up the screen colours.
* CALLANNE.COM - An example of how to call Rosanne from CP/M, with source.
* NSWP    .COM - The well-known PD file manager; included so you don't need
                 PIP or STAT to copy files or check disc space.
* SETCCP  .COM - }
* NULU    .COM - } Used by MAKECPM3.SUB
* QT16-01C.LBR - Trevor Gowen's QTERM overlay - supports serial communications
                 up to 4800 baud. You will need a copy of QTERM to use this
                 overlay.
* XLOGSEA .COM - XLOGIN is a utility for older PCWs and Spectrum +3s, allowing
                 them to use discs in the PCW16's "720k boot/root" format.
                 Run XLOGSEA.COM on an older PCW, and it will create several
                 files; you should read the one called XLOGIN.DOC. 

  The following programs are part of, and only work under, ZPM3:

* AUTOTOG .COM - ZPM3 utility to activate automatic command prompting. Type
                AUTOTOG ON to activate, and then press CTRL and Q together.
                ZPM3 will then try to guess what your command is based on 
                previous commands.
* CLRHIST .COM - ZPM3 utility. ZPM3 remembers previous commands you have typed;
                this clears out the stored commands.

Organisation
============

  In this release, all system files are stored in the boot file - this is 
called A10CPM2.EML for CP/M 2, or A10ZPM3.EML for ZPM3.

Features
========

  If there is no .EML file on the start-of-day disc, CP/M will load with a 
very basic specification:

* 56k TPA
* 1 floppy drive, read-only access
* Dumb terminal screen

  If the start-of-day disc does have a suitable .EML file, then the 
specification becomes:

* 56k TPA (61k under CP/M 3)
* 1 floppy drive, read/write access. The drive can be used as A: and B:
* 512k drive M:
* VT-52 compatible screen
* Support for the parallel printer
* Support for the serial port

  For programming information, see the "Technical" section at the end.

New in this release
===================

* This is the first general release.

Known Bugs and Features
=======================

  Under CP/M 2, you must be very careful to change discs only at the A>
prompt, and to press STOP when you do.

Missing Features (or, the Wish List). 
None of these is essential for normal use of CP/M.
==================================================

 * Some of the DD_* USERF calls are missing, but they require direct 
  programming of the floppy controller (see below).
 * EXPORT/IMPORT programs to access the Cabinet.
 * Equivalent of the PAPER / DAISY utility on an old PCW.
 * GSX support.
 * Currently, CP/M is implemented as a Rosanne application; there may be a 
  case for writing it to use only the hardware, so that it can be loaded onto
  a "bare" PCW16. Then again, there may not.

Technical information
=====================

  For technical and programming information, see the file USERF.TXT.

VT52 screen driver
==================

  The screen driver accepts all escape codes used on "classic" PCWs.

  It also accepts the following CRTPLUS codes:

* ESC + B <n>              (set border colour)
* ESC + a <n> and ESC - a  (AND with character <n>)
* ESC + b  and    ESC - b  (bold on/off)
* ESC + d  and    ESC - d  (double width on and off)
* ESC + D  and    ESC - D  (doublestrike on/off)
* ESC + f  and    ESC - f  (flashing cursor on/off)
* ESC + g  and    ESC - g  (grey text on/off)
* ESC + h  and    ESC - h  (double height)
* ESC + i  and    ESC - i  (italic text on/off)
* ESC + o <n> and ESC - o  (OR with character <n>)
* ESC + u <n> and ESC - u  (set underline style)
* ESC + x <n> and ESC - x  (XOR with character <n>)

  The ESC x (set 24x80 screen) and ESC y (set 30x80 screen) are done by 
changing the font size. The ESC 3 n (change mode) is done by changing the 
screen resolution, which can be quite alarming if you aren't expecting it.

  The program CRTFONT allows you to switch screen fonts. The syntax is:

CRTFONT <fontfile>             - to load a font for the 30x80 screen
CRTFONT <fontfile> [TALL]      - to load a font for the 24x80 screen
CRTFONT <fontfile> [SAVE]      - to save the current 30x80 font
CRTFONT <fontfile> [TALL,SAVE] - to save the current 24x80 font

  The supplied fonts are based on the "S" font supplied with Slackware Linux,
but using the same character set as a "classic" PCW.

  The program PALETTE lets you change the screen colours. Unless your PCW16
has a colour display (and just how likely is that?) you will be limited to 
three colours - black, white and dark grey.

  The command to use is:

PALETTE background foreground

  where each of "background" and "foreground" is a number. Numbers you should
use are:

   0 - Black
  21 - Dark grey
  63 - White

  The PALETTE command can take more than two numbers; the extra ones get used
as additional "foreground" colours if the screen is in Mode 0 or Mode 1.

Keyboard driver
===============
  Keyboard redefinition is possible. Redefinition is done by the LOADKEYS 
command:

LOADKEYS keyfile

where "keyfile" is a series of ASCII lines.
  It is possible to save the current keyboard state with the command:

LOADKEYS keyfile.kmt [SAVE]

 - this saves a "keymap" file that can then be reloaded by LOADKEYS.

  For full details of keyboard functions, see the file KEYBOARD.TXT.

Floppy driver
=============

  The floppy driver can use only CP/M format discs with 9 sectors per track. 
This allows the use of 706k discs from old-style PCWs, high-density discs 
formatted with DU55, and my 702k "DualDOS" format.
  CP/M can be booted from a 706k PCW-format disc or a 1.4Mb disc formatted 
with DU55. 
  As on a PCW "classic", you can use drive B: even when there is only one 
floppy drive; you will be asked to insert the "disc for A:" or the 
"disc for B:". However, since CP/M 2 has a fairly intimate relationship with 
the A: drive, this feature is only really useful under CP/M 3.

SETLST.COM
==========

  SETLST.COM can be used to send a sequence of control codes to the printer.
The command to type is:

  SETLST "string"

  where string is the sequence of characters you want to send. It will be 
interpreted as follows:

  Letters will be converted to lower case.
  A letter after a % sign will remain upper-case.
  A letter after a ^ sign will be converted to a control character.
  %% becomes %
  %^ becomes ^
  %" becomes "
  The sequence ^#<number># becomes the character with the given number.

  So:

    SETLST "^L"      sends Control-L (form feed).
    SETLST "^[D"     sends ESC d  
    SETLST "^[%D"    sends ESC D
    SETLST "^#140#"  sends character 140.
    SETLST "^[%%1"   sends ESC % "1"
    SETLST "^[%%^A"  sends ESC % 1

Serial port
===========

  The serial port driver is based on Trevor Gowen's QTERM overlay. When 
CP/M is first starting, there may be a delay of a few seconds while the 
serial driver tries to detect if there is a communications link in place.

  To set communications parameters, use SETSIO - type SETSIO [HELP] for a
list of the various parameters that can be used. Note that a SETSIO command
line should contain no spaces between options - only commas.

  The three handshake protocols that can be used are:

[PROTOCOL=1] : RTS<>CTS handshake only.
[PROTOCOL=2] : DTR<>DSR handshake only.
[PROTOCOL=3] : RTS--CTS "connect" (CTS checked during Tx), DTR<>DSR handshake.

Single-floppy startup
=====================

  This version of CP/M is able to use one single start-of-day disc rather 
than separate PCW16 and CP/M ones. Discs of this type are known as "boot/root 
discs".

  Currently, the use of boot/root discs is not recommended, because older 
PCWs cannot access them except by using DU55 or XLOGIN. Therefore the CP/M 3 
upgrade procedure above can not be carried out. However, this is a useful 
way of making "turnkey" discs designed to load one particular program.

  To experiment with boot/root discs, insert the disc you made from PCW720.RAW
and run "CPM for the PCW16" on it, as usual. When the prompt appears asking 
you to insert the start-of-day disc, leave the PCW disc in the drive and click 
[OK]. CP/M 2 will load; as mentioned above, the CP/M 3 upgrade cannot be 
performed easily on these discs.

  The file PCW1440.RAW contains a 1.4Mb boot/root disc.

_______________________________________________________________________________

Acknowledgements:
-----------------

Cliff Lawson and Richard Wildey, for programming information.
Simeon Cran, for letting me use the ZPM3 BDOS.
Trevor Gowen, for the QTERM overlay, the printer FID, and alpha-testing.
Tony Velate, for alpha-testing.

_______________________________________________________________________________

COPYING
=======

  CP/M for the PCW16 is composed of a large number of components with
different distribution conditions. If you intend to distribute it, you may 
have to be careful about what gets included.
  In particular, ZPM3 can't be sold. If you want to start selling a CP/M-3
system based on this program, you will need to:

* Ask Caldera about distributing real CP/M 3 for money, or
* Ask Simeon Cran about distributing ZPM3 for money.

ZPM3 components
===============

  ZPM3 may not be sold; see ZPM3DIST.TXT for details.

  ZPM3 components are: ZPM3.SYS, ZPM3DIST.TXT, CLRHIST.COM, and AUTOTOG.COM.

DU55
====
  
  DU55 may only be distributed with PCW16 CP/M. No source code is 
provided. There are no other restrictions on the distributeion of DU55.

NSWP, NULU, CALLANNE, SETCCP
============================

  These .COM files are public domain software or freeware and have no 
restrictions of any kind on distribution.

Other .COM files
================

  The other .COM files provided are distributed under the GNU General Public
License, version 2 (see COPYING).

Other system files
==================

  The system files (*.FID, BNKBIOS3.SPR, GENCPM.DAT, ANNELDR.PRG) are 
distributed under the GNU Library General Public License, version 2. This is
so they can be linked with a proprietary CP/M BDOS.

  The CP/M 2 implementation supplied is SUPRBDOS plus ZCPR-D&J. Both
of these programs are freely redistributable.

Documentation
=============

  One final point; you should update this documentation if your distribution of
CP/M is packaged differently from the original. There is nothing to stop you 
including ZPM3, or supplying a single-disc startup, or omitting one or more 
drivers from the .EML file; but under these circumstances, the documentation
should be altered to make it clear what has been changed.


