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 / ZSYS / ZSYSARK / Z3HLP03.ARK / SYSLIB42.LBR / SYSLIB4.HZP / SYSLIB4.HLP
Text File  |  1990-03-23  |  13KB  |  338 lines
  1.   Introduction 
  2.  Close a File               - F$CLOSE
  3.  Delete a File              - F$DELETE
  4.  Test File Existence        - F$EXIST
  5.  Create a File              - F$MAKE
  6.  Open a File                - F$OPEN, F$MOPEN
  7.  Append to a File           - F$APPEND, F$APPL
  8.   Usage Example for F$APPEND and F$APPL
  9.  Read Block from File       - F$READ
  10.  Rename a File              - F$RENAME
  11.  Compute File Size          - F$SIZE
  12.  Write a Block to a File    - F$WRITE
  13.  Return Random Record Num   - GETRR, GETRR1
  14.  Return File Size           - GETFS, GETFS1
  15.  Get File Attributes        - GFA
  16.  Read File Block Random     - R$READ
  17.  Write File Block Random    - R$WRITE
  18.  Set/Clear File Attributes  - SCFA, SFA
  19.   Library (LBR) File Manipulation
  20. :            CP/M File Input/Output Routines 
  21.  
  22. The following routines are general-purpose file I/O routines
  23. which interface to CP/M through the Entry Point at location 5.
  24. They preserve BC, DE, and HL, and return with the standard CP/M
  25. error codes for the corresponding routines.  These routines are:
  26.  
  27.      F$CLOSE   F$DELETE  F$EXIST   F$MAKE    F$OPEN
  28.      F$MOPEN   F$READ    F$RENAME  F$SIZE    F$WRITE
  29.      R$READ    R$WRITE
  30.  
  31. The routines GFA, SCFA, and SFA all deal with getting (GFA) and
  32. setting (SCFA and SFA) the attributes of files whose FCBs are
  33. addressed by DE.
  34.  
  35. The following files allow you to append to the end of an existing
  36. file conveniently.  They return unique error codes.
  37.  
  38.      F$APPEND  F$APPL    GETRR     GETRR1    GETFS     GETFS1
  39.  
  40. :F$CLOSE - Close a File
  41.  
  42.   ENTER: DE = Points to FCB for desired file
  43.   EXIT :  A = 0, Zero Flag Set (Z) if Close Ok
  44.               A <> 0, Zero Clear (NZ) if Error in Closing
  45.   USES : AF
  46.  
  47.  Usage:  This routine is used to close a specified file in the
  48.   current Drive/User area.
  49.  
  50. :F$DELETE - Delete a File
  51.  
  52.   ENTER: DE = Points to FCB for file to delete
  53.   EXIT :  A = 0, Zero Flag Set (Z) if Delete Ok
  54.               A <> 0, Zero Clear (NZ) if File Not Found
  55.   USES : AF
  56.  
  57.  Usage:  This routine is used to delete a specified file from
  58.   current Drive/User area.
  59.  
  60. :F$EXIST - Test of Existence of a File
  61.  
  62.   ENTER: DE = Address of an FCB for file to test
  63.   EXIT :  A <> 0, Zero Flag Clear (NZ) if File Exists
  64.               A = 0, Zero Flag Set (Z) if File Not Found
  65.   USES : AF
  66.  
  67.  Usage:  This routine tests for the presence of a specified file
  68.   in the current disk/user area.  Status is returned showing the
  69.   results of the search.
  70.  
  71. :F$MAKE - Create a File
  72.  
  73.   ENTER: DE = Points to an FCB for the desired file
  74.   EXIT :  A = Directory Code [0..3] if File Created Ok
  75.               A = 0FFH if No Directory Space Available
  76.   USES : AF
  77.  
  78.  Usage:  This routine is used to Create (Make) a specified file
  79.   in the current Drive/User Area.
  80.  
  81. :F$OPEN - Open a File
  82.  
  83.   ENTER: DE = Pointer to FCB for desired file
  84.   EXIT :  A = 0, Zero Flag Set (Z) if File Opened Ok
  85.               A <> 0, Zero Flag Clear (NZ) if NOT Opened
  86.   USES : AF
  87.  
  88.  Usage:  This routine is used to Open a specified file in the
  89.   Current Drive/User Area.
  90.  
  91. F$MOPEN - Open a File with Creation
  92.  
  93.   ENTER: DE = Pointer to FCB for file to Open
  94.   EXIT :  A = 0, Zero Flag Set (Z) if File Opened Ok
  95.               A <> 0, Zero Clear (NZ) if No Dir Space (Error)
  96.   USES : AF
  97.  
  98.  Usage:  This routine is used to Open a specified file.  If the
  99.   file is not found, F$MOPEN tries to create one.  NOTE: This
  100.   routine should NOT be used as a substitute for existence
  101.   testing with F$EXIST.
  102.  
  103. :F$APPEND - Append to a File
  104.  
  105.   ENTER: DE = Pointer to an FCB for the Desired File
  106.   EXIT :  A = 0, Zero Flag Set (Z) if File Opened Ok
  107.               A = Error Code, Zero Flag Clear (NZ) if Error as:
  108.                    1    --> File Not Found
  109.                    2    --> File is Full (no more room)
  110.                    3    --> File Found but Empty
  111.   USES : AF
  112.   SIDE EFFECTS: Current DMA buffer has last file record if A=0
  113.  
  114.  Usage:  This routine is used to Open a file for appending.  The
  115.   results of the operation are reported.  Various  error condi-
  116.   tions can occur, and are reported.  Error 3 is a note that the
  117.   file is empty and is not fatal (processing can continue).
  118.  
  119.   If the APPEND is successful, the current DMA buffer contains
  120.   the last record in the file.  The next sequential write will
  121.   write to the record after the last one in the file.  (See
  122.   F$APPL which starts writing on the last record of the file).
  123.  
  124. F$APPL
  125.  
  126.   ENTER: DE = pointer to FCB for desired file
  127.   EXIT :  A = 0, Zero Flag Set (Z) if File Opened Ok
  128.               A = Error Code, Zero Flag Clear (NZ) if Error
  129.                    1    --> File Not Found
  130.                    2    --> File is Full (no more room)
  131.                    3    --> File Found but Empty
  132.   USES : AF
  133.   SIDE EFFECTS: Current DMA buffer has last record if A=0
  134.  
  135.  Usage:  This routine is used to Open a file for appending.  The
  136.   results of the operation are reported.  Various  error condi-
  137.   tions can occur, and are reported.  Error 3 is a note that the
  138.   file is empty and is not fatal (processing can continue).
  139.  
  140.   If the APPL is successful, the last record in the file is in
  141.   the current DMA buffer.  The next sequential write (F$WRITE)
  142.   will write back over the last record in the file.  
  143.  
  144. :                        Append Use 
  145.  
  146. The following code segment illustrates the intended usage for
  147. the two file append routines.
  148.  
  149. With F$APPEND:                  With F$APPL:
  150.  
  151.      ...                             ...
  152.      LD    DE,FCB                    LD    DE,FCB
  153.      CALL  F$APPEND                  CALL  F$APPL
  154.      ...                             ...
  155.      <Prepare next record>           <Modify last record>
  156.      ...                             ...
  157.      LD    DE,FCB                    LD    DE,FCB
  158.      CALL  F$WRITE   ;after last     CALL  F$WRITE   ;on last
  159.      ...                             ...
  160.      LD    DE,FCB                    LD    DE,FCB
  161.      CALL  F$CLOSE   ;close file     CALL  F$CLOSE   ;close
  162.      ...                             ...
  163.  
  164. :F$READ - Read a Block from a File
  165.  
  166.   ENTER: DE = Pointer to FCB for desired file
  167.   EXIT : A = 0, Zero Flag Set (Z) if Read Ok
  168.              A = Error Code, Zero Flag Clear (NZ) if Error
  169.                    1 --> Read past end of file
  170.                    2 --> Reading unwritten data in random access
  171.  
  172.  Usage:  This routine is used to Read the next block (128 bytes)
  173.   of data from an Open file in the Current Drive/User Area.  The
  174.   data is loaded into the current DMA buffer.
  175.  
  176. :F$RENAME - Rename a File
  177.  
  178.   ENTER: HL = Pointer to first 12 bytes of new FCB
  179.          DE = Pointer to first 12 bytes of old FCB
  180.   EXIT :  A <> 0, Zero Flag Clear (NZ) if Rename Ok
  181.               A = 0, Zero Flag Set (Z) if File Not Found Error
  182.   USES : AF
  183.  
  184.  Usage:  This routine is used to rename a file in the current
  185.   Drive/User Area.  Only the FN and FT fields are significant in
  186.   the FCBs, so the rest of the FCB need not be present for this
  187.   function to work.
  188.  
  189. :F$SIZE - Compute File Size
  190.  
  191.   ENTER: DE = Pointer to the 1st 12 bytes of an FCB
  192.   EXIT : HL = File Size in kiloBytes
  193.   USES : AF
  194.  
  195.  Usage:  This routine is used to obtain the computed size of a
  196.   file (in K) based on its record count.  This routine gives the
  197.   file size correct to the next 1K, but does not take into
  198.   account the grouping factor.
  199.  
  200. :F$WRITE - Write a Block to a File
  201.  
  202.   ENTER: DE = Pointer to FCB for open file
  203.   EXIT :  A = 0, Zero Flag Set (Z) if Write Ok
  204.               A = Error Code, Zero Clear (NZ) if Error
  205.                    1    --> Error in extending file
  206.                    2    --> End of disk data
  207.                    0FFH --> No more directory space
  208.   USES : AF
  209.  
  210.  Usage:  This routine is used to Write the next 128 byte block
  211.   of data from the current DMA Buffer to a specified open file in
  212.   the Current Drive/User Area.
  213.  
  214. :GETRR, GETRR1 - Get Random Record Number
  215.  
  216.   ENTER: DE = pointer to FCB
  217.   EXIT : HL = Random Record Number
  218.       A = 0, Zero Flag Set (Z) if No Error
  219.               A <> 0, Zero Flag Clear (NZ) ifRandom Record Overflow
  220.             (value in A is Error Code)
  221.   USES : AF,HL
  222.  
  223.  Usage:  Return the random record number of the last record read
  224.   or written sequentially from the specified file.  These routines
  225.   are convenient in determining the current position in a file.
  226.  
  227.   NOTE:  GETRR does not affect the random record number field of
  228.   the FCB and is larger in size.  GETRR1 is smaller and DOES
  229.   affect the random record number field of the FCB.
  230.  
  231. :GETFS, GETFS1 - Get File Size in Records
  232.  
  233.   ENTER: DE = pointer to FCB
  234.   EXIT : HL = Number of Records in File (File Size)
  235.       A = 0, Zero Flag Set (Z) if No Error
  236.           A <> 0, Zero Flag Clear (NZ) if Random Record Overflow
  237.             (Value in A is Error Code)
  238.   USES : AF,HL
  239.  
  240.  Usage:  Return the file size (in terms of records) of the file
  241.   whose FCB is pointed to by DE.  These routines are convenient
  242.   in determining the number of records in a file.
  243.  
  244.   NOTE:  GETFS does not affect the random record number field
  245.   of the FCB and is larger in size.  GETFS1 is smaller and
  246.   affects the random record number field of the FCB.
  247.  
  248. :GFA - Get File Attributes
  249.  
  250.   ENTER: DE = pointer to FCB
  251.   EXIT :  A = Attribute Code
  252.         A0 = Read-Only Attr (1 = R/O, 0 = R/W)
  253.         A7 = SYStem Attr    (1 = SYS, 0 = Dir)
  254.   USES : AF
  255.  
  256.  Usage:  This routine is used to return the attributes of the
  257.   file whose FCB is pointed to by DE.  On return, A contains a
  258.   code indicating the R/O and SYS attributes, where the 8th bit
  259.   of A (A7) is 1 if the file is a SYStem file and 0 if the file
  260.   is a DIRectory (Non-SYStem) file and the 1st bit of A (A0) is
  261.   1 if the file is Read/Only and 0 if the file is Read/Write.
  262.  
  263.   As a side effect, the MSBs of all bytes in the File Name and
  264.   File Type fields of the original FCB (bytes 1-11, where byte 0
  265.   is first) are set equal to the MSBs of the corresponding
  266.   directory entry.
  267.  
  268. :R$READ - Random Read a Block from a File
  269.  
  270.   ENTER: DE = Pointer to FCB
  271.          HL = Random Record Number
  272.   EXIT :  A = 0, Zero Flag Set (Z) if NO Error
  273.               A = Error Code, Zero Clear (NZ) if Error where:
  274.         1 --> Attempt to Read Unwritten Record
  275.         3 --> CP/M could not Close Current Extent
  276.         4 --> Attempt to Read Unwritten Extent
  277.         6 --> Attempt to Read Beyond End of Disk
  278.   USES : AF
  279.  
  280.  Usage:  This routine is used to read a block from the specified
  281.   file in Random mode.  It is assumed that the file has already
  282.   been opened by the F$OPEN routine or equivalent.
  283.  
  284. :R$WRITE - Random Write of a Block to a File
  285.  
  286.   ENTER: DE = Pointer to FCB
  287.      HL = Random Record Number
  288.   EXIT :  A = 0, Zero Flag Set (Z) if No Error
  289.           A = Error Code, Zero Flag Clear (NZ) if Error as:
  290.         0 --> No Error (Z Flag Set)
  291.         1 --> Attempt to Read Unwritten Record
  292.         3 --> CP/M could not Close Current Extent
  293.         4 --> Attempt to Read Unwritten Extent
  294.         5 --> Directory Full
  295.         6 --> Attempt to Read Beyond End of Disk
  296.   USES : AF
  297.  
  298.  Usage:  This routine is used to write data at the current DMA
  299.   position to the designated file in a specific Record Number.
  300.   This file should have been previously opened by a call to
  301.   F$OPEN or equivalent.
  302.  
  303. :SCFA - Set and Clear File Attributes
  304.  
  305.   ENTER: DE = pointer to FCB
  306.       A = Attribute Code as:
  307.         A0 = Read-Only (1=Set to R/O, 0=Set to R/W)
  308.         A7 = SYStem    (1=Set to SYStem, 0=Set to Dir)
  309.   EXIT :  A = 0, Zero Flag Set (Z) if Operation Ok
  310.           A <> 0, Zero Clear (NZ) if Ambiguous file/Not found
  311.   USES : AF
  312.   SIDE EFFECT: All attribute bits other then Read-Only and SYStem
  313.     are cleared to Zero.
  314.  
  315.  Usage:  Set/Clear Read-Only and SYStem attributes of the specified
  316.   file and clear all other attributes to 0 (the MSBs of bytes 1-8
  317.   and 11 are set to 0).  Bits 0 and 7 of the A register are set to
  318.   signify how the Read-Only and SYStem bits are to be set in the
  319.   file.
  320.  
  321. SFA - Set File Attributes
  322.  
  323.   ENTER: DE = pointer to FCB
  324.       A = Attribute Code where:
  325.         A0 = Read-Only (1 = Set to R/O, 0 = Set to R/W)
  326.         A7 = SYStem    (1 = Set SYStem, 0 = Set Non-SYS)
  327.   EXIT :  A = 0, Zero Flag Set (Z) if Operation Ok
  328.           A <> 0, Zero Clear (NZ) if Ambiguous file/Not found
  329.   USES : AF
  330.   SIDE EFFECT: All attributes in the FCB are set to those of the
  331.     Directory entry except for Read-Only and SYStem
  332.  
  333.  Usage:  This routine is used to Set or Clear the Read-Only and/or
  334.   SYStem attributes of the specified file while not affecting the
  335.   other attribute bits (bytes 1-11, where byte 0 is first).
  336.  
  337. ::SYSLIBJ.HLP
  338.