
   [left.gif]-[left.gif] [right.gif]-[right.gif] [up.gif]-[up.gif] Table
   of Contents
     _________________________________________________________________
   
                     11. The optional File-Access word set
                                       
   See: A.11 The optional File-Access word set
     _________________________________________________________________
   
11.1 Introduction

   These words provide access to mass storage in the form of files under
   the following assumptions:
     * files are provided by a host operating system;
     * file names are represented as character strings;
     * the format of file names is determined by the host operating
       system;
     * an open file is identified by a single-cell file identifier
       (fileid);
     * file-state information (e.g., position, size) is managed by the
       host operating system;
     * file contents are accessed as a sequence of characters;
     * file read operations return an actual transfer count, which can
       differ from the requested transfer count.
     _________________________________________________________________
   
11.2 Additional terms

   file-access method:
          A permissible means of accessing a file, such as read/write or
          read only.
          
   file position:
          The character offset from the start of the file.
          
   input file:
          The file, containing a sequence of lines, that is the input
          source.
     _________________________________________________________________
   
11.3 Additional usage requirements
     _________________________________________________________________
   
  11.3.1 Data types
  
   Append table 11.1 to table 3.1.
   
   Table 11.1 - Data types
   
Symbol  Data type               Size on stack
------  ---------               -------------
ior     I/O results             1 cell
fam     file access method      1 cell
fileid  file identifiers        1 cell
     _________________________________________________________________
   
    11.3.1.1 File identifiers
    
   File identifiers are implementation-dependent single-cell values that
   are passed to file operators to designate specific files. Opening a
   file assigns a file identifier, which remains valid until closed.
     _________________________________________________________________
   
    11.3.1.2 I/O results
    
   I/O results are single-cell numbers indicating the result of I/O
   operations. A value of zero indicates that the I/O operation completed
   successfully; other values and their meanings are
   implementation-defined. Reaching the end of a file shall be reported
   as zero.
   
   An I/O exception in the execution of a File-Access word that can
   return an I/O result shall not cause a THROW; exception indications
   are returned in the ior.
     _________________________________________________________________
   
    11.3.1.3 File access methods
    
   File access methods are implementation-defined single-cell values.
     _________________________________________________________________
   
    11.3.1.4 File names
    
   A character string containing the name of the file. The file name may
   include an implementation-dependent path name. The format of file
   names is implementation defined.
     _________________________________________________________________
   
  11.3.2 Blocks in files
  
   If the File-Access word set is implemented, the Block word set shall
   be implemented.
   
   Blocks may, but need not, reside in files. When they do:
   
     * Block numbers may be mapped to one or more files by
       implementation-defined means. An ambiguous condition exists if a
       requested block number is not currently mapped;
     * An UPDATEd block that came from a file shall be transferred back
       to the same file.
       
   See: A.11.3.2 Blocks in files
     _________________________________________________________________
   
  11.3.3 Environmental queries
  
   Append table 11.2 to table 3.5.
   
   See: 3.2.6 Environmental queries
   
   Table 11.2 - Environmental query strings
   
String         Value data type   Constant?  Meaning
------         ---------------   ---------  -------
FILE            flag             no         file word set present
FILE-EXT        flag             no         file extensions word set present
     _________________________________________________________________
   
  11.3.4 Input source
  
   The File-Access word set creates another input source for the text
   interpreter. When the input source is a text file, BLK shall contain
   zero, SOURCE-ID shall contain the fileid of that text file, and the
   input buffer shall contain one line of the text file.
   
   Input with INCLUDED, INCLUDE-FILE, LOAD and EVALUATE shall be nestable
   in any order to at least eight levels.
   
   A program that uses more than eight levels of input-file nesting has
   an environmental dependency.
   
   See: 3.3.3.5 Input buffers, 9. Optional Exception word set.
     _________________________________________________________________
   
  11.3.5 Other transient regions
  
   The list of words using memory in transient regions is extended to
   include 11.6.1.2165 S".
   
   See: 3.3.3.6 Other transient regions
     _________________________________________________________________
   
  11.3.6 Parsing
  
   When parsing from a text file using a space delimiter, control
   characters shall be treated the same as the space character.
   
   Lines of at least 128 characters shall be supported. A program that
   requires lines of more than 128 characters has an environmental
   dependency.
   
   A program may reposition the parse area within the input buffer by
   manipulating the contents of >IN. More extensive repositioning can be
   accomplished using SAVE-INPUT and RESTORE-INPUT.
   
   See: 3.4.1 Parsing
     _________________________________________________________________
   
11.4 Additional documentation requirements
     _________________________________________________________________
   
  11.4.1 System documentation
     _________________________________________________________________
   
    11.4.1.1 Implementation-defined options
    
     * file access methods used by 11.6.1.0765 BIN, 11.6.1.1010
       CREATE-FILE, 11.6.1.1970 OPEN-FILE, 11.6.1.2054 R/O, 11.6.1.2056
       R/W, and 11.6.1.2425 W/O;
     * file exceptions;
     * file line terminator (11.6.1.2090 READ-LINE);
     * file name format (11.3.1.4 File names);
     * Information returned by 11.6.2.1524 FILE-STATUS;
     * Input file state after an exception (11.6.1.1717 INCLUDE-FILE,
       11.6.1.1718 INCLUDED);
     * ior values and meaning (11.3.1.2 I/O results);
     * maximum depth of file input nesting (11.3.4 Input source);
     * maximum size of input line (11.3.6 Parsing);
     * methods for mapping block ranges to files (11.3.2 Blocks in
       files);
     * number of string buffers provided (11.6.1.2165 S");
     * size of string buffer used by 11.6.1.2165 S".
     _________________________________________________________________
   
    11.4.1.2 Ambiguous conditions
    
     * attempting to position a file outside its boundaries (11.6.1.2142
       REPOSITION-FILE);
     * attempting to read from file positions not yet written
       (11.6.1.2080 READ-FILE, 11.6.1.2090 READ-LINE);
     * fileid is invalid (11.6.1.1717 INCLUDE-FILE);
     * I/O exception reading or closing fileid (11.6.1.1717 INCLUDE-FILE,
       11.6.1.1718 INCLUDED);
     * named file cannot be opened (11.6.1.1718 INCLUDED);
     * requesting an unmapped block number (11.3.2 Blocks in files);
     * using 11.6.1.2218 SOURCE-ID when 7.6.1.0790 BLK is not zero.
     _________________________________________________________________
   
    11.4.1.3 Other system documentation
    
     * no additional requirements.
     _________________________________________________________________
   
  11.4.2 Program documentation
     _________________________________________________________________
   
    11.4.2.1 Environmental dependencies
    
     * requiring lines longer than 128 characters (11.3.6 Parsing);
     * using more than eight levels of input-file nesting (11.3.4 Input
       source).
     _________________________________________________________________
   
    11.4.2.2 Other program documentation
    
     * no additional requirements.
     _________________________________________________________________
   
11.5 Compliance and labeling
     _________________________________________________________________
   
  11.5.1 ANS Forth systems
  
   The phrase Providing the File Access word set shall be appended to the
   label of any Standard System that provides all of the File Access word
   set.
   
   The phrase Providing name(s) from the File Access Extensions word set
   shall be appended to the label of any Standard System that provides
   portions of the File Access Extensions word set.
   
   The phrase Providing the File Access Extensions word set shall be
   appended to the label of any Standard System that provides all of the
   File Access and File Access Extensions word sets.
     _________________________________________________________________
   
  11.5.2 ANS Forth programs
  
   The phrase Requiring the File Access word set shall be appended to the
   label of Standard Programs that require the system to provide the File
   Access word set.
   
   The phrase Requiring name(s) from the File Access Extensions word set
   shall be appended to the label of Standard Programs that require the
   system to provide portions of the File Access Extensions word set.
   
   The phrase Requiring the File Access Extensions word set shall be
   appended to the label of Standard Programs that require the system to
   provide all of the File Access and File Access Extensions word sets.
     _________________________________________________________________
   
11.6 Glossary
     _________________________________________________________________
   
  11.6.1 File Access words
     _________________________________________________________________
   
   11.6.1.0080 (
   paren FILE
        ( "ccc<paren>" -- )

   Extend the semantics of 6.1.0080 ( to include:
   
   When parsing from a text file, if the end of the parse area is reached
   before a right parenthesis is found, refill the input buffer from the
   next line of the file, set >IN to zero, and resume parsing, repeating
   this process until either a right parenthesis is found or the end of
   the file is reached.
     _________________________________________________________________
   
   11.6.1.0765 BIN
   FILE
        ( fam1 -- fam2 )

   Modify the implementation-defined file access method fam1 to
   additionally select a binary, i.e., not line oriented, file access
   method, giving access method fam2.
   
   See: A.11.6.1.0765 BIN , 11.6.1.2054 R/O , 11.6.1.2056 R/W ,
   11.6.1.2425 W/O
     _________________________________________________________________
   
   11.6.1.0900 CLOSE-FILE
   FILE
        ( fileid -- ior )

   Close the file identified by fileid. ior is the implementation-defined
   I/O result code.
     _________________________________________________________________
   
   11.6.1.1010 CREATE-FILE
   FILE
        ( c-addr u fam -- fileid ior )

   Create the file named in the character string specified by c-addr and
   u, and open it with file access method fam. The meaning of values of
   fam is implementation defined. If a file with the same name already
   exists, recreate it as an empty file.
   
   If the file was successfully created and opened, ior is zero, fileid
   is its identifier, and the file has been positioned to the start of
   the file.
   
   Otherwise, ior is the implementation-defined I/O result code and
   fileid is undefined.
   
   See: A.11.6.1.1010 CREATE-FILE
     _________________________________________________________________
   
   11.6.1.1190 DELETE-FILE
   FILE
        ( c-addr u -- ior )

   Delete the file named in the character string specified by c-addr u.
   ior is the implementation-defined I/O result code.
     _________________________________________________________________
   
   11.6.1.1520 FILE-POSITION
   FILE
        ( fileid -- ud ior )

   ud is the current file position for the file identified by fileid. ior
   is the implementation-defined I/O result code. ud is undefined if ior
   is non-zero.
     _________________________________________________________________
   
   11.6.1.1522 FILE-SIZE
   FILE
        ( fileid -- ud ior )

   ud is the size, in characters, of the file identified by fileid. ior
   is the implementation-defined I/O result code. This operation does not
   affect the value returned by FILE-POSITION. ud is undefined if ior is
   non-zero.
     _________________________________________________________________
   
   11.6.1.1717 INCLUDE-FILE
   FILE
        ( i*x fileid -- j*x )

   Remove fileid from the stack. Save the current input source
   specification, including the current value of SOURCE-ID. Store fileid
   in SOURCE-ID. Make the file specified by fileid the input source.
   Store zero in BLK. Other stack effects are due to the words included.
   
   Repeat until end of file: read a line from the file, fill the input
   buffer from the contents of that line, set >IN to zero, and interpret.
   
   Text interpretation begins at the file position where the next file
   read would occur.
   
   When the end of the file is reached, close the file and restore the
   input source specification to its saved value.
   
   An ambiguous condition exists if fileid is invalid, if there is an I/O
   exception reading fileid, or if an I/O exception occurs while closing
   fileid. When an ambiguous condition exists, the status (open or
   closed) of any files that were being interpreted is
   implementation-defined.
   
   See: 11.3.4 Input source, A.11.6.1.1717 INCLUDE-FILE
     _________________________________________________________________
   
   11.6.1.1718 INCLUDED
   FILE
        ( i*x c-addr u -- j*x )

   Remove c-addr u from the stack. Save the current input source
   specification, including the current value of SOURCE-ID. Open the file
   specified by c-addr u, store the resulting fileid in SOURCE-ID, and
   make it the input source. Store zero in BLK. Other stack effects are
   due to the words included.
   
   Repeat until end of file: read a line from the file, fill the input
   buffer from the contents of that line, set >IN to zero, and interpret.
   
   Text interpretation begins at the file position where the next file
   read would occur.
   
   When the end of the file is reached, close the file and restore the
   input source specification to its saved value.
   
   An ambiguous condition exists if the named file can not be opened, if
   an I/O exception occurs reading the file, or if an I/O exception
   occurs while closing the file. When an ambiguous condition exists, the
   status (open or closed) of any files that were being interpreted is
   implementation-defined.
   
   See: A.11.6.1.1718 INCLUDED , 11.6.1.1717 INCLUDE-FILE
     _________________________________________________________________
   
   11.6.1.1970 OPEN-FILE
   FILE
        ( c-addr u fam -- fileid ior )

   Open the file named in the character string specified by c-addr u,
   with file access method indicated by fam. The meaning of values of fam
   is implementation defined.
   
   If the file is successfully opened, ior is zero, fileid is its
   identifier, and the file has been positioned to the start of the file.
   
   Otherwise, ior is the implementation-defined I/O result code and
   fileid is undefined.
   
   See: A.11.6.1.1970 OPEN-FILE
     _________________________________________________________________
   
   11.6.1.2054 R/O
   r-o FILE
        ( -- fam )

   fam is the implementation-defined value for selecting the read only
   file access method.
   
   See: 11.6.1.1010 CREATE-FILE , 11.6.1.1970 OPEN-FILE
     _________________________________________________________________
   
   11.6.1.2056 R/W
   r-w FILE
        ( -- fam )

   fam is the implementation-defined value for selecting the read/write
   file access method.
   
   See: 11.6.1.1010 CREATE-FILE , 11.6.1.1970 OPEN-FILE
     _________________________________________________________________
   
   11.6.1.2080 READ-FILE
   FILE
        ( c-addr u1 fileid -- u2 ior )

   Read u1 consecutive characters to c-addr from the current position of
   the file identified by fileid.
   
   If u1 characters are read without an exception, ior is zero and u2 is
   equal to u1.
   
   If the end of the file is reached before u1 characters are read, ior
   is zero and u2 is the number of characters actually read.
   
   If the operation is initiated when the value returned by FILE-POSITION
   is equal to the value returned by FILE-SIZE for the file identified by
   fileid, ior is zero and u2 is zero.
   
   If an exception occurs, ior is the implementation-defined I/O result
   code, and u2 is the number of characters transferred to c-addr without
   an exception.
   
   An ambiguous condition exists if the operation is initiated when the
   value returned by FILE-POSITION is greater than the value returned by
   FILE-SIZE for the file identified by fileid, or if the requested
   operation attempts to read portions of the file not written.
   
   At the conclusion of the operation, FILE-POSITION returns the next
   file position after the last character read.
   
   See: A.11.6.1.2080 READ-FILE
     _________________________________________________________________
   
   11.6.1.2090 READ-LINE
   FILE
        ( c-addr u1 fileid -- u2 flag ior )

   Read the next line from the file specified by fileid into memory at
   the address c-addr. At most u1 characters are read. Up to two
   implementation-defined line-terminating characters may be read into
   memory at the end of the line, but are not included in the count u2.
   The line buffer provided by c-addr should be at least u1+2 characters
   long.
   
   If the operation succeeded, flag is true and ior is zero. If a line
   terminator was received before u1 characters were read, then u2 is the
   number of characters, not including the line terminator, actually read
   (0 <= u2 <= u1). When u1 = u2, the line terminator has yet to be
   reached.
   
   If the operation is initiated when the value returned by FILE-POSITION
   is equal to the value returned by FILE-SIZE for the file identified by
   fileid, flag is false, ior is zero, and u2 is zero. If ior is
   non-zero, an exception occurred during the operation and ior is the
   implementation-defined I/O result code.
   
   An ambiguous condition exists if the operation is initiated when the
   value returned by FILE-POSITION is greater than the value returned by
   FILE-SIZE for the file identified by fileid, or if the requested
   operation attempts to read portions of the file not written.
   
   At the conclusion of the operation, FILE-POSITION returns the next
   file position after the last character read.
   
   See: A.11.6.1.2090 READ-LINE , RFI 0001.
     _________________________________________________________________
   
   11.6.1.2142 REPOSITION-FILE
   FILE
        ( ud fileid -- ior )

   Reposition the file identified by fileid to ud. ior is the
   implementation-defined I/O result code. An ambiguous condition exists
   if the file is positioned outside the file boundaries.
   
   At the conclusion of the operation, FILE-POSITION returns the value
   ud.
     _________________________________________________________________
   
   11.6.1.2147 RESIZE-FILE
   FILE
        ( ud fileid -- ior )

   Set the size of the file identified by fileid to ud. ior is the
   implementation-defined I/O result code.
   
   If the resultant file is larger than the file before the operation,
   the portion of the file added as a result of the operation might not
   have been written.
   
   At the conclusion of the operation, FILE-SIZE returns the value ud and
   FILE-POSITION returns an unspecified value.
   
   See: 11.6.1.2080 READ-FILE , 11.6.1.2090 READ-LINE
     _________________________________________________________________
   
   11.6.1.2165 S"
   s-quote FILE
   
   Extend the semantics of 6.1.2165 S" to be:
        Interpretation: ( "ccc<quote>" -- c-addr u )

   Parse ccc delimited by " (double quote). Store the resulting string
   c-addr u at a temporary location. The maximum length of the temporary
   buffer is implementation-dependent but shall be no less than 80
   characters. Subsequent uses of S" may overwrite the temporary buffer.
   At least one such buffer shall be provided.
        Compilation: ( "ccc<quote>" -- )

   Parse ccc delimited by " (double quote). Append the run-time semantics
   given below to the current definition.
        Run-time: ( -- c-addr u )

   Return c-addr and u that describe a string consisting of the
   characters ccc.
   
   See: 3.4.1 Parsing, 6.2.0855 C" , A.11.6.1.2165 S" , 11.3.5 Other
   transient regions.
     _________________________________________________________________
   
   11.6.1.2218 SOURCE-ID
   source-i-d FILE
        ( -- 0 | -1 | fileid )

   Extend 6.2.2218 SOURCE-ID to include text-file input as follows:
SOURCE-ID       Input source
---------       ------------
fileid          Text file fileid
-1              String (via EVALUATE)
0               User input device

   An ambiguous condition exists if SOURCE-ID is used when BLK contains a
   non-zero value.
     _________________________________________________________________
   
   11.6.1.2425 W/O
   w-o FILE
        ( -- fam )

   fam is the implementation-defined value for selecting the write only
   file access method.
   
   See: 11.6.1.1010 CREATE-FILE , 11.6.1.1970 OPEN-FILE
     _________________________________________________________________
   
   11.6.1.2480 WRITE-FILE
   FILE
        ( c-addr u fileid -- ior )

   Write u characters from c-addr to the file identified by fileid
   starting at its current position. ior is the implementation-defined
   I/O result code.
   
   At the conclusion of the operation, FILE-POSITION returns the next
   file position after the last character written to the file, and
   FILE-SIZE returns a value greater than or equal to the value returned
   by FILE-POSITION.
   
   See: 11.6.1.2080 READ-FILE , 11.6.1.2090 READ-LINE
     _________________________________________________________________
   
   11.6.1.2485 WRITE-LINE
   FILE
        ( c-addr u fileid -- ior )

   Write u characters from c-addr followed by the
   implementation-dependent line terminator to the file identified by
   fileid starting at its current position. ior is the
   implementation-defined I/O result code.
   
   At the conclusion of the operation, FILE-POSITION returns the next
   file position after the last character written to the file, and
   FILE-SIZE returns a value greater than or equal to the value returned
   by FILE-POSITION.
   
   See: 11.6.1.2080 READ-FILE , 11.6.1.2090 READ-LINE
     _________________________________________________________________
   
  11.6.2 File-Access extension words
     _________________________________________________________________
   
   11.6.2.1524 FILE-STATUS
   FILE EXT
        ( c-addr u -- x ior )

   Return the status of the file identified by the character string
   c-addr u. If the file exists, ior is zero; otherwise ior is the
   implementation-defined I/O result code. x contains
   implementation-defined information about the file.
     _________________________________________________________________
   
   11.6.2.1560 FLUSH-FILE
   FILE EXT
        ( fileid -- ior )

   Attempt to force any buffered information written to the file referred
   to by fileid to be written to mass storage, and the size information
   for the file to be recorded in the storage directory if changed. If
   the operation is successful, ior is zero. Otherwise, it is an
   implementation-defined I/O result code.
     _________________________________________________________________
   
   11.6.2.2125 REFILL
   FILE EXT
        ( -- flag )

   Extend the execution semantics of 6.2.2125 REFILL with the following:
   
   When the input source is a text file, attempt to read the next line
   from the text-input file. If successful, make the result the current
   input buffer, set >IN to zero, and return true. Otherwise return
   false.
   
   See: 7.6.2.2125 REFILL
     _________________________________________________________________
   
   11.6.2.2130 RENAME-FILE
   FILE EXT
        ( c-addr1 u1 c-addr2 u2 -- ior )

   Rename the file named by the character string c-addr1 u1 to the name
   in the character string c-addr2 u2. ior is the implementation-defined
   I/O result code.
     _________________________________________________________________
   
   [up.gif]-[up.gif] Table of Contents
   [right.gif]-[right.gif] Next Section
