CP/M/CPM_CDROM.iso/enterprs/cpm/utils/f/rlib12.lbr/LIBLIB.HZP/LIBLIB.HLP

Text File | 1991-10-19 | 9.5 KB | 311 lines

LIBLIB INTRODUCTION
FILL    Fill n bytes of memory with a constant
GETBIT  Retrieve the next n bits from a REL source
GETZFS  Parse a Z3 filespec into a FCB
INIFCB  Initialize a File Control Block
MPY16   16 bit multiply with 32 bit result
PKGOFF  convert offset in Z3ENV to absolute address
RADBIN  convert ASCII in any radix to binary
SDELM   see if current character is a delimiter
SKSP    increment a pointer past spaces
UCASE   converts char to upper case
:INTRODUCTION TO LIBLIB

LIBLIB is a M-REL library required during linking of the RLIB
library manager program. It was built using RLIB.

A library contains two or more concatenated REL modules each
of which was (in principle, at least) separately assembled.
Each module has a name which is either the name of the original
source file (by default) or a name assigned with the NAME assembler
instruction. Such names are used only by the library manager to
distinguish one complete module from the next.

Each (named) module contains one or more Entry Points: symbols which
are usually the start of a subroutine. Such symbols were declared
PUBLIC in the original source. For convenience, one of the entry points
may have the same name as the module. Module names are meaningless to
the linker; only entry points are recognized. See the GETZFS module,
whose entry point is FNAME, for a case where the two are not the same.

LIBLIB is organized by Module Name. Examples show proper calls.
The command 'RLIB LIBLIB' will display Module Names and Entry points.
:FILL    Fill n bytes of memory with a constant

Fill memory pointed to by DE with character in A for B bytes

usage:    ext    fill
    ...
    ld    b,10
    ld    a,' '        ;fill with 10 spaces
    call    fill

CALL FILL WITH
    B  = number of bytes to fill
    A  = value to fill with
    DE = address to start filling

RETURN WITH
    DE = address of next unfilled byte
    The block specified has been filled with (A)

:GETBIT  Retrieve the next n bits from a REL source
Routines to get B bits from M-REL bit stream

The GETBIT module contains two entry points, GETBIT, and INIBIT.
INIBIT is used before the first call to GETBIT to provide initial
data for processing the first byte of a REL file. Each new REL file
requires such initialization before GETBIT is called.

usage:    ext    getbit,inibit
    <open the file, read first buffer-full>
    ...
    ld    a,(hl)        ;hl -> first byte of file
    ld    hl,getrel
    call    inibit        ;see INIBIT for parameters
    ...
    ld    b,3        ;to get the next 3 bits
    call    getbit

CALL GETBIT WITH
    B  = number of bits to get

RETURN WITH
    A  = contains the B bits
    HL = current value of (bitcnt)
    BC munched
    DE is unused, depending on the GETREL routine.

(bitcnt) is an internally stored word variable. The high byte
contains the remaining bits yet to be extracted from the REL
bit stream. The low byte contains the number of bits left to
extract before a new byte is requested (via GETREL). During
initialization with INIBIT, the first byte of the rel file is
stored in the high byte and the low byte is set to 8.

INIBIT initializes (bitcnt) and provides the address of the routine
(GETREL, for example) that will be called by GETBIT when it needs
another byte from the REL file buffer.

usage:    see GETBIT

CALL INIBIT WITH
    HL = Address of the GETREL routine (see below)
    A  = first byte from the rel file
RETURN WITH
    H  = byte from which bits will be extracted (A)
    L  = bits remaining in the byte (8)

GETREL is a user written routine in the calling program which, when
called, passes the next byte from the .REL file in A. File access
and file buffer maintenance are GETREL responsibilities. When End
of File is reached, it is an error condition which GETREL must
handle. (An M-REL EOF normally occurs first and stops file processing)
The BC register pair must be preserved across calls to GETREL.
:GETZFS  Parse a Z3 filespec into a FCB
Routine to perform parse of [DU/DIR:]FN[.FT]

The Entry for this subroutine is FNAME. It is almost the same as
the FNAME routine in Z3LIB.REL. The difference: this routine
deposits the user number for the filespec in the address FCB-1.
In addition, the list of delimiters recognized is different than
those used by the Z3LIB fname routine. See routine SDELM for the
delimiter list.

FNAME uses the following routines in LIBLIB:
    fill,ifcb,inifcb,mpy16,pkgoff,radbin
    rten1,sdelm,sksp,ucase

usage:    ext    fname
    ...
    ld    hl,(bufptr)        ;ascii string to parse
    ld    de,fcb            ;place to parse to
    ld    bc,(defdu)        ;currently logged DU
    call    fname

CALL FNAME WITH:
    HL -> Token to be parsed as Z3 filespec
    DE -> FCB drive byte
    B  =  Default Drive, (A...P = 1...16)
    C  =  Default User, 0...31

RETURN WITH:
    HL -> Delimiter which terminated the parse
    DE    is preserved
    BC =  D/U, with defaults replaced by explicit D or U
    FCB drive byte, FN, FT, data fields initialized
    FCB+13 =Default or declared User area (the S1 byte)
    FCB-1 = Default or declared User area
    NZ = Error, FCB+15 contains error flag
    Z  = no error
    A  = number of '?' in fn/ft. (wildcard count)

:INIFCB  Initialize a File Control Block

Two entry points are available in the INIFCB module, INIFCB and IFCB.

INIFCB initializes the FCB pointed to by DE. It initializes 32 bytes
as fcb1 and fcb2. The Drive byte is not affected. This routine simply
increments DE and then calls IFCB twice. See IFCB for details.

usage:    ext    inifcb
    ...
    call    inifcb

CALL WITH:
    DE = address of the drive byte (byte 0) of an FCB

RETURN WITH:
    DE = FCB+34

Other LIBLIB routines used:    fill

IFCB
Initializes part of FCB whose file name field is pointed to by DE on entry.
The file name and type are set to space characters; the EX, S2, RC, and the
following CR (current record ) or DN (disk number) fields are set to zero.
The S1 byte is set to the current user number.  On exit, DE points to the
byte at offset 17 in the FCB (two bytes past the record count byte).

usage:    ext    ifcb
    ...
    ld    de,fcb+17    ;for fcb2 (for a Rename, for example)
    call    ifcb

CALL WITH:
    DE = address of the NAME field of the FCB to be initialized

RETURN WITH:
    DE = <Name field address> + 16.

:MPY16   16 bit multiply with 32 bit result

This routine multiplies the 16-bit values in DE and HL and returns the
32-bit result in HLBC (HL has high 16 bits; BC has low 16 bits).
Register pair AF is preserved.

usage:    ext    mpy16
    ...
    ld    hl,val1
    ld    de,val2
    call    mpy16

:PKGOFF  convert offset in Z3ENV to system module address

Calculate address of a package from Z3ENV.  On entry, E contains the
offset to the address of the package in the environment.  On exit,
DE points to the beginning of the package and HL points to the fifth
byte (where the command table starts in the RCP and FCP modules).
The zero flag is set on return if the package is not supported.

usage:    ext    pkgoff
    public    z3env
    ...
    ld    e,offset
    call    pkgoff

CALL WITH:
    E = offset in the Z3 environment
    Z3ENV is a label for the address of the
       ZCPR3x Environment Descriptor

RETURN WITH:
    DE = Address of the environment package.

:RADBIN  convert ASCII in any radix to binary

The RADBIN module contains two entry points, RADBIN and RTEN1.

RTEN1 performs decimal conversion of the string at HL.

usage:    ext rten1
    ...
    call rten1    ;converts (HL) asumming a decimal number

RADBIN converts the string pointed to by HL using the radix passed in DE.
If the conversion is successful, the value is returned in BC. HL points
to the character that terminated the number, and A contains that
character.  If an invalid character is encountered, the routine returns
with the carry flag set, and HL points to the offending character.

usage:    ext radbin
    ...
    ld    de,13        ;for base 13
    ld    hl,(bufptr)
    call radbin

CALL WITH:
    HL = address of an ascii string in any radix
    DE = Number Base used to interpret the string
         (2 for binary, 8 for Octal, etc.)

RETURN WITH:
    BC = Binary value of the ASCII number represented
    Carry flag set if the string contains an invalid character

Other LIBLIB routines used:    mpy16,sdelm

:SDELM   see if current character is a delimiter

This routine checks for a delimiter character pointed to by HL.
It returns with the character in A and the zero flag set if it
is a delimiter.  The delimiters tested for include all control
characters, space, and the following characters.

    ','        ; comma
    '/'        ; indicates lib srch (22/08/88)
    ':'        ; colon
    '.'        ; period
    '='        ; equality sign
    ';'        ; semicolon
    '<'        ; left angle bracket
    '>'        ; right angle bracket
    '_'        ; underline

usage:    ext sdelm
    ...
    call sdelm
    ...

CALL WITH:
    HL = address of character to test

RETURN WITH:
    A = the byte at HL
    Z flag set means this is one of the delimiters
    NZ means the character is NOT a delimiter
    Other registers are preserved

:SKSP    increment a pointer past spaces
    public    sksp

Subroutine to skip over spaces in the buffer pointed to by HL.  On return,
the zero flag is set if we encountered the end of the line or a command
separator character.

usage:    ext sksp
    ...
    ld hl,(bufptr)
    call sksp

CALL WITH:
    HL = address of a character in memory

RETURN WITH:
    HL = address of next non-space character

:UCASE   converts char to upper case

Converts the  character in A to upper case.

usage:    ext ucase
    ...
    call ucase

CALL WITH:
    A  = contains a lower case ASCII character

RETURN WITH:
    A  = same character converted to upper case
    All other registers are preserved