eX version 0.4b User's Manual                         File eXMan19.txt
(C) Copyright 1995, 1996 William E. Wilgus III.   All rights reserved.

File Functions


          Illegal LITERAL eX File Specification Characters

          Character   Name             ASCII Code
           #      Pound sign         35
           $      Dollar sign        36
           (      Left parens        40
           )      Right parens       41
           /      Slash              47
           ]      Right bracket      91


eof
                    eof FileArgument
     Boolean end of file.  For sequential files, it returns true (-1)
     if so, false (0) if not.  For random files, it returns true only
     if the last record read was incomplete due to the end of file
     being reached.  The argument may be either a file specification
     or a file number.  

fAttr
                fAttr FileArgument <<:= eev#>>
     Returns the argument file's attribute, which may be interpreted  
     with 
               Bit #   Test    Bit Set Meaning
                   0    & 1     Read only
                   1    & 2     Hidden file
                   2    & 4     System file
                   3    & 8     Volume label
                   4    & 16    Sub-directory
                   5    & 32    Archive

     The file may be specified by either its file number or file
     specification, and if given as a file specification, the file
     does not need to be currently defined.

fDate
               fDate FileArgument <<:= Date$>>
     Returns the date of FileArgument and is assignable.  The argument
     may be either a file number or specification, and in the 
     latter case the file does not need to be currently defined.  

fDTG
                   fDTG File
     Returns the Date Time Group of File as a long integer that is 
     equivalent to

          (jDate(fDate File) * 100000 + esecs(fTime File))

     and is compatable with the product of the function DTG. The
     argument may be either a file number or specification, and in the
     latter case the file does not need to be currently defined.  eX 
     crashes if the file is not found.

file
     Defines a file and makes it available for use.  Files may be
     multiply defined.  For random access files the arguments are 

          file(FileSpec$, FileNumber#, Mode$, BufferDefinition$)

     and for sequential files the arguments are 

          file(FileSpec$, FileNumber#, Mode<<, Option$>>)

     FileSpecific$ is an eX filespecification.  FileNumber# may be
     any number 0 through the number of files allocated (/af#), with
     0 being a signal to use the lowest available file number,
     beginning with 1.  In such case the file number actually used may
     be determined with the function FileId.  
 
     Mode$ may be any of

               Append   Input   Output   Random 

     in either alphabetic case.  Only the first character is
     significant and required.  
 
     BufferDefinition$ is an enumeration of the record fields (which
     are referred to as variables in eX) for random access files.  
     Whitespace must exist between each identifier in the enumeration.


     String fields must have a stated length that must be seperated
     from the string identifier by a comma followed by whitespace.  

               "$One, 10 _two __three .four ..five"
     The above defines a record with a 10-byte string named "One" 
     followed by the numerics enumerated, which are stored in the 
     file in internal storage format.  
 
     Option$ may be used with sequential files to specify a delimited 
     file with  

                              D or d

     or a length-encoded file with  

                              L or l 

FileId
                         FileId FileArgument
     Returns the file identity of FileArgument, which must currently
     be defined.  If FileArgument is given as a file specification,
     its file number is returned; as a file number, its file
     specification is returned.

files
     Returns the number of files allocated.

fMode
                         fMode FileArgument
     Returns file mode number for FileArgument, which may be given as
     either a file specification (string) or a file number, but must
     currently be defined.  The returned number may be interpreted 
     with 

                    Code   Mode
                      3    Random access
                      4    Input
                      5    Length-encoded input
                      6    Delimited input
                      7    Output
                      8    Length-encoded output
                      9    Delimited output
                     10    Append
                     11    Length-encoded append
                     12    Delimited append

forget
           forget DataEntity1$<<, DataEntity2, ...>>
     Removes knowledge of the argument data object list elements.  
     All data entities except accumulators may be forgotten.  For
     files, forgets all openings if a file specification is given; if
     a file number is given, only the opening as the file number is
     forgotten.  If the file is a random access file, the current
     record is written prior to forgetting the file; sequential output
     file buffers are `flushed'.  A forget data entity may be
     indirectly specified, and any data entity used in the indirection
     will be preserved.  `Forget' is otherwise inert.  


fPos
                         fPos FileArgument
     Returns the position of the currently defined file FileArgument,
     which may be given as a file specification or number.  For random
     access files the returned value is the record number; sequential
     files the byte position.

FreeFiles
     Returns the number of files that may be defined, i.e. the number
     of file data entities that are not currently being used. 

fTime
                    fTime FileArgument <<:= Time$>>
     Returns the time of FileArgument and is assignable. The argument
     may be either a file number or specification; and if given as the
     latter, doesn't need to be currently defined.

lof
                         lof FileArgument
     Returns the length of the file.  It accepts either a file
     specification or if the file is currently defined, its file
     number argument.  The number of records is returned for random
     access files, the number of bytes in the file is returned for
     sequential access files and un-defined files.  Note that for
     sequential files, the value returned includes the byte occupied
     by the operating system's end of file flag, ^Z.

read
     With random access files, reads a record from the identified
     file into the buffer.  It does not return any data. 

                    read(ObjectFile<<, RecordNumber#>>)

     The file argument may be a file specification or a file number.  
     If the record number is absent or given as 0, the next record
     from the current file position is read. 

     With sequential files, reads the file for each data entity in the
     argument list and assigns the value read to the data entity.

          read(ObjectFile) DataEntity1<<, ... DataEntityN>> 

seek
               seek(FileIdentifier, Position#)
     Positions a file's read/write pointer.  For random access, 
     Position# is a record number; in all other modes, the byte
     position.  The first byte and the first record both numbered 1.
     The file may be given as a file specification or a file number.  

TempFile
               TempFile<<(DrivePath<<, Attribute#>>)>>
     Creates a uniquely named file in DrivePath$ having the file 
     attribute Attribute#.  If Attrribute# is omitted, 0 is used
     (normal file), and in the sans-argument form, the file is created
     in the current sub-directory of the default drive.  The function
     name refers to its usual use---the files are persistent (but they
     do have wierd names).

write
     The form of the argument varies according to the mode of the
     file. 

                    write(ObjectFile<<, Recno#>>)
     For random files, writes a random access record.  
     The object file may be given as a file specification or a file
     number.  If the record number is absent or given as 0, the next
     record from the current position is written.  If the record to be
     written is more than one record past the current end of the file,
     null records are written from the current end of the file to the
     specified record - 1.  
 
          write<<;>>(ObjectFile) Data1<<, Data2<<; ... DataN>>>>
     With sequential files, writes each data entity in the argument
     list to the file.  If simultaneously presented with both data
     class values, writes both (the string first).  If a comma (,) is
     used as an argument list item seperator, a carriage return is
     issued to the file after the list item it precedes is sent to the
     file.  If a semi-colon (;) is used, no carriage return is
     issued to the file after the item it precedes. The optional
     semi-colon immediately following the eX word write is used to
     supress a carriage return after the last (or only) item in the
     list.  Note that carriage return supression applies to both if
     write is simultaneously presented with values in both data
     classes.
