B0B1COPY - Copy between page 0 and page 1 of a CE-163 module

This code is expected to run in the SHARP PC-1500/A and the TANDY PC-2.
It requires a module CE-163.

                          !!!!BE CAREFUL !!!!
This routine is expected to copy a binary block from/to page 0 to/from
page 1 of the switchable CE-163 memory module. Be sure that you have saved
your important job before using it.

Your are own responsible of the memory organization of the page 1. This
page 1 may be used as a backup page to save not used program or data, but
you should organize it yourself. The B0B1COPY will not perform checks
before starting the copy.
!!! YOU SHOULD ALWAYS BE IN THE PAGE 0 WHEN YOU RUN IT !!!

This version is still in pre-alpha release. It is not fully mature and bugs
are present.

------------------------------- IMPORTANT --------------------------------
I am not responsible for any data or programs lost or corrupted after you
ran this program.
I am not responsible for any damages resulting by using this program.
                    YOU USE IT AT YOUR OWN RISKS !
--------------------------------------------------------------------------

1. Installation

This program may be installed every where in main RAM (&4000..&4800 for a
PC-1500/PC-2 or &4000..&5800 for a PC-1500A). But IT SHOULD REMAIN IN THE
PAGE 0 OF CE-163. Do not install it in the page 1.

To select the page 0:
   POKE &5800,0 (for PC-1500/PC-2)
   POKE &6800,0 (for PC-1500A)

To select the page 1:
   POKE &5801,0 (for PC-1500/PC-2)
   POKE &6801,0 (for PC-1500A)

The zip archive contains the following files:
   COPYING      - The GPL v2
   README       - This file
   b0b1copy.asm - The disassembled code
   b0b1copy.bin - The binary image of B0B1COPY
   b0b1copy.wav - The WAV file to load with CLOAD M (by default the code
                  will be loaded at &40C5. If you prefer to load it at
                  another address, do CLOAD M<myaddress>)

In all examples below, we assume a PC1500/PC-2 and the routine in &40C5.

On the SHARP PC1500/A/PC-2, select the page0 and just do
   POKE &5800,0
   NEW &41A1
   CLOAD M
or
   POKE &5800,0
   NEW <address>+220
   CLOAD M<address>
if yoy want the program to be loaded to the <address> given.


2. Usage

This program is launched by
   POKE &5800,0
   var$="sssseeeepdddd"
   CALL <address>,$var$
where var$ is a BASIC string variable with the following content:
   sssseeeepdddd
with:
   ssss : The start address of the block to be copied
   eeee : The end adress + 1 of the block to be copied
   p    : The destination page with < for page 0 and > for the page 1
   dddd : The start destination address where the block will be copied

The program will perform a minimal checks about the string given. It
raises the following errors:
   ERROR 1  : The CALL &40C5 is not followed by a string variable
              The page symbol is not < or >
   ERROR 36 : A given address is not a valid 4-hexadecimal digits number


3. Examples

In all examples below, we assume a PC1500/PC-2 and the routine in &40C5.

To copy the RESERVE (&0008 .. &00C4) area from page 0 to the page at the
address &1800, do
   POKE &5800,0
   E$="000800C5>1800"
   CALL &40C5,E$

To copy the binary area &2ADA .. &2C76 from page 1 to &2100 in page 0,
do
   POKE &5800,0
   F$="2ADA2C77<2100"
   CALL &40C5,F$

If you load the routine at another address, replace CALL &40C5,var$ by
CALL <address>,var$.

Because it not switchable, the main RAM (&4000 .. &4800 or &5800) may be
copied from page 0 or 1 or to page 0 or 1.
The next action
   POKE &5800,0
   B$="40C54800>00C5"
   CALL &40C5,B$
will copy the whole main RAM to the destination address &00C5 in page 1;
the main RAM is seen in page 0.

In a same way
   POKE &5800,0
   A$="0008000C5<40C5"
   CALL &40C5,A$
will copy the RESERVE area from main RAM (seen in page 1) to the RESERVE
area in page 0.


4. Restrictions

This routine is expected to run only with a CE-163 switchabe memory module.
It will work with other memory modules, because they are not switchable,
so the same memory will be seen in page 0 and also in page 1, but NEVER
COPY BLOCKS WHICH OVERLAP ! The result may be unpredictable...
You will corrupt the data and may raise a crash.

Even with a CE-163, never copy a block going outside the CE-163 area with
another block going outisde the same area. The result will be unpredictable
and may corrupt the data and may raise a crash.
For exemple:
   POKE &5800,0
   Z$="38004400>3C00"
   CALL &40C5,Z$
will corrupt the block copied, because the area from &4000 to &4800 is not
switchable and will be taken in page 0 and page 1.


5. Copyright and license

Copyright 2012 Christophe Gottheimer <cgh75015@gmail.com>

B0B1COPY is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License version 2 as published by the Free
Software Foundation.  Note that I am not granting permission to redistribute
or modify nsimII under the terms of any later version of the General Public
License.

This program is distributed in the hope that it will be useful (or at
least amusing), but WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along with
this program (in the file "COPYING"); if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

