PROGAID for Sinclair ZX81
by Albert Olivera
from Your Computer, March 1984

Albert Olivera takes you through a simple and short program
designed to add a nine-function toolkit to your ZX-81.


[The hex dump had an error in it. Byte 16759 should be 235 (EB),]
[not FF, with a checksum of 1269, not 1289.                     ]
[See the YC letters page in the May 1984 issue (page 42).   JimG]


PROGAID IS A toolkit program which provides the ZX-81 with nine
functions not available in its ROM. The routines, which occupy 399
bytes, are written entirely in machine code and are implemented with
USR calls.

The program automatically resets RAMtop and loads itself above it. It
is relocatable and can he used with any size of RAM from 1K to 16K. If
used with a RAM larger than 16K it will be necessary to set RAMtop to
maximum before loading Progaid.

Once the program is loaded it auto-runs and displays the addresses of
the different routines. These addresses are the argument of the USR
calls and vary with different sizes of RAM. On a 16K machine RAMtop is
reset to 32369, and the addresses referred to in the test of this
article will assume the use of such a machine.


Utilities available

The following are the utilities available:


RT-DOWN (address 32369): This function allows the programmer to
reserve a specified number of bytes above RAMtop, which is lowered and
brought into operation without the execution of a New command. This
means that any Basic program currently in the machine remains
unaffected by the operation. The amount of memory it is wished to
reserve is specified by typing:
	RAND xxx
where "xxx" is the number of bytes being reserved - these must be more
than 0 - for example RAND 100. The routine is then called by:
	PRINT USR 32369
which, apart from resetting RAMtop, prints the new RAMtop figure -
32269 in our example.


PGM-SVR (address 32418): PGM-SVR - program saver - allows you to store
a copy of the current Basic program behind RAMtop. Another Basic
program can then be loaded and run, and NEWed without the old program
being lost. The old program has to be recalled using the MERGE
function - see below. To implement PGM-SVR type:
	PRINT USR 32418
RAMtop will then be reset, the program will be copied behind it, and
the new RAMtop figure will be printed.


MERGE (address 32453): This function is complementary to PGM-SVR and
provides the facility to load a new program from tape without losing
the one currently loaded. To use, first store the current program
behind RAMtop with PGM-SVR. The second program is then loaded, thus
overwriting the first one in Basic area. By typing:
	PRINT USR 32453
the first program is transferred from behind RAMtop to the start of
Basic area in front of the second program.

Line numbers are not tested in any way, so if care has not been taken
beforehand line numbers - though not the lines themselves - will be
duplicated in the first and second programs. Such duplicated line
numbers cannot be edited in the usual way, but they can be regularized
with the Renumber facility - see later.


MAKE-REM (address 32518)' This facility allows users to create a Line
1 Rem of any length. The length is specified by keying:
	RAND xxx
where xxx, which must he greater than 0, is the number of characters
to be inserted in the REM statement - and then:
	PRINT USR 32518


UNREM (address 32571): PRINT USR 32571 will strip all REM statements -
except in Line 1 REM - from a program. Line 1 is excluded because it
is often used to store machine-code subroutines.


RUB-LINE (address 32617): Blocks of Basic lines can be deleted using
this function. The parameters of the block being deleted are set by
typing:
	LIST xxx
where xxx is the "from" line number - for example:
	LIST 100
then:
	RAND xxx
where xxx is the "to" line number - for example:
	RAND 430
and finally:
	PRINT USR 32617

The examples given will result in lines 110 to 430 - inclusive -
disappearing from the program.


RENUMBER (address 32643): This function renumbers a Basic program in
steps of 10. It ignores Line 1 if it exists and converts the rest of
the lines into 10, 20, 30, etc. GOTO and GOSUB destinations are not
renumbered, but the routine flags these statements by converting the
character immediately following GOTO and GOSUB into an inverse or
graphic character. The routine is called by
	PRINT USR 32643
or by:
	LIST USR 32643
which will give an automatic listing.


[The next routine in sequence is MEM-LEFT at 32728,]
[but this wasn't described in the article.     JimG]


MEM-USED (address 32743): PRINT USR 32743 will display in bytes the
amount of RAM occupied by the program currently in Basic area,
including variables if these have been implemented.

The full machine code is shown in Figure 1. The code is initially held
in a Line 1 REM statement, so the first task is to create a REM line
containing 427 characters. To load the code in Figure 1 use the hex
loader provided with Pac-81 on page 89.

Immediately the code has been loaded save everything on tape; this
will save having to enter the code all over again if an error has been
made the first time. The loader program can then be erased one line at
a time - or by using the RUB-LINE function already in the Line 1 REM,
ie. type:
	LIST 10
	RAND 150
[Actually, the Pac-81 loader/lister used lines 7000-8080. JimG]
and then:
	PRINT USR 16787
Hopefully, everything except Line 1 will disappear. If not, check the
code between addresses 16787 and 16812, as there must have been an
error made when loading the code.

The next step is to enter the Basic auto- loader program as in Figure
2, but for the time being, for testing purposes, leave out lines 10
and 160. Again save the whole on tape before proceeding further.

Now run the program and you should get a display as in Figure 3,
assuming you are using a 16K machine. This display is the program's
way of informing the user of the addresses that have to he used to
call the different facilities.

You must now test each routine, following the instructions given
earlier. If something does not work properly check that the code
stored in Line 1 is correct, using the Read Facility in the hex
loader. This program displays the contents of successive memory
locations so long as any key is kept depressed.


No incorrect entry test

Once everything is in order insert lines 10 and 160 of the auto-loader
program in Figure 2. Then save the program onto the definitive tape,
using RUN so that it will auto-run when next loaded.

It is relevant to mention here that the auto- loader program has been
written so that after resetting RAMtop and transferring the utilities
behind it, both the Basic and variable areas will he cleared, leaving
behind only the addresses message on display.

It should be noted that Progaid does not test for incorrect entries;
thus if, for example, you use the MERGE function without having first
PGM-SVRed a program, the machine will hang up. Nevertheless, the
routines do test where necessary that there is enough memory for any
particular operation, returning an Error 4 message if there is not.

