ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/commercial-software/programming/Z80TOOLS.ZIP/DISK1.ZIP/TOOLKIT.DOC

Text File | 1998-07-30 | 17KB | 413 lines

         This disk contains software described and displayed in

                         DR. DOBBS' Z80 TOOLKIT

                          by David E. Cortesi

                        The Copyright Statement

Like the book, the contents of this disk are Copyright (c) 1985 by M&T
Publishing, 2464 Embarcadero Way, Palo Alto, CA 94303.  All rights
reserved.  The original purchaser is permitted to copy this material in
any way needed to support his or her personal computer use, provided
that embedded copyright statements are retained.  Distribution of the
program source files in any form or via any medium is expressly
forbidden.  Apply to publisher for permission to distribute in object
form as an embedded part of another product.

                        The Necessary Disclaimer

Like any nontrivial software, these programs surely contain errors of
logic despite the best efforts of all concerned.  Moreover, the nature
of library functions is such as to make their misuse more likely, and
the consequences of their misuse potentially more serious, than that of
other programs.  Finally, the purpose, methods, and internal design of
the programs are described at length in the companion book.  Therefore
the reader is responsible for judging the fitness of this software for
use in any particular application and neither author nor publisher will
be liable for damages consequent on such use.

                             And So To Work

     You must perform several tasks in order to use this material.  Your
first move should be to print this file and read it through in comfort.
Then you can refer to it while typing commands, make notes in its
margin, and so forth.

     Next you must copy the distribution disks so you can put the
originals away in a safe place and use the copied files thereafter.  The
copy need not be in the same format as these disks: if you have a hard
disk, or if your normal diskette format holds more data, by all means
copy the files in your usual format.

                         The Distributed Files

     These disks should contain the following files.  They won't be in
this order but you should be able to find them all.  Here they are with
their sizes in kilobytes and capsule descriptions:

toolkit.doc       16k   this file
antdir.com         6k   lists contents of anthologies
antget.com         6k   copies files out of anthologies
cmdrel.ant/x/y    18k   anthology of command program object files
modules.rel        6k   object of modules developed in the book
env22.rel         13k   object of toolkit functions (CP/M 2.2)
env30.rel         13k   object of toolkit functions (CP/M 3.0)
environ.lib       22k   toolkit function macros
cmdasm.ant/x/y    77k   anth: command program source files
modules.ant/x/y   51k   anth: module source files
maclibs.ant/x/y   61k   anth: commented toolkit macros
seqfile1.ant/x/y 103k   anth: source of most file functions
seqfile2.ant/x/y  41k   anth: source of file open/close
strings.ant/x/y   31k   anth: source of string functions
integers.ant/x/y  27k   anth: source of integer functions
tests.ant/x/y      8k   anth: source of character tests
program.ant/x/y   16k   anth: source of program control functions

Check that they're all present and accounted for.

                         Regarding Anthologies

The design of anthologies and the anthology commands was described in
chapters 8-10.  If you haven't read them, here's a capsule explanation.
     An anthology is a collection of smaller files.  The files held in
an anthology are called "members" of the anthology.  An anthology is
held in three CP/M files.  They all have the same filename, while their
filetypes are .ANT (the data) and .ANX and .ANY (directories).  Thus you
have the three files

     cmdrel.ant
     cmdrel.anx
     cmdrel.any

which together make up the single anthology, CMDREL.
     The antdir command lists the contents of an anthology.  You can
list the contents of CMDREL, for instance, with the command

     antdir cmdrel

The antdir command is like DIR in that you may select a set of files --
say, the anthology commands -- by supplying a filespec:

     antdir cmdrel ant*.*

     An anthologized file must be copied out from the anthology before
it can be used for anthing.  The antget command copies members from
anthologies.  To copy a particular file -- say, the typist program --
from the CMDREL anthology, give the anthology name and the filespec of
the member:

     antget cmdrel typist.rel

The antget command will accept wildcards in its second operand, so you
may copy out several members with similar names:

     antget c:cmdrel b:ant*.rel

     The Antdir and Antget commands are supplied in executable form for
CP/M 2.2 (but will also run on CP/M Plus).  Other anthology commands are
in the CMDREL anthology and have to be linked before they can be run.

                  Preparing The Toolkit Object Library

