home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / ENTERPRS / CPM / UTILS / S / ZCNFG21.LZH / CFGLIB.LZH / CFGLIB.HLP next >
Text File  |  1992-11-03  |  9KB  |  315 lines
  1. CFGLIB INTRODUCTION
  2. PUTZFS  (PUTZFS, PUTZDU, PUTZFN) Deparse FCB to DU:FN.FT
  3. GETZFS  (FNAME) Parse a Z3 filespec into a FCB
  4. INIFCB  Initialize a File Control Block
  5. MPY16   16 bit multiply with 32 bit result
  6. PKGOFF  convert offset in Z3ENV to absolute address
  7. RADBIN  (RADBIN, RTEN1) convert ASCII in any radix to binary
  8. SDELM   see if current character is a delimiter
  9. SKSP    increment a pointer past spaces
  10. UCASE   converts char to upper case
  11. FILL    Fill n bytes of memory with a constant
  12. RJUSTIP (RJIP, NTSPCS) - Right JUStify Text In Place
  13. :INTRODUCTION TO CFGLIB
  14.  
  15. CFGLIB is an M-REL library required during linking of ZCNFG.
  16. It was built using RLIB.
  17.  
  18. A library contains two or more concatenated REL modules each
  19. of which was (in principle, at least) separately assembled.
  20. Each module has a name which is either the name of the original
  21. source file (by default) or a name assigned with the NAME assembler
  22. instruction. Such names are used only by the library manager to
  23. distinguish one complete module from the next. 
  24.  
  25. Each (named) module contains one or more Entry Points: symbols which
  26. are usually the start of a subroutine. Such symbols were declared
  27. PUBLIC in the original source. For convenience, one of the entry points
  28. may have the same name as the module. Module names are meaningless to
  29. the linker; only entry points are recognized. See the GETZFS module,
  30. whose entry point is FNAME, for a case where the two are not the same.
  31.  
  32. CFGLIB is organized by Module Name. Examples show proper calls.
  33. The command 'RLIB CFGLIB' will display Module Names and Entry points.
  34. :PUTZFS - Deparse FCB to DU:FN.FT
  35.  
  36. Translates FCB preceded by a byte containing the user number into the
  37. standard FileSpec format, DU:FN.FT, with spaces removed from FN and
  38. appended at the end of the FT field.
  39.  
  40. PUTZFS sends DU:FN.FT to a 15 byte buffer
  41. PUTZDU sends DU: to a 3-byte destination
  42. PUTZFN sends FN.FT to a 12 byte buffer
  43.  
  44. CALL WITH:
  45.     HL -> FCB+1 (FILENAME field)
  46.     DE -> destination buffer
  47. RETURN WITH:
  48.     C = number of fill spaces at buffer end
  49.     DE -> next unused buffer location
  50.     HL -> FCB+12
  51.     flags Z,NC if no problems
  52.           CY set if D or U out of range
  53.  
  54.     ext    ma2hc        ;from SYSLIB
  55.     public    putzfs,putzdu,putzfn
  56.  
  57. :GETZFS  Parse a Z3 filespec into a FCB
  58. Routine to perform parse of [DU/DIR:]FN[.FT]
  59.  
  60. The Entry for this subroutine is FNAME. It is almost the same as
  61. the FNAME routine in Z3LIB.REL. The differences: this routine
  62. 1) deposits the user number for the filespec in the address FCB-1.
  63. 2) the list of delimiters recognized is different than those used 
  64.    by the Z3LIB fname routine. See routine SDELM for the delimiters.
  65. 3) The default DU in BC is used without range testing. That is the
  66.    responsibility of the calling routine.
  67.  
  68. FNAME uses the following routines in CFGLIB:
  69.     fill,ifcb,inifcb,mpy16,pkgoff,radbin
  70.     rten1,sdelm,sksp,ucase
  71.  
  72. usage:    ext    fname
  73.     ...
  74.     ld    hl,(bufptr)        ;ascii string to parse
  75.     ld    de,fcb            ;place to parse to
  76.     ld    bc,(defdu)        ;currently logged DU
  77.     call    fname
  78.  
  79. CALL FNAME WITH:
  80.     HL -> Token to be parsed as Z3 filespec
  81.     DE -> FCB drive byte
  82.     B  =  Default Drive, (A...P = 1...16)
  83.     C  =  Default User, 0...31
  84.  
  85. RETURN WITH:
  86.     HL -> Delimiter which terminated the parse
  87.     DE    is preserved
  88.     BC =  D/U, with defaults replaced by explicit D or U
  89.     FCB drive byte, FN, FT, data fields initialized
  90.     FCB+13 =Default or declared User area (the S1 byte)
  91.     FCB-1 = Default or declared User area
  92.     NZ = Error, FCB+15 contains error flag
  93.     Z  = no error
  94.     A  = number of '?' in fn/ft. (wildcard count)
  95.  
  96. :INIFCB  Initialize a File Control Block
  97.  
  98. Two entry points are available in the INIFCB module, INIFCB and IFCB.
  99.  
  100. INIFCB initializes the FCB pointed to by DE. It initializes 32 bytes
  101. as fcb1 and fcb2. The Drive byte is not affected. This routine simply
  102. increments DE and then calls IFCB twice. See IFCB for details.
  103.  
  104. usage:    ext    inifcb
  105.     ...
  106.     call    inifcb
  107.  
  108. CALL WITH:
  109.     DE = address of the drive byte (byte 0) of an FCB
  110.  
  111. RETURN WITH:
  112.     DE = FCB+34
  113.  
  114. Other CFGLIB routines used:    fill
  115.  
  116. IFCB
  117. Initializes part of FCB whose file name field is pointed to by DE on entry.
  118. The file name and type are set to space characters; the EX, S2, RC, and the
  119. following CR (current record ) or DN (disk number) fields are set to zero.
  120. The S1 byte is set to the current user number.  On exit, DE points to the
  121. byte at offset 17 in the FCB (two bytes past the record count byte).
  122.  
  123. usage:    ext    ifcb
  124.     ...
  125.     ld    de,fcb+17    ;for fcb2 (for a Rename, for example)
  126.     call    ifcb
  127.  
  128. CALL WITH:
  129.     DE = address of the NAME field of the FCB to be initialized
  130.  
  131. RETURN WITH:
  132.     DE = <Name field address> + 16.
  133.  
  134. :MPY16   16 bit multiply with 32 bit result
  135.  
  136. This routine multiplies the 16-bit values in DE and HL and returns the
  137. 32-bit result in HLBC (HL has high 16 bits; BC has low 16 bits).
  138. Register pair AF is preserved.
  139.  
  140. usage:    ext    mpy16
  141.     ...
  142.     ld    hl,val1
  143.     ld    de,val2
  144.     call    mpy16
  145.  
  146. :PKGOFF  convert offset in Z3ENV to system module address
  147.  
  148. Calculate address of a package from Z3ENV.  On entry, E contains the
  149. offset to the address of the package in the environment.  On exit,
  150. DE points to the beginning of the package and HL points to the fifth
  151. byte (where the command table starts in the RCP and FCP modules).
  152. The zero flag is set on return if the package is not supported.
  153.  
  154. usage:    ext    pkgoff
  155.     public    z3env
  156.     ...
  157.     ld    e,offset
  158.     call    pkgoff
  159.  
  160. CALL WITH:
  161.     E = offset in the Z3 environment
  162.     Z3ENV is a label for the address of the 
  163.        ZCPR3x Environment Descriptor
  164.  
  165. RETURN WITH:
  166.     DE = Address of the environment package.
  167.  
  168. :RADBIN  convert ASCII in any radix to binary
  169.  
  170. The RADBIN module contains two entry points, RADBIN and RTEN1.
  171.  
  172. RTEN1 performs decimal conversion of the string at HL.
  173.  
  174. usage:    ext rten1
  175.     ...
  176.     call rten1    ;converts (HL) asumming a decimal number
  177.  
  178. RADBIN converts the string pointed to by HL using the radix passed in DE.
  179. If the conversion is successful, the value is returned in BC. HL points
  180. to the character that terminated the number, and A contains that
  181. character.  If an invalid character is encountered, the routine returns
  182. with the carry flag set, and HL points to the offending character.
  183.  
  184. usage:    ext radbin
  185.     ...
  186.     ld    de,13        ;for base 13
  187.     ld    hl,(bufptr)
  188.     call radbin
  189.  
  190. CALL WITH:
  191.     HL = address of an ascii string in any radix
  192.     DE = Number Base used to interpret the string
  193.          (2 for binary, 8 for Octal, etc.)
  194.  
  195. RETURN WITH:
  196.     BC = Binary value of the ASCII number represented
  197.     Carry flag set if the string contains an invalid character
  198.     
  199. Other CFGLIB routines used:    mpy16,sdelm
  200.  
  201. :SDELM   see if current character is a delimiter
  202.  
  203. This routine checks for a delimiter character pointed to by HL.
  204. It returns with the character in A and the zero flag set if it
  205. is a delimiter.  The delimiters tested for include all control
  206. characters, space, and the following characters.
  207.  
  208.     ','        ; comma
  209.     '/'        ; forward slash precedes options
  210.     ':'        ; colon
  211.     '.'        ; period
  212.     '='        ; equality sign
  213.     ';'        ; semicolon
  214.     '<'        ; left angle bracket
  215.     '>'        ; right angle bracket
  216.     '_'        ; underline
  217.  
  218. usage:    ext sdelm
  219.     ...
  220.     call sdelm
  221.     ...
  222.  
  223. CALL WITH:
  224.     HL = address of character to test
  225.  
  226. RETURN WITH:
  227.     A = the byte at HL
  228.     Z flag set means this is one of the delimiters
  229.     NZ means the character is NOT a delimiter
  230.     Other registers are preserved
  231.  
  232. :SKSP    increment a pointer past spaces
  233.     public    sksp
  234.  
  235. Subroutine to skip over spaces in the buffer pointed to by HL.  On return,
  236. the zero flag is set if we encountered the end of the line or a command
  237. separator character.
  238.  
  239. usage:    ext sksp
  240.     ...
  241.     ld hl,(bufptr)
  242.     call sksp
  243.  
  244. CALL WITH:
  245.     HL = address of a character in memory
  246.  
  247. RETURN WITH:
  248.     HL = address of next non-space character
  249.  
  250. :UCASE   converts char to upper case
  251.  
  252. Converts the  character in A to upper case.
  253.  
  254. usage:    ext ucase
  255.     ...
  256.     call ucase
  257.  
  258. CALL WITH:
  259.     A  = contains a lower case ASCII character
  260.  
  261. RETURN WITH:
  262.     A  = same character converted to upper case
  263.     All other registers are preserved
  264. :FILL    Fill n bytes of memory with a constant
  265.  
  266. Fill memory pointed to by DE with character in A for B bytes
  267.  
  268. usage:    ext    fill
  269.     ...
  270.     ld    b,10
  271.     ld    a,' '        ;fill with 10 spaces
  272.     call    fill
  273.  
  274. CALL FILL WITH
  275.     B  = number of bytes to fill
  276.     A  = value to fill with
  277.     DE = address to start filling
  278.  
  279. RETURN WITH
  280.     DE = address of next unfilled byte
  281.     The block specified has been filled with (A)
  282. :RJUSTIP - Right JUStify Text In Place
  283.  
  284. Moves left justified text to the right end of
  285. the buffer at HL and moves terminal spaces to
  286. the beginning of the buffer
  287.  
  288.     public    RJIP, NTSPCS
  289.  
  290. CALL WITH:
  291.     HL -> fixed length buffer, left justified
  292.     BC: B = field width, C = Number of spaces at end
  293. RETURN WITH:
  294.     HL preserved
  295.     BC, DE destroyed
  296.  
  297. NTSPCS (next screen) may be used to provide the calling
  298. data for this routine.
  299.  
  300.  
  301. NTSPCS - count trailing spaces in LJ field of text
  302.  
  303. Scan the field at (HL) whose length is given in BC
  304. or just C, counting trailing spaces.
  305. This routine may be used to provide input for RJIP
  306.  
  307. CALL WITH:
  308.     HL -> start of field containing text
  309.     C  =  length of the field (1...255)
  310.  
  311. RETURN WITH:
  312.     DE, HL are preserved
  313.     BC = field length in B, number of trailing spaces in C
  314.  
  315.