Section I
INTRODUCTION

ZCPR3: THE LIBRARIES

A Reference Manual
and
User's Guide
for
SYSLIB, Z3LIB, and VLIB

Written by
Richard Conn

Copyright 1986    Richard Conn







This Page Left Blank




ZCPR3: The Libraries Introduction

1. INTRODUCTION

1.1. What Are the Libraries of ZCPR3?

The libraries of ZCPR3 consist of SYSLIB (SYStem LIBrary),
Z3LIB (ZCPR3-specific routines), and VLIB (screen-oriented
routines for ZCPR3). These libraries are intended to relieve the
programmer of the task of frequently "re-inventing the wheel" and
to provide him with an environment of reliable tools which
encourages structured programming at the assembly language level.

Each routine in the libraries can be viewed as a reliable
"black box." The routines are completely documented within this
manual and the help files (which can only be viewed under the
HELP tool of ZCPR3), and the programmer is consistently provided
with the following information:

1. Name of Subroutine

2. Function it performs

3. What its inputs are

4. What its outputs are

5. What registers are affected by it

6. What other library routines it calls upon

7. What errors can occur and how it handles them

The routines are designed to work together and complement
each other. Parameter passing is consistent between the various
subroutines. For instance, all routines which need to be passed
a pointer to a File Control Block are passed that pointer in the
DE register pair.  As a general rule, if a register is not
returned as an output from the routine, then its value is not
affected (it has the same value when the routine is exited as it
had when the routine was called).

The libraries are relocatable object modules created in the
Microsoft M80 relocatable object format.   The M80 or ZAS
assemblers can be used to create and manipulate relocatable
object modules.  All routines are grouped within functionally-
related modules.  Once a routine is referenced (by the EXT
statement in the M80 assembly language program), its module is
loaded and it is available to the programmer by means of a simple
subroutine call.  All other subroutines within that particular
module are also loaded, but they are not available to the
programmer unless he has also referenced them by EXT statements.
The module is loaded only once, regardless of how many routines
within the module are referenced. For this reason, each module
was designed to contain routines which are frequently used
together or are called by each other (one routine within the
module calls another routine within the module).

1-1

ZCPR3: The Libraries Introduction

1.2. What is Needed to Use the Libraries?

You need an 8080, Z80, NSC800, or HD64180-based micro-
computer with at least 48K bytes of contiguous memory running
ZCPR3 or Z-System <ZCPR3 and ZRDOS), the Microsoft M80 assembler
tool set (specifically, the M80 assembler and the L80 linker) or
the Echelon ZAS assembler tool set (specifically, the ZAS
assembler and ZLINK linker), and the usual set of software
development tools (an editor and, preferably, a debugger) to use
the libraries.




1.3. What Do the Libraries Buy You?

To the experienced programmer, the libraries have the
potential of being a significant tool which enables him to:

1. Solve his programming task quickly

— because he spends less time writing
commonly-used subroutines and worrying about how his
registers are affected by these subroutines and more
time concentrating on the problem at hand.

2. Write space- and speed-efficient code

— because all of the routines have been gone
over time and time again to reduce their size and make
them more efficient in terms of speed. For example, the
SORT routine is a Shell Sort that can be called to
perform the sort using pointers (in which case it
exchanges pointers rather than records when it needs to
do a swap) or perform the sort without using pointers
(when space is a factor and there may not be enough room
for a pointer table).

3. Write more maintainable code

— because the libraries are designed with
structured programming philosophy in mind.   Each
subroutine is equivalent to a process box, having (1)
only one entrance and one exit, (2) a precisely-defined
function, and (3) a precisely-defined set of input and
output parameters.  Having used the libraries for some
time now, the author has noted that his programming
thought processes and program designs have tended more
and more toward end-in (top-down from the objective
point of view and bottom-up from the library subroutine
point of view), structured designs that he can go back
to at a later date and readily decipher and modify.

4. Reduce the programming effort

— because the libraries provide a number of
very involved routines which would, in themselves, take
quite some time to code. For example, the DIRF routine
will load the directory of a disk into memory, select a
set of files from that loaded directory as specified by
a File Control Block and a flag which indicates whether
to include System or Non-System files and what user area
is to be examined, packs the loaded directory (removing

1-2







ZCPR3: The Libraries                                 Introduction




entries not selected from the memory buffer),
alphabetizes the directory entries by file name and type
or by file type and name, and returns a pointer to the
first entry and a count of the number of entries
selected.

In many ways, the libraries bring advantages of programming
in a High-Order Language, like C or Pascal, to the assembly
language programmer. They allow him to maintain the smaller code
size and greater efficiency which can be realized in assembly
language programming and simultaneously realize a reduced life-
cycle cost (from development to fielding to post-fielding
maintenance and modification) over assembly language programming
without a similar tool set.

1.4. How Do You Assemble with the Libraries?

Each example at the end of this manual shows an assembly of
the sample program.  Each program uses SYSLIB only, so the
commands required to assemble and link the programs are straight-
forward :

ZAS filename

This command assembles the file named filename.Z80 and produces
an output file named filename.REL.   This output file must be
linked with SYSLIB to create the absolute object code file.

ZLINK filename,A:SYSLIB/

This command links filename.REL with SYSLIB.REL (SYSLIB.REL is on
drive A) and produces filename. COM.   This COM file may now be
executed.

If the program uses Z3LIB or VLIB, then these libraries must
be specified in the ZLINK command in the proper order.  VLIB uses
routines in Z3LIB and SYSLIB, and Z3LIB uses routines in SYSLIB.
If a program uses VLIB, then VLIB, Z3LIB, and SYSLIB must be
linked (in that order):

ZLINK filename,A: VLIB/,A: Z3LIB/,A: SYSLIB/

If a program uses Z3LIB, then Z3LIB and SYSLIB must be linked (in
that order):

ZLINK filename.A: Z3LIB/,A: SYSLIB/

