home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / FFB.ZIP / FFHLP.ARC / FILES.TXT < prev    next >
Encoding:
File List  |  1987-10-31  |  12.1 KB  |  325 lines
  1. \ FILES.TXT     Information on Files and their interface in ZF.
  2.  
  3.  9. The File System and Handles
  4.  
  5.           The file system interface in ZF uses Handles to talk to
  6.         DOS, that is only number representing the File ID is passed
  7.         to DOS from Forth. To make the interface a simple and clean
  8.         as possible, you the Forth programmer need never deal with
  9.         the details of how this works, you only need know that
  10.         handles are created with the word HANDLE, handles are arrays
  11.         within which special file information is stored, and when a
  12.         handles name is executed, it returns an address which is the
  13.         address that is passed to the handle file control words. Word
  14.         definitions and usage follow;
  15.  
  16.         Handle Words in ZF
  17.  
  18.                 .FILES          ( --- )
  19.  
  20.           Print to the screen a list of the files currently open.
  21.  
  22.                 .LOADED         ( --- )
  23.  
  24.           Print a list of the files that have been loaded, This list
  25.         is used to locate the source file for a particular word that
  26.         has been compiled.
  27.  
  28.                 ">$             ( char_addr count --- counted_string )
  29.  
  30.           Drops the count, and decrements char_addr by one, to
  31.         convert to a counted string.
  32.  
  33.                 $>HANDLE        ( a1 handle --- )
  34.  
  35.           Move the COUNTED STRING a1 into the filename field of
  36.         handle.
  37.  
  38.                 $>EXT           ( a1 handle --- )
  39.  
  40.           Move the counted string a1 into the extension field of
  41.         handle, the extension string should not contain a decimal
  42.         point, and should be exactly (3) three characters long.
  43.  
  44.                 $HOPEN          ( a1 --- return_code )
  45.  
  46.           Close the current file if one is open, move the counted
  47.         string from address a1 to the current handle on the handle
  48.         stack. Return the result code from DOS as return_code.
  49.  
  50.                 !HCB            ( handle | text --- )
  51.  
  52.           Picks up text from the input stream with word, and places
  53.         the name into the handle.
  54.  
  55.  
  56.  
  57.                 ?DEF.EXT        ( --- handle )
  58.  
  59.           Conditionally applies the extension specified in the array
  60.         DEFEXT to the filename in handle. DEFEXT is a counted string,
  61.         three characters long plus the count.
  62.  
  63.                 CHARREAD        ( --- c1 )
  64.  
  65.           Reads a character from the currently open file specified by
  66.         SHNDL @, before using this word, you will need to initialize
  67.         the sequential input buffer to empty, to force a refill from
  68.         the currently selected file, by saying; INLEN OFF This will
  69.         force a disk read on the next call to CHARREAD, assuring you
  70.         get data from the file you selected.
  71.  
  72.                 CLOSE           ( --- )
  73.  
  74.           Close the currently open file on SHNDL @, moves down one
  75.         level on the handle stack, so another file may be open after
  76.         performing this operation, but normally you will be able to
  77.         operate on the handle in SHNDL, as an empty handle after
  78.         performing CLOSE.
  79.  
  80.                 CLR-HCB         ( handle --- )
  81.  
  82.           Clears the handle, to nulls, and resets the handle
  83.         identifier field to -1 to indicate no file is open.
  84.  
  85.                 CURPOINTER      ( handle --- Double_current )
  86.  
  87.           Returns the current 32-bit double pointer into the file
  88.         specified by handle.
  89.  
  90.                 DEFEXT          ( --- a1 )
  91.  
  92.           Returns the address of the default file extension that will
  93.         be applied to any file to be opened, if no extension is
  94.         specified in the filename when the HOPEN occurs. The address
  95.         a1 is the address of a 4 byte array containing a count byte,
  96.         and three extension bytes following. In no case should a
  97.         string longer than 3 characters plus count be placed in
  98.         DEFEXT.
  99.  
  100.                 ENDFILE         ( handle --- double_end )
  101.  
  102.           Return the double_end number which represents the length of
  103.         the file specified by handle. The file must already be open.
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.                 EXHREAD         ( a1 n1 handle segment --- n2 )
  113.  
  114.           Read from file handle into the buffer specified by segment
  115.         and address a1 for a length of bytes n1, return n2 the length
  116.         of bytes actually read. The file must already be open. Useful
  117.         for reading from a file into memory other than Forth's code
  118.         segment. A read from a file is limited to 65535 bytes.
  119.  
  120.                 EXHWRITE        ( a1 n1 handle segment --- n2 )
  121.  
  122.           Write from segment and address a1 for a length of n1 bytes
  123.         to file handle, return n2 the length of bytes actually
  124.         written. the file must already be open. Useful for writing
  125.         from memory other than Forth code segment to a file. A write
  126.         to a file is limited to 65535 bytes.
  127.  
  128.                 FILE>TIB        ( a1 --- )
  129.  
  130.           Move the counted string filename from address a1 to the
  131.         Terminal Input Buffer (TIB), available for use by !HCB.
  132.  
  133.                 FLOAD           ( filename --- )
  134.  
  135.           Open and load the file specified by filename.
  136.  
  137.                 HANDLE          ( <hndlname> --- )
  138.  
  139.           Create a handle with name <hndlname>. When <hndlname> is
  140.         later executed, it returns the address of the handle array
  141.         created.
  142.  
  143.                 HANDLE>EXT      ( handle --- a1 )
  144.  
  145.           Steps from the handle address to the address of the file
  146.         extension in the handle, if an extension exists, else it
  147.         steps to the null following the filename. The address a1 will
  148.         be the address of a decimal point character if the file
  149.         contains an extension, or the address of a null if no
  150.         extension was contained in the handle.
  151.  
  152.                 HCLOSE          ( handle --- return_code )
  153.  
  154.           Close the file currently open on handle, and return the
  155.         result code from DOS as return_code.
  156.  
  157.                 HCREATE         ( handle --- return_code )
  158.  
  159.           Create the filename specified by handle, and return the DOS
  160.         result code as return_code.
  161.  
  162.                 HDELETE         ( handle --- return_code )
  163.  
  164.           Delete the filename as specified by handle, return the
  165.         result code from DOS as return_code.
  166.  
  167.                 HIDELINES       ( --- )
  168.  
  169.           Specifies that lines loaded with FLOAD NOT be displayed to
  170.         the display screen.
  171.  
  172.                 HOPEN           ( handle --- return_code )
  173.  
  174.           Given handle the address, open the filename in it, and
  175.         return the result code from DOS as return_code.
  176.  
  177.                 HREAD           ( a1 n1 handle --- n2 )
  178.  
  179.           Read from file handle into the buffer address a1 for length
  180.         of bytes n1, return n2 the length of bytes actually read. The
  181.         file must already be open. A read from a file is limited to
  182.         65535 bytes.
  183.  
  184.                 HRENAME         ( handle1 handle2 --- return_code )
  185.  
  186.           Rename the filename specified by handle1 to be the name
  187.         specified in handle2, return the DOS result code as
  188.         return_code.
  189.  
  190.                 HWRITE          ( a1 n1 handle --- n2 )
  191.  
  192.           Write from address a1 for length n1 bytes to file handle,
  193.         return n2 the length of bytes actually written. The file must
  194.         already be open. A write to a file is limited to 65535
  195.         bytes.
  196.  
  197.                 LINEREAD        ( --- a1 )
  198.  
  199.           Reads lines from the current file, prebuffered by INBUF,
  200.         which holds 1024 bytes. Returns a1 the address of OUTBUF, a
  201.         256 byte buffer used to hold lines read. When switching to a
  202.         new file, you should use MOVEPOINTER to reset the file
  203.         pointer to the beginning of the file, and reset INLEN to zero
  204.         so the next LINEREAD will cause a read from the disk file.
  205.         The read line length is limited to 255 bytes.
  206.  
  207.                 LIST            ( line_number --- )
  208.  
  209.           List 18 lines starting at line_number from the currently open
  210.         file. See also L N B OPEN FL
  211.  
  212.                 LOAD            ( line_number --- )
  213.  
  214.           Start loading the currently open file, at line_number. Load
  215.         through the end of the file if no errors are encountered.
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.                 MOVEPOINTER     ( double_offset handle --- )
  223.  
  224.           Move the filepointer into the file handle to the offset
  225.         location specified by double_offset. The file must already be
  226.         open.
  227.  
  228.                 PATHSET         ( handle --- f1 )
  229.  
  230.           Checks the file contained in handle, if it does not contain
  231.         a path, then it applies the current drive and path to the
  232.         handle. Returns f1 FALSE if it succeeded, else TRUE if it
  233.         failed to read the path from DOS.
  234.  
  235.                 RWMODE          ( --- a1 )
  236.  
  237.           A variable which holds the read/write attributes for any
  238.         file to be opened by HOPEN, normally contains a two (2) for
  239.         read/write, may be set to one (1) for write only, or to zero
  240.         (0) for read only.
  241.  
  242.                 SEEK            ( d1 --- )
  243.  
  244.           Position the file pointer for the file currently open on
  245.         SHNDL @, to d1, that is SEEK to position d1.
  246.  
  247.                 SEQDOWN         ( --- )
  248.  
  249.           Close the current file on the current level of the handle
  250.         stack, and step down one level to the previous handle. The
  251.         handle stack is four levels deep.
  252.  
  253.                 SEQUP           ( --- )
  254.  
  255.           Step up one Handle on the handle stack, if there is a file
  256.         open on that stack level, close it. The stack handle is four
  257.         levels deep.
  258.  
  259.                 SHOWLINES       ( --- )
  260.  
  261.           Specifies that lines loaded with FLOAD will be displayed to
  262.         the display screen.
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.         Handle Fields
  278.  
  279.           A handle contains several fields, and words have been
  280.         defined to traverse to the various fields, here is a picture
  281.         of the data structure of a handle.
  282.  
  283.             +0        +1                     +66            +68
  284.           [ count ] [ path & filename 00 ] [ attributes ] [ handle ]
  285.             1 byte    64 bytes   +  null     2 bytes        2 bytes
  286.             ^          ^                     ^              ^
  287.             |          |                     |              |
  288.           handle     >NAM                  >ATTRIB        >HNDLE
  289.  
  290.           Each of the words in the above line, after handle, steps
  291.         from the address returned by the handle, to the field
  292.         indicated.
  293.  
  294.         Sample of LINEREAD usage.
  295.  
  296.           A sequential line read word LINEREAD is provided, which
  297.         reads a line at a time from the file open in SHNDL, returning
  298.         an address of a counted string which will include the CRLF
  299.         characters at the end of the line, so you will need to strip
  300.         them off if you don't want them. the LINEREAD word is used as
  301.         follows;
  302.  
  303.         : sample        ( filename --- )
  304.                 open                            \ open a file
  305.                 0.0 seek                        \ reset file pointer
  306.                 inlen off                       \ clear input buffer
  307.                 begin   lineread                \ read a line, returns
  308.                                                 \ an address of counted $
  309.                         dup c@                  \ check for length <>0
  310.                 while   cr count 2- type        \ type line just read
  311.                                                 \ without the CRLF chars.
  312.                 repeat  drop                    \ repeat till file empty.
  313.                 close ;                         \ close the file.
  314.  
  315.           This simple example may seem complicated, but it really is
  316.         easy to read the lines of a sequential file, and writing is
  317.         just as easy.
  318.  
  319.           The word LINEREAD automatically buffers the reads from disk
  320.         in a 1k buffer to minimize the number of DOS calls performed.
  321.         Lines up to 255 characters can be read with LINEREAD, longer
  322.         lines or lines not terminated by a LF will be truncated to
  323.         255 characters.
  324.  
  325.