The toolkit support functions are provided in two forms, one for CP/M
2.2 and one for CP/M 3.0 (CP/M Plus).  You must use the version
appropriate for your system.  The 2.2 versions will work under CP/M Plus
(but won't handle file passwords).  However, the Plus file tools will
*not* work under 2.2.
     Both sets of tools are provided in object form.  The file ENV22.REL
contains the CP/M 2.2 version; ENV30.REL is for CP/M 3.0.  Your next
task is to copy the correct version for your system under the filename
ENVIRON.  The form in which you copy it depends on whose LINK command
you are using.
     If you are using the Digital Research LINK command that comes with
RMAC, I recommend you use the Digital Research LIB command to make an
indexed relocatable library, like this (for 2.2):

     lib environ.irl[i]=env22.rel

The same command, using ENV30.REL, would be right for CP/M Plus.
     Link programs from other publishers can't handle the .IRL file
format.  For them, it's best to leave the object file in .REL format and
copy it with pip:

     pip environ.rel=env22.rel[v]

This ENVIRON object library is a file you will use fairly often, so copy
it to your assembler work disk.  You won't need the ENV22 and ENV30
files again except as backup.

                        Linking Command Programs

All the command programs developed in the book (and some bonus extras)
are stored in two anthologies: CMDASM contains their source files, and
CMDREL their object files.  To save space, only antdir and antget are on
the disk as complete .COM files.  They had to be, so you could get at
the others!
     Two steps are needed to prepare each command file.  First you must
copy it out from CMDREL; then you must link it with the support modules
and toolkit functions.  Suppose you wanted the PACK program next.
Extract it with

     antget cmdrel pack.rel

and then link it this way (using the Digital Research link command):

     link pack,modules[s],environ.irl[s]

It may be possible to link these programs using a linker from another
vendor.  However, I HAVE NOT TESTED ANY OTHER LINKER, and can't advise
on command sequences or problems.
     List the members of cmdrel now and link any that you want to use.
The resulting command files (.COM files) may be copied to other disks
for use as you see fit.  After this, you won't need the CMDREL anthology
except for backup.

     Use the same linking procedure for a program of your own, or for a
command you take from the CMDASM anthology and modify: assemble it, then
link it with the toolkit modules from the MODULES and ENVIRON libraries.
If you don't plan to write programs of your own, you needn't read any
further in this file.

                     Setting Up the Toolkit Macros

To make programs of your own or modify the ones from the book, you must
assemble them, probably with the RMAC assembler from Digital Resarch.
Before it can call on a toolkit function, any program must contain the
statement

     maclib environ

This loads ENVIRON.LIB, the library of macros that are the interface to
the toolkit functions.  But before you use it in an assembly, you must
make sure that ENVIRON.LIB is correct for your operating system.
     The very first line of ENVIRON.LIB is

     CpmLevel equ 22h

This is correct if you are in fact using CP/M 2.2 or another DOS
compatible with it.  However, if you are using CP/M Plus you ought to
edit the distributed version of ENVIRON.LIB and change that first line
to read

     CpmLevel equ 30h

Now you may copy the macro library to your assembly work disk.
     The CpmLevel equate has very little effect in your own programs and
in those from the book.  Primarily, it decides whether or not the PROLOG
macro will generate code to set the CP/M Plus Program Return Code when a
program ends.  CP/M 2.2 doesn's support a Program Return Code, but no
harm comes from trying to set it.
     The effect of CpmLevel on a toolkit function can be profound.  Some
of the file functions assemble drastically different code in the two
systems.  That explains why you received two different toolkit object
libraries (ENV22 and ENV30) but only one set of command object files
(CMDREL).

     Now that ENVIRON.LIB is ready to use, you might like to to examine,
change, and reassemble the source of the command programs.  Those files
are in the CMDASM anthology.  List its members with antdir and extract
them with antget.  Once copied out, you may treat them like any other
assembler source files.

                         Commented Macro Source

Should you examine ENVIRON.LIB, you will see that it contains no
comments or pretty formatting.  That is because it has been processed by
the command SQASM, a utility that strips all comments, blank lines, and
redundant spaces from an assembly source file.  Stripping ENVIRON.LIB
makes it smaller, which shortens assembly time a lot.
     Commented versions of the macros do exist.  They are contained in
the MACLIBS anthology.  Check it with antdir; you'll see it contains
several macro libraries.  Feel free to extract them with antget and
browse through them.
     ENVIRON.LIB is constructed by catenating seven of those libraries.
Each of the seven contains macros from a different area.  The files are
separated for ease of editing, then made into a single ENVIRON.LIB for
ease of assembly.  If you should want to make a change in ENVIRON.LIB
(not something you would normally do), here is the right way to go about
it.  First, extract its seven components (this could be a submit file):

     antget maclibs equates.lib
     antget maclibs smallz80.lib
     antget maclibs program.lib
     antget maclibs seqfile.lib
     antget maclibs tests.lib
     antget maclibs integers.lib

Then edit the library that contains the macro to be changed.  Put the
updated version back in MACLIBS with antput.  Then create a new
ENVIRON.LIB with these commands (which ought to be a submit file):

     sqasm equates.lib 1.x
     sqasm smallz80.lib 2.x
     sqasm program.lib 3.x
     sqasm seqfile.lib 4.x
     sqasm strings.lib 5.x
     sqasm tests.lib 6.x
     sqasm integers.lib 7.x
     era environ.lib
     pip environ.lib=1.x,2.x,3.x,4.x,5.x,6.x,7.x
     era *.x

The SQASM command is in CMDREL; you'll have to link it for use.

                         Extra Macro Libraries

The MACLIBS anthology contains four macro libraries that are not used in
ENVIRON.LIB.  The first is SERVICES.LIB; it contains equates for all the
BDOS services, and a macro that makes it easy to call the BDOS.  Use it
in programs of your own if you need to write explicit calls on the BDOS.
The second extra is FCR.LIB; it describes the fields of a File Control
Record.  You should never need to include it in your own programs.
However, FCR and SERVICES are used by some toolkit functions, and you'd
have to copy them out in order to reassemble those source files.
     A third library, BIOSCALL.LIB, is used by none of these programs.
It defines names for BIOS entry points and has a macro for calling the
BIOS.  The call goes through a module, BIOS, that is present in the
ENV22/30 object libraries (its source is in the PROGRAM anthology).
     Finally, OTHERZ80.LIB contains the Z80 instructions that were
omitted from ENVIRON.LIB.  The instructions that deal with index
register IY, with the alternate register set, with the unauthorized Z80
instructions, and with hardware I/O are defined here.  If you need them,
copy out this library and name it your programs.

                        The Toolkit Source Files

     The assembly source of toolkit functions is contained in five
anthologies, each corresponding to one functional area.  You'll notice a
correspondence between the names of these anthologies and the names of
five of the maclibs in the MACLIBS anthology.  That's no coincidence!
The modules stored in the SEQFILE anthologies are the ones that are
called by the macros found in SEQFILE.LIB, and the same correspondence
holds for the PROGRAM, STRINGS, TESTS, and INTEGERS anthologies.
     To view a module's source, extract it with antget.  Should you want
to assemble one, notice which macro libraries it includes, and extract
those from the MACLIBS anthology for it to use.
     Should you change a module, you may test it with a program of your
own by naming it separately in the link:

     link testprog,newmod,environ.irl[s]

Here "testprog" is a program that will exercise the changed function of
"newmod."  Since it is specifically named, the file "newmod.rel" will be
linked while the old version of it still in ENVIRON.IRL will be ignored.
     After testing a module may be updated in ENVIRON.IRL with the LIB
utility from Digital Research:

     lib environ.irl[i]=environ.irl<newmod>

The order in which modules appear in ENVIRON.IRL is critical: a module
must follow all the modules that call upon it, and ZZPROG must be the
very last.  Thus you should only update a module in the way shown above;
don't use LIB to delete a module or tack it on the front or back.
     In the unlikely event that you have to reassemble and reconstruct
the entire toolkit object library, here is a table of all the toolkit
source modules, with their source anthology names, in the order that
they appear in ENVIRON.IRL:

; file control routines
     fckpt seqfile1
     fdirs seqfile1
     fattrs seqfile1
     fqeof seqfile1
; get routines
     fsgbw seqfile1
     fsgxw seqfile1
     fskip seqfile1
     fsgst seqfile1
     fsgac seqfile1
     fsgbk seqfile1
     fsg24 seqfile1
     fsgbb seqfile1
     fsgby seqfile1
; put routines
     fspbx seqfile1
     fspwx seqfile1
     fsplx seqfile1
     fspbd seqfile1
     fspbw seqfile1
     fspsw seqfile1
     fspld seqfile1
     fspst seqfile1
     fspac seqfile1
     fspbk seqfile1
     fsp24 seqfile1
     fspbb seqfile1
     fspby seqfile1
; direct-access routines
     frecda seqfile1
     fsize seqfile1
     fnote seqfile1
     fseek seqfile1
; open/close routines
     fopni seqfile2
     fopno seqfile2
     fopna seqfile2
     fopnu seqfile2
     fopnc seqfile2
     fopne seqfile2
     fbufr seqfile2
     fmake seqfile2
     fclos seqfile2
     fpass seqfile2
     fasgn seqfile2
; internal file routines
     frfil seqfile1
     fbadv seqfile1
     fbout seqfile1
     fbupd seqfile1
     fbinp seqfile1
     fbrra seqfile1
     fbaim seqfile1
     feror seqfile1
     fstsp seqfile1
; string functions
     strhex strings
     strplw strings
     strpbw strings
     strpbb strings
     strpnd strings
     strtxt strings
     strput strings
     strtak strings
     strapp strings
     strend strings
     strgsw strings
     strgbw strings
     strgxw strings
     strskp strings
     strlok strings
     strcmp strings
     strlen strings
; integer arithmetic
     random integers
     lwldst integers
     lwarth integers
     cpllw integers
     div816 integers
     divlw integers
     divsw integers
     divbw integers
     mpy816 integers
     mpysw integers
     mpybw integers
     cmpsw integers
     cplbw integers
     addahl integers
; tests
     touppr tests
     test01 tests
     test02 tests
     test03 tests
; program control
     cmdtok program
     dsaloc program
     ramfil program
     bios program
     zzprog program
sts
; program control
     cmdtok program
     dsaloc program