The examples were done on a ZCPR3 system, and the user is
always on Drive B; doing the development work, while the editors,
assemblers, and libraries (SYSLIB.REL, Z3LIB.REL, and VLIB.RED
are on Drive A: .   (The files may be on drive A in a PUBLIC
directory if using ZRDOS, Version 1.2, or later.)

1-3

ZCPR3: The Libraries Introduction

1.5. How to Learn-to Use the Libraries Effectively?

This is opinion, of course, but I feel that the best way to
learn how to use the libraries would involve the following steps:

1.   Study this manual in an overview fashion,
familiarizing yourself with the functions of the subroutines
available.

2.  Study in some detail the sample source programs at
the end, jumping back to the main body of the manual from time to
time to see why the routines I selected in the programs were used
in the way I used them.

3.  Try coding a couple of the routines in this manual,
copying them verbatim and assembling them.

4.  Try making up a few simple problems of your own and
use the libraries to code them.

5.  Apply the libraries to a significant program you
want to write.




I am a strong advocate of writing programs in order
how to program, and I feel that it is most important to
as much familiarity with the routines as you can and (2)
programs using these routines.

to learn
(1) gain
to write

1.6. Comments on Software Engineering

We are experiencing a SOFTWARE CRISIS today, the basis of
which is simply that it is more difficult to build reliable
software systems that we think it should be.  All too often, the
symptoms of the SOFTWARE CRISIS are seen:

o Cost - unpredictable and judged excessive
o Efficiency - time and space utilitization are

not efficient

o Modiflability - software is difficult to change
o Reliability - software often fails
o Responsiveness - user needs are not met
o Timeliness - software is not delivered on time
o Transportability - software used on one system

may not be used on another

The bottom line in the design of a software system is that
the software should meet its stated requirements.   To achieve
this end, the field of SOFTWARE ENGINEERING has arisen.   The
goals of SOFTWARE ENGINEERING are:







1-4

ZCPR3: The Libraries                                 Introduction




1. Modif lability ~ Software should be easy to change, and
software should be designed with later change in roind.

2.   Efficiency - The software system should use its
available resources in an optimal manner.

3.  Reliability - The software should perform according to
specification and recover safely from failure during use.

4. Understandability - Software should be easy to read and
follow.  Understandability is the tool used to pass from a
particular problem space to a solution.

The libraries attempt to help the programmer achieve the
goals of Software Engineering by applying the principles of
Software Engineering. These principles are:

1. Abstraction and Information Hiding - Unnecessary detail
is hidden from the user. For example, the DIRF routine loads the
contents of a disk directory into a memory buffer. How this load
is done is hidden from the programmer — all he needs to know is
that the load was done and he now has a vector of directory
entries to work with.

2.  Modularity - the libraries is very modular in design.
Each routine in the library performs one and only one function,
and the documentation provides complete detail as to what that
function is, what its input parameters are, what its output
parameters are, what its side effects are, and other data.

3.   Localization and Loose Coupling - library modules are
loosely coupled — each module may be treated independently of
the others.  Additionally, the modules are strongly cohesive —
the components of each module are intimately related to each
other but not to components of other modules.

4. Uniformity - The calling conventions between the various
modules are consistent with each other, and it is frequently the
case that the output parameters from one module may be directly
used as input parameters to another.

5.  Completeness - Each module or group of related modules
are functionally complete. No additional functions are required.

6. Confirmabiiity - A program written using library modules
can be readily decomposed for incremental testing.

1-5

ZCPR3: The Libraries Introduction

1.7. Definitions of Terms

Some frequently-used terms are defined below.

1.  Buffer - A contiguous vector of bytes in memory.  The
buffer is known by its starting address and size (in bytes).
Example:

buffer:   DS   40   ; 40-byte buffer

2.   Character - A one-byte (8-bit) value.  A value range
within the ASCII character set (a 7-bit value) is implied but not
required, so a character could have a value of 81H.

3*  Directory - An index to the files on the disk.  An entry
in a directory contains the name of a file, the user number it
resides in, how large the file is, and where the file is located
on the disk.   The information loaded by the SYSLIB directory
routines does not include file location information, but does
include everything else.  In another sense, the term directory is
used to refer to a particular disk and user area (such as A4 or
B31).

4.  DMA (Direct Memory Access) - The address of the 128-byte
block in memory through which disk file I/O is performed.  128-
byte blocks are read and written from and to the disk through
buffers identified by the DMA address.

5-  File - Any CP/M file, which may be either text or
binary.  SYSLIB makes no distinction between these two types of
files.

6.   FCB (File Control Block) - A 36-byte buffer which
corresponds to the full definition of a CP/M Pile Control Block.
SYSLIB FCB's are ALWAYS 36 bytes long.   In many cases, when a
routine requires a user-supplied FCB, the user need only fill in
the file name and type fields (bytes 1-11) and need not concern
himself with the rest of the fields.  The INITFCB routine stores
zero in all bytes except bytes 1-11 of the FCB.

7.   FD (File Descriptor) - Any data structure used to
identify a file and contain pertinent data used to access the
file via open, close, read, write, etc., routines.  The term "FD"
is encountered in UNIX terminology.

8.  IOCB (Input/Output Control Block) - An extension to the
FCB concept used by the byte-oriented file input/output routines.
An IOCB, also known as IOCTL, contains an FCB and other data
buffers.

9.  LPD (Library Utility Descriptor) - An extension to the
FCB concept used by the library utility routines for library file
input/output.  An LUD contains an FCB and other data buffers.










1-6

ZCPR3: The Libraries                                 Introduction







10. String - Any sequence of ASCII characters terminated by
a <NULL> character, which is a byte of value 0.   Examples of
strings are:

DB   'This is a string',0
DB   1,2,3,'This is also',0

11.  TBUFF (Temporary Buffer) - The default DMA buffer
located a memory locations 80H to OFFH.

12. Vector - Any sequence of bytes which has an associated
byte count. The first byte of a vector is addressed by the
contents of a register pair (such as HL) and the length of the
vector is contained in the B register or the BC register pair.

1.8. Parameter-Passing Conventions

The libraries are very consistent in their parameter-passing
conventions. In all cases, parameters are passed to and from the
routines in registers.   If more values are required than there
are available registers, the register values are pointers to
specification blocks which contain the desired parameters (see
the FXn$xxxxx and the SORT routines).

In roost cases, the following rules apply. There will always
be exceptions to the rule, but the following statements are true
in most cases.

Uses of the HL Register Pair

1.   HL is used as a buffer pointer.   For example, HL
contains the address of the buffer used by DIRF.

2.   HL is used as a string pointer.   For example, HL
contains the address of the first byte of a string for the EVAL
routine.

3.   HL is used to contain the first operand for math
routines. For example, DIVHD divides HL by DE.

Uses of the DE Register Pair

1. DE is used to point to an FCB. For example, DE contains
the address of the FCB used by DIRP.

2.  DE is used to contain the second operand for math
routines. For example, SUBHD subtracts DE from HL.

3. DE is used to point to special blocks (buffers) used by
library routines.   For example, DE points to the Sort
Specification Block for the SORT routine.

1-7

ZCPR3: The Libraries Introduction

Uses of the BC Register Pair

1.  BC is used to contain a DU form, where B contains a disk
number (A=0) and C contains a user number.

2.  BC is used to contain the number of bytes in a vector.

Uses of the A Register

1.  A is used to contain an input flag.  For example, A
contains the selection flag used by DIRF.

2.  A is used to contain an error return code.  If the value
of this code is 0, the Zero Flag (Z) is also set, and vice-versa.
For example, A contains a TPA overflow error flag returned by the
DIRF routine.

3.  A is used to contain a character input or output from a
library routine.  For example, CIN returns a character in A and
COUT outputs a character in A.

1.9. Programs and Files

The following programs and files are referenced in and were
used to create this document:

Program or File                         Source
SYSLIB.REL, Z3LIB.REL, VLIB.REL

Libraries                        ' Echelon, Inc.
STESTxxx.ZSO Test Programs              Echelon, Inc.
ZCPR3                                   Echelon, Inc.
ZAS.COM, ZLINK.COM Assembler/Linker     Echelon, Inc.
ZDM.COM Debugger                        Echelon, Inc.
T3MASTER.COM, T3SERVER.COM

(Part of TERM III)  Echelon, Inc.
CATNOTE.COM (Part of DISCAT)            Echelon, Inc.
M80.COM, L80.COM, LIB80.COM Assembler,

Linker, and Librarian             Microsoft, Inc.
WM.COM (WbrdMaster Editor)              Micropro, Inc.
WS.COM (Wordstar Editor)                Micropro, Inc.
STARINDX.COM (Starlndex)                Micropro, Inc.

This document was prepared in its entirety on a Z-System
running ZCPR3 and ZRDOS Plus with a 48K TPA.  FCPs, lOPs, RCPs,
NDRs, and TERM III Redirectable I/O to an Aropro slave computer
(made by Ampro Computers, Inc.) were implemented.   The screen
displays in the Sample Programs appendix were generated by re-
directing console output into a file on the Acnpro.  Some of the
programs used included:

1-8




2CPR3: The Libraries                                 Introduction




Program                       Usage

WS.COM                        Editor

WM.COM                       Editor

STARINDX.COM                 Generated table of contents
and index

CATNOTE.COM                  Generated Pile Listings
appendix

T3MASTER.COM, T3SERVER.COM,

Redirectable IOP         Recorded screen displays into
file and transferred
files between computers
for Sample Programs
appendix




1-9

Introduction

ZCPR3: The Libraries

NOTES;







1-10