Date : Thu, 04 Nov 1982 15:50:44-EST (Thu)
From : Rick Conn <rconn@BRL>
Subject: SYSLIB Details
From the SYSLIB User and Reference Manual:
SYSLIB User and Reference Manual
SYSLIB -- An Integrated Library of Assembly Language
Utility Subroutines for use with the Microsoft M80 Assembler
1.0 Introduction
1.01 What is SYSLIB?
SYSLIB (SYStem LIBrary) is a collection of over 130 subrou-
tines which are designed to provide to the CP/M 8080/Z80 assembly
language programmer a set of functions upon which he can build
his programs. This library is intended to relieve the programmer
of the task of frequently "reinventing the wheel" and to provide
him with an tool environment which encourages structured
programming at the assembly language level.
Each subroutine within SYSLIB can be viewed as a reliable
"black box." The subroutines in SYSLIB are completely documented
within this 100+ page manual and the SYSLIBx.HLP files, and the
programmer is consistently provided with the following informa-
tion:
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 within SYSLIB 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. Also, as a general rule, if a
register is not returned as an output from the SYSLIB subroutine,
then its value is not affected (it has the same value when the
routine is exited as it had when the routine was called).
SYSLIB itself is a library of relocatable object modules
created in the Microsoft M80 relocatable object format. All
subroutines within SYSLIB 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, I have designed each
module 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 - Introduction Page 1
SYSLIB User and Reference Manual
1.02 What is Needed to Use SYSLIB?
You need an 8080- or Z80-based microcomputer with at least
48K bytes of contiguous memory running CP/M 2.2, the Microsoft
M80 assembler tool set (specifically, the M80 assembler and the
L80 linker), and the usual set of software development tools (an
editor and, preferably, a debugger) to use SYSLIB.
1.03 What Does SYSLIB Buy Me?
The bottom line is that, to the experienced SYSLIB program-
mer, SYSLIB has the potential of being a significant tool which
enables him to:
1. Solve his programming task quickly
-- because he spends less time writing com-
monly-used subroutines and worrying about how his regis-
ters 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 SYSLIB 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 SYSLIB is designed with structured
programming philosophy in mind; each subroutine is equi-
valent 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 SYSLIB 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 SYSLIB subroutine point of view), structured designs
that he can go back to at a later date and readily
decipher and modify
1 - Introduction Page 2
SYSLIB User and Reference Manual
4. Reduce the programming effort
-- because SYSLIB provides 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
entries not selected from the memory buffer), alphabet-
izes 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, SYSLIB brings some of the advantages of pro-
gramming in a High-Order Language, like C or Pascal, to the
assembly language programmer. It allows him to maintain the
smaller code size and greater efficiency which can be realized in
assembly language programming and simultaneously realize a re-
duced life-cycle cost (from development to fielding to post-
fielding maintenance and modification) over assembly language
programming without a SYSLIB-like tool set.
1.04 How Do I Assemble with SYSLIB?
Each example in Section 21 of this manual shows an assembly
of the sample program. I frequently use a command file, which I
call M80.SUB, to assemble my programs. This command file takes
only one parameter, the name of the file to be assembled WITHOUT
its type (MAC is assumed). Warning: The command MUST be:
SUB M80 filename
and it MUST NOT be:
SUB M80 filename.typ
If it is of the latter form, the source code will be deleted
during the assembly process! You may wish to remove the
ERA $1.BAK
command in the M80.SUB file to eliminate this problem. I only do
this for a space savings.
1 - Introduction Page 3
SYSLIB User and Reference Manual
My M80.SUB command file is:
; M80.SUB -- MACRO-80 Assembler and Linker
M80 =$1
SUB /A PLEASE ABORT IF ERROR(S) EXIST
ERA $1.BAK
ERA $1.COM
L80 /P:100,$1,A:SYSLIB/S,$1/N,/U,/E
ERA $1.REL
; ASSEMBLY COMPLETE
I run ZCPR2 instead of the CP/M 2.2 CCP, and I am always on
Drive B: doing my development work, while my editors and
assemblers (and SYSLIB.REL) are on Drive A:. Note that this is
reflected in M80.SUB, where L80 looks for A:SYSLIB for the scan.
1.05 How Do I Learn to Use SYSLIB Effectively?
This is, of course, opinion, but I feel that the best way to
learn how to use SYSLIB would involve the following steps:
1. Study the SYSLIB manual in an overview fashion,
familiarizing yourself with the functions of the subroutines
available
2. Study in some detail the sample source programs in
Section 21, 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 SYSLIB to code them
5. Apply SYSLIB to a significant program you want to
write
I am a strong advocate of writing programs in order to learn
how to program, and I feel that it is most important to (1) gain
as much familiarity with the SYSLIB routines as you can and (2)
to write programs using these routines.
1 - Introduction Page 4
SYSLIB User and Reference Manual
1.06 Who May Use SYSLIB?
SYSLIB is hereby released to the public domain. Anyone who
wishes to USE it may do so with no strings attached. The author
assumes no responsibility or liability for the use of SYSLIB. It
is copyrighted by the author, Richard Conn, who has sole rights
to it. SYSLIB and its associated documentation may be sold by
itself or as an independent part of a package of programs only
with the express, written consent of the author. The author,
however, supports the use of SYSLIB by commercial software devel-
opers, and places no restriction on the sale of programs which
are BASED on SYSLIB and use routines contained within SYSLIB to
perform their major functions.
I hope you enjoy using SYSLIB and find it to be as useful a
tool as I do.
Richard Conn
1 - Introduction Page 5
SYSLIB User and Reference Manual
SYSLIB -- An Integrated Library of Assembly Language
Utility Subroutines for use with the Microsoft M80 Assembler
Functional Listing of SYSLIB Routines
2.0 Directory Manipulation Routines - 6
DIRF, DIRFS: 7 DBUFFER: 8 DPARAMS: 9
DFREE: 9 FSIZE: 10 DIRLOAD, DIRSLOAD: 11
DIRALPHA: 12 DIRSEL: 12 DIRPACK: 13 DIRNPACK: 14
3.0 Numeric String Evaluation Routines - 15
EVAL: 15 EVAL16: 16 EVAL10: 16 EVAL8: 17 EVAL2: 17
4.0 Byte-Oriented File Input/Output Routines (0-n-3) - 18
FIn$OPEN: 19 FOn$OPEN: 20 FIn$CLOSE: 20
FOn$CLOSE: 20 Fn$GET: 21 Fn$PUT: 21
5.0 CP/M File Input/Output Routines - 23
F$OPEN: 23 F$MOPEN: 24 F$CLOSE: 24 F$MAKE: 25
F$DELETE: 25 F$RENAME: 26 F$EXIST: 26 F$READ: 27
F$WRITE: 27
6.0 File Name String Parser and FCB Init - 28
FNAME: 28 INITFCB: 29
7.0 Input Line Editors - 30
BBLINE: 31 BLINE: 31 INLINE: 32
8.0 String Output Routines - 34
PRINT, LPRINT: 34 PSTR, LPSTR: 34
9.0 Numeric Output Routines - 35
PHL4HC, LHL4HC: 35 MHL4HC: 35 PHL5DC, LHL5DC: 36
MHL5DC: 36 PHLDC, LHLDC: 36 MHLDC: 37
PA2HC, LA2HC: 37 MA2HC: 37 PA3DC, LA3DC: 38
MA3DC: 38 PADC, LADC: 38 MADC: 39
10.0 String and Value Comparison Routines - 40
COMPHD: 40 COMPB, COMPBC: 40 SCANNER: 40 INSTR: 41
11.0 Character-Oriented Input/Output Routines - 42
CRLF, LCRLF: 42 CONDIN: 42 CST: 43
CIN, RIN: 43 COUT, LOUT, POUT: 43
CCOUT, CLOUT, CPOUT: 44
12.0 Math Routines - 45
ADDHD: 45 SUBHD: 45 MULHD: 46 DIVHD: 46
NEGH: 46 CMPH: 46 ROTLH: 47 ROTRH: 47
SHFTLH: 47 SHFTRH: 48 ANDHD: 48 ORHD: 48
XORHD: 48
13.0 CRC Routines - 49
CRCCLR, CRC1CLR: 50 CRCUPD, CRC1UPD: 50
CRCDONE, CRC1DONE: 50 CRCK, CRC1K: 51
14.0 Random Number Generator Routines - 52
RNDINIT: 52 RNDSEED: 52 RND: 53
15.0 User/Disk Manipulation Routines - 54
PUTUD: 54 GETUD: 55 LOGUD: 55 RETUD: 55
16.0 Sort Routines - 56
SSBINIT: 57 SORT: 57
17.0 ZCPR2 Feature-Specific Routines - 58
ZINIMC: 58 ZINIEXT: 59 ZCPRSET: 59 ZCPRQ: 60
ZMCPTR: 61 ZPFIND: 61 ZFSTAT: 62
18.0 ZCPR2-Specific Named Directory Routines - 63
ZFNINIT: 64 ZDNFIND: 64 ZFNAME: 65
19.0 Miscellaneous Routines - 66
BDOS: 67 BIOS: 67 CAPS: 68
CAPSTR: 68 CATH: 69 CODEND: 69
EN: 69 FILLB, FILLBC, HFILB, HFILBC: 70
MOVEB, MOVEBC, HMOVB, HMOVBC: 71 PAUSE: 71