ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/ZSYS/ZSYSARK/Z3HLP03.ARK/SYSLIB42.LBR/SYSLIB0.HZP/SYSLIB0.HLP

Text File | 1990-03-23 | 13KB | 319 lines

 Introduction to SYSLIB 4

 Comments on Software Engineering 

 Library Definitions and Terms 

 Parameter-Passing Conventions 

 Overview of SYSLIB 4 Routines 
:                
 Introduction to SYSLIB 4 

SYSLIB 4 is an integrated tool set which is designed to assist
you, the assembly language programmer, in writing programs.  It
is intended to place you at a higher level of abstraction and
allow you to concentrate on the problem at hand without having
to concern yourself with the low-level implementation details
of the operating system interface, input/output, text parsing
and evaluation, math, and sorting.

To illustrate this point, consider an assembly language program
which needs to access a disk directory, then display a sorted
list of file names.  Without SYSLIB 4 or similar library, you
would have to write a relatively sophisticated body to code to
access the directory, load it in memory, sort, and display it.

SYSLIB 4, however, provides you with a "toolbox" of routines to
call on to perform some of the more tedious functions.  One of
these tools, DIRF, loads the elements of a disk directory which
match a file spec into a memory buffer for you.


But, more than just providing a set of tools, SYSLIB 4 was
designed with structured programming and software engineering
in mind.  The basic goal in software design is that the
programs meet the stated requirements.  In applying software
engineering, we want more than just this.  Among other things,
we want the program to be:

          o Modifiable             o Efficient
          o Reliable               o Understandable

SYSLIB 4 offers a significant set of facilities which can help
to achieve these goals.

:           
 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 Modifiability - 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.  Modifiability - Software should be easy to change, and
software should be designed with later change in mind.

   2.  Efficiency - The software system should use 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.


SYSLIB 4 attempts to help you achieve the goals of Software
Engineering by applying these principles:

   1.  Abstraction and Information Hiding - Unnecessary detail
is hidden from you.  For example, the DIRF routine loads the
contents of a disk directory into a memory buffer.  How this
load is done is hidden -- all you need to know is that the load
was done and you have a vector of directory entries.

   2.  Modularity - SYSLIB 4 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 - SYSLIB 4 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
SYSLIB 4 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 needed.

   6.  Confirmability - A program written using SYSLIB 4
modules can be readily decomposed for incremental testing.

:        
 Definitions and Terms 

Some terms are used frequently in the SYSLIB 4 documentation.
These terms are defined below.

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

    BUFFER:    DEFS    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 files on a disk.  A directory
entry contains the name of a file, the User number it resides
in, the file size, and where the file is located on the disk.
The information loaded by SYSLIB directory routines does not
include file location information, but does include every-
thing else.  In another sense, the term directory is used to
refer to a particular disk and user area (such as A4 or B31).

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

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

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

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

:             
 Parameter-Passing Conventions 

SYSLIB 4 is very consistent in its parameter-passing conven-
tions.  In all cases, parameters are passed to and from SYSLIB
4 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 nearly all
cases, the following register usage rules apply:

The HL Register Pair is used --

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

   2. as a string pointer; for example, HL points to the first
    byte of a string for the EVAL routine

   3. to hold the first operand for math routines; for example,
    DIVHD divides HL by DE


The DE Register Pair is used --

   1. to point to an FCB; for example, DE contains the address
    of the FCB used by DIRF

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

   3. to point to special blocks (buffers) used by SYSLIB 4
    routines; for example, DE points to the Sort
    Specification Block for the SORT routine

The BC Register Pair is used to contain a DU form, where B
    hold a Disk Number (A=0) and C hold a User Number


The A Register is used to --

   1. contain an Input Flag; for example, A contains the
    selection flag used by DIRF

   2. 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. contain a character input or output from a a SYSLIB 4
    routine; for example, CIN returns a character in A and
    COUT outputs a character in A

