File Input and Output are accomplished by assigning
appropriate attributes or values to Scripta variables of
type FILE.

A FILE variable is created by assigning one of the
attributes OPEN, CREATE or APPEND to a Scripta variable.
Such a variable may be used for no other purpose until the
CLOSE attribute has been assigned to it.

The File Input/Output functions are as follows:

%fvariable := FAPPEND <path_name_of_file>
%fvariable := FCREATE <path_name_of_file>
%fvariable := FOPEN <path_name_of_file>

%fvariable := FCLOSE

%fvariable := FSEEK <file_position>
%fvariable := FREAD/<maximum_bytes> %variable
%fvariable := FWRITE/<number_of_bytes> %variable
%fvariable := FNEWLINE
%fvariable := FSIZE %variable
%fvariable := FTRUNC

where %variable and %fvariable are the names of Scripta
variables. If %fvariable does not exist when a file
opening function is executed, it is created. %variable
will be created if necessary by FREAD but must pre-exist
for FWRITE. %fvariable is a variable of type FILE which
should be used for no other purpose; %variable is a
variable of type STRING which the FREAD and FWRITE
functions use as a buffer.

FAPPEND opens the named file and sets the initial file
position to end_of_file so that subsequent FWRITE and
FNEWLINE functions append to the file. FAPPEND fails if
the named file does not exist.

FCREATE creates the named file and sets the initial file
position to beginning_of_file (or end_of_file, they're the
same thing in an empty file). If the named file already
exists, it is emptied. i.e., all information within the
file is erased.

FOPEN opens the named file and sets the initial file
position to beginning_of_file so that subsequent FREAD
functions start reading data from the beginning of the
file.

FCLOSE closes the file, thus ending all record-level
access to the file until it is the subject of a further
file opening function.

FSEEK resets current file position to the specified
<file_position>. <file_position> must be specified as a
number of bytes relative to the beginning of the file.
i.e., the function 'FSEEK 0' positions at
beginning_of_file. This function is used for reading files
randomly. Some algorithm would be used for calculating the
position of a particular record within a file and then
FSEEK used to position the file at the start of the
required record, ready for a subsequent FREAD function.
Naturally, it may also be used for FWRITEing records at
random positions within the file.

FREAD has two distinct functions, depending on whether
/<maximum_bytes> is specified. If it is NOT specified then
FREAD copies data, starting from current file position,
into %variable. Copying stops when FREAD encounters
end_of_file, Ascii 26 (Ctrl/Z), Ascii 13 (Carriage Return)
or %variable is full (i.e., 200 bytes have been read).
Ascii 10 (Line Feed) characters following Ascii 13
characters are ignored.

The variable %ERROR is set to TRUE when end_of_file (or
Ascii 26) is encountered. Otherwise, it is set to FALSE.

If /<maximum_bytes> IS specified then it must represent a
value less than or equal to 200. FREAD will read the
specified number of bytes, starting at current file
position, into %variable. The actual number of bytes read
is stored in the system variable %SYSLEN. If the bytes
read do not contain binary data, or in particular do not
contain null (Ascii zero) characters, then the number of
bytes read may also be tested using the $LEN function. A
value less than <maximum_bytes> indicates that end_of_file
was reached before the required number of bytes could be
read. A value of zero indicates that end_of_file has been
reached.

This form of FREAD is used to read files of typically
fixed-length records, either serially, in which case
%SYSLEN=0 may be used to test for end_of_file, or
randomly, in which case FSEEK would be used to select a
particular record in the file and %SYSLEN=0 indicates that
the FSEEK moved current position to a point at or beyond
end_of_file. Values of %SYSLEN which are greater than zero
but less than <maximum_bytes> indicate that the final
record in the file has been read, and is under-sized. This
is usually indicative of a deeper error such as an invalid
FSEEK <file_position> algorithm.

FWRITE is used to write strings to the file specified by
%fvariable, beginning at current file position. FWRITE has
two distinct functions depending on whether
/<number_of_bytes> is supplied. If it is NOT supplied then
the whole of the current contents of %variable are
written, otherwise, the number of bytes specified is
written.

Scripta makes no check that the value of <number_of_bytes>
is valid (other than the fact that it must be less than or
equal to 200 - the maximum size of a STRING variable. This
is because the record being written may contain binary
data which could confuse Scripta if it included Ascii 0
(NUL) characters and cause $LEN to return an invalid
result.

The FNEWLINE function writes a Carriage Return/Line Feed
character pair to the file, starting at current position.

The FSIZE function sets %variable to the current size of
the file in bytes.

FTRUNC truncates the file to current file position. For
example:

          %handle := fopen "SOMEFILE.DAT"
          %handle := fseek 100
          %handle := ftrunc
          %handle := fclose

This fragment of script truncates the file SOMEFILE.DAT
to 100 bytes in size.

There are numerous examples of the use of record-level
file access commands in the scripts supplied with the
Scripta package.
