CP/M/CPM_CDROM.iso/jsage/zsus/z3help/c.lbr/CFGLIB.HZP/CFGLIB.HLP

Text File | 1991-11-18 | 9.0 KB | 313 lines

CFGLIB INTRODUCTION
PUTZFS  (PUTZFS, PUTZDU, PUTZFN) Deparse FCB to DU:FN.FT
GETZFS  (FNAME) 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  (RADBIN, RTEN1) 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
FILL    Fill n bytes of memory with a constant
RJUSTIP (RJIP, NTSPCS) - Right JUStify Text In Place
:INTRODUCTION TO CFGLIB

CFGLIB is an M-REL library required during linking of ZCNFG.
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.

CFGLIB is organized by Module Name. Examples show proper calls.
The command 'RLIB CFGLIB' will display Module Names and Entry points.
:PUTZFS - Deparse FCB to DU:FN.FT

Translates FCB preceded by a byte containing the user number into the
standard FileSpec format, DU:FN.FT, with spaces removed from FN and
appended at the end of the FT field.

PUTZFS sends DU:FN.FT to a 15 byte buffer
PUTZDU sends DU: to a 3-byte destination
PUTZFN sends FN.FT to a 12 byte buffer

CALL WITH:
    HL -> FCB+1 (FILENAME field)
    DE -> destination buffer
RETURN WITH:
    A destroyed, B = 0
    C = number of fill spaces at buffer end
    DE -> next unused buffer location
    HL -> FCB+12

    ext    ma2hc        ;from SYSLIB
    public    putzfs,putzdu,putzfn

: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 CFGLIB:
    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 CFGLIB 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 CFGLIB 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
    '/'        ; forward slash precedes options
    ':'        ; 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
: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)
:RJUSTIP - Right JUStify Text In Place

Moves left justified text to the right end of
the buffer at HL and moves terminal spaces to
the beginning of the buffer

    public    RJIP, NTSPCS

CALL WITH:
    HL -> fixed length buffer, left justified
    BC: B = field width, C = Number of spaces at end
RETURN WITH:
    HL preserved
    BC, DE destroyed

NTSPCS (next screen) may be used to provide the calling
data for this routine.


NTSPCS - count trailing spaces in LJ field of text

Scan the field at (HL) whose length is given in BC
or just C, counting trailing spaces.
This routine may be used to provide input for RJIP

CALL WITH:
    HL -> start of field containing text
    C  =  length of the field (1...255)

RETURN WITH:
    DE, HL are preserved
    BC = field length in B, number of trailing spaces in C