:           
 Overview of SYSLIB 4 Routines 

SYSLIB 4 contains many routines grouped into the following
functional areas:

   1. Directory Manipulation Routines.  These routines deal
    with directory access.  The entries of a disk direc-
    tory can be loaded into a memory buffer, selected
    against an FCB, sorted, and manipulated.

   2. Numeric String Evaluation Routines.  These routines
    convert character strings into 16-bit binary values.
    Strings like those below are processed:

    DEFB    '123',0        ; value is 123 decimal
    DEFB    '5AH',0        ; value is 5A hexadecimal
    DEFB    '110B',0    ; value is 110 binary
    DEFB    '77Q',0        ; value is 77 octal


   3. Byte-Oriented File Input/Output Routines.  These routines
    support input and output to and from files on the basis
    of a byte at a time.  FX$GET, for example, returns the
    next byte from the current file in A.

   4. CP/M File Input/Output Routines.  These routines support
    input and output to and from files on the basis of a
    128-byte block at a time.  Provisions for deleting
    files, renaming files, and computing file sizes also
    exist.

   5. User/Disk Manipulation Routines.  These routines allow
    the program to find out what disk and user area it is
    in and to move between directories.


   6. File Name String Parser.  This routine is used to convert
    a file name text string into an acceptable form and
    place it into an FCB.  For example, the following con-
    version can be done:

    DEFB    'MYFILE.TXT',0        ; string

    DEFB    0            ; ..converted to
    DEFB    'MYFILE  '
    DEFB    'TXT'
    DEFS    24

   7. Input Line Editors.  These routines accept user input
    with editing and return a pointer to the first byte of
    user input in string form (terminated by a binary 0).


   8. String Output Routines.  These routines send strings to
    various devices.  Routines are provided to send strings
    of characters to the console or printer with or without
    control-character processing.

   9. Numeric Output Routines.  These routines convert binary
    values to character sequences and output them to
    various devices.  Output to the console and printer is
    provided, and the output is either in the form of
    decimal or hexadecimal numbers.

   10. String and Value Comparison Routines.  These routines
    provide various comparison functions for both strings
    and numbers.  One string may be compared against
    another string or a substring of another string.  Two
    16-bit numbers can be compared.


   11. Character-Oriented Input/Output Routines.  These
    routines provide input and output services on a
    character-for-character basis to a variety of devices.
    Output to the console and the printer is provided.
    Also, device status, such as console input status,
    routines are available.

   12. Math Routines.  These routines perform mathematical
    calculations on 16-bit quantities.  Add, subtract,
    multiply, divide, rotate, shift, logical AND, logical
    OR, and logical XOR are some of the functions provided.

   13. CRC Routines.  These routines support computation of
    Cyclic Redundancy Check values for byte streams.  A
    number of different CRC calculation routines are
    available for different CRC polynomials.


   14. Random Number Generator Routines.  These routines
    implement a pseudo-random number generator which
    returns an 8-bit value when called.  The seed value for
    this generator may be fed to it, thereby generating the
    same sequence for each given seed, or it may be
    selected randomly.

   15. Sort Routines.  These routines provide a fast, general-
    purpose in-memory sort capability.  The sort algorithm
    is very efficient (a Shell Sort), and may be performed
    using element pointers or not using pointers (pointers
    cost more memory but speed up the sort even further).


   16. Capitalization and Character Test/Skip Routines.  These
    routines are useful for text parsing.  A variety of
    evaluation routines are provided to determine the type
    of character being dealt with (such as alphabetic,
    numeric, hexadecimal, space, punctuation, etc).  Both
    string and individual character capitalization capa-
    bilities are also provided.

   17. Memory Allocation Routines.  These routines provide a
    dynamic memory allocation mechanism that constantly
    checks for TPA overflow.  After defining the bounds of
    a memory buffer, requests for space from this area may
    be issued on a byte-for-byte basis.