OPEN {`in | `out | `append | `direct } [`big | `little] File '<>' Path
CLOSE`file File
Before reading or writing to a file it must first be opened. When a file is opened a File handle is designated that is used to reference the file in subsequent I/O commands. THe handle can also be passed as an argument to a procedure.
When done processing the file it needs to be closed. If the File handle is declared as a Local variable in a procedure then the file will automatically be closed when leaving the procedure. A File Handle declared in a Class as Global will be closed when the program terminates. You can also close a file immediately using the Close command.
Since the Open and Close verbs often used as procedure names, they can be overloaded. You can name a procedure Open or Close so long as the parameters do not have In, Out, Append, or Direct switches. They should not be declared as parameters with a Bit type.
The Io.File class in the Basis library includes methods for a common set of I/O operations. It is imported whenever you import the Gilda.Basis library. It declares a type, File, typically used to declare a file handle. I/O commands can also use the standard I/O streams, (In, Out, and Err) as handles.
You can also declare a custom file handle for use with I/O commands. A file handle is a structure containing a wizard pointer to a byte. Supporting Macros and Micros can also be included in the structure.
type File is - *Id = 0 byte :Opaque file Id
OPEN {`in | `out | `append | `direct } [`big | `little] File '<>' Path
in Open a file for input.
out Open a file for sequential output; overwriting an existing file.
append Open a file for sequential output; appending to an existing file.
direct Open a file for direct access.
big Write integer values in big endian order (default).
little Write integer values in little endian order.
File Declare the name of a handle used by subsequent I/O commands.
Path Declare the OS path of the file to open as a String expression.
The Path argument is a String expression and may be an absolute or relative file path. Either forward or backward slashes can be used to delimit path components. A ".." component to reference the next higher directory.
Any restrictions on characters used in a path component are platform specific. On Windows platform a leading drive name is allowed. It is written as a drive letter followed by a colon and slash. Paths on Windows file sytems are not case sensitive, but they are on Unix.
The External Data Representation (XDR) standard specifies using big endian layout for portable binary messaging and binary data files. You can also marshall binary data by serializing it as text. The Serialize.Primitive class in the Gilda Basis library has procedures that serialize and deserialize primitive types.
Direct access files are a one dimensional array of a given type. The type cannot be a String and if it is a structure it must be declared as a Record Type. Records are stored without padding between elements regardles of the alignment .
When opening an existing file for output, it is deleted and a new empty file is created. When an existing file is opened for Input or Direct access, it is positioned to the beginning of the file. If an existing file is opened for appending then it is positioned to the end of the file.
The same file can be opened concurrently by separate threads or processes. The behavior of any conflict is determined by the operating system.
CLOSE`file File
Once a file is closed its handle cannot be used to access it without reopening it. After successfully closing a file handle, the pointer in the handle is zeroed. Closing a file that is already closed does nothing and will not raise an exception.
A file must be eventually be closed, but this may be done automatically when leaving a procedure or a program teminates. After an exception is raised it is good practice to ensure that any open files are closed. When unwinding exception a File handle local to a procedure will be closed once that procedure is unwound. When the File Handle is a Global variable it is especially important to close it after an exception. You can use a Postconditon block to take care of this.
The Basis library includes a File.Size function that determines the number of bytes in a file. The Path argument is a string expression that is the (OS specific) path of the file. On an error the result is a negative error code.
Size = File.Size( Path ); Get the number of bytes in a file.
-1 The file was not found.
-2 The file cannot be accessed.
-3 The file is protected.
-4 The path is a directory.
The Basis library also has a generic Status function that returns the state of a File stream. If called with an uninitialized file handle, the result is undefined.
Code = Status( File ); Get the current state of a file being processed. Closed 0 The file is closed Eol #A Sequential input at End Of Line Eof #B Sequential input at End of Stream Peof #C Sequential input at Past End of Stream In #D Sequential input at next byte to be read Out #E Sequential output Direct #F Direct access
The File type defines macros to check the status of a File handle.
IF File`Open: IF the file is open,
The Status function can also be used to determine the cause of an exception after an I/O error has occurred. When an I/O error occurs an Error exception is raised. The exception Message will have a description of the cause. Note that the status will only be set to an error state within a Catch handler.
Command Status Message
OPEN #10 Tried to open a file that does not exist.
#11 Can not open a directory.
#12 Not permitted to access a path directory.
#13 Not permitted to access a file or stream.
#14 The file or stream is in use by another.
#15 Too many files are open.
INPUT, OPEN #16 Could not read from a file or stream.
PRINT, OPEN, CLOSE #17 Could not write to a file or stream.
PRINT, CLOSE #18 The file system is full.
#19 The output buffer overflowed.
PRINT, INPUT #1a Using the wrong kind of File Handle.
#1b The Seek index is too large.
Yield a Sequence Value
