8.S. Tables of Operations
9. Sequential Input and Output
9.3. Opening, Closing, Reading, and Writing Files
Before the data in a file may be accessed, the file must be "open". A file may be opened by calling the system procedure "open". "open" is a generic procedure that may operate on either text or data files.
When a program finishes accessing the data in a file, it must close it by calling the system procedure "close". If a program fails to close a file, the file is closed when MAINSAIL exits (provided MAINSAIL exits normally). However, since closing a file may free up memory or other resources associated with an open file, it is a good idea to close files as soon as you are done with them.
When "open" is called, a program must specify whether it intends to use the file for input or for output (or both; see Section 10.11). "write" may be called only for files open for output, "read"
only for files open for input.
The predeclared files "logFile" and "cmdFile" are text files that are opened before a user program gains control. logFile is opened for output, cmdFile for input.
The declarations of "open" and "close" are shown in Figure 9.3-1. The file Iff' passed to "open"
is the variable declared by the user (or predeclared by MAINSAIL) that is used in subsequent calls to "read", "write", and "close". The fileName parameter is the name of the file. The openBits parameter specifies the type of access desired for the file; some of the applicable predefined bits constants are "input", "create", "output", and "errorOK". The fileSize parameter is rarely specified and can be ignored.
A program that opens a text file and copies the contents to 10gFile is shown in Example 9.3-2.
Note the use of the "!" in specifying both the "input" and "errorOK" bits to "open". The openBits parameter could have been written "input lOR errorOK"; however, when several named bits are specified in a bits parameter, it is customary to use "!" rather than "lOR". The presence of the errorOK bit indicates that if "open" is unable to process the named file, it should return false. If errorOK is not specified, "open" writes a message to 10gFile indicating that the named file cannot be opened, and prompts repeatedly for a new file name until a file is named that can be opened; if errorOK is not specified, "open" always returns true.
When the end of a text file is reached, "read" fails, since there are no more strings to read from the file. "$gotValue(t)" returns false if the last attempted read from f failed, true otherwise.
$gotValue is the usual way to test for end-of-file. The $gotValue test is not precise; see Section 10.13.
# open is not really declared twice; i t is
# actually a generic procedure.
BOOLEAN PROCEDURE open
(PRODUCES POINTER (textFile) STRING
BITS
OPTIONAL LONG INTEGER BOOLEAN PROCEDURE open
(PRODUCES POINTER (dataFile) STRING
BITS
OPTIONAL LONG INTEGER
f;
PROCEDURE close (MODIFIES POINTER(file) f;
OPTIONAL BITS closeBits)
Figure 9.3-1. The Declarations of "open" and "close"
Example 9.3-3 shows a program that reads a data file, processes it, and writes the result to another data file. The input data file contains a series of sets of long real numbers to be added.
Each set is preceded by an integer specifying the number of long reals. The program terminates when it finds a set with zero long reals. Since "read" returns a Zero of the
appropriate data type whenever the end of file has been reached, this ensures that the program will terminate if it accidentally reads beyond the end of the input file.
Example 9.3-3 illustrates the use of the open bits "create" and "prompt". "prompt" specifies that the fileName parameter is actually a prompt to be written to 10gFile; the real file name is then read from cmdFile. The "create" bit must be specified when opening a new file; the
"output" bit must be specified whenever the "create" bit is specified.
Example 9.3-4 shows what an input file to the program of Example 9.3-3 might look like, and the resulting output file. The data files are shown diagrammatically because they would presumably be illegible if interpreted as text files. The amount of storage occupied by each data item is not proportional to the space allotted to it in the diagram; all integers take up the number of storage units required to represent an integer, and all long reals the number of storage units required to represent a long real. These numbers are dependent on the system on which MAINSAIL is running; see Section 10.11.
BEGIN "COpFil"
INITIAL PROCEDURE;
BEGIN STRING s;
POINTER (textFile) inputFile;
write(logFile,"Input file name: "); read(cmdFile,s);
IF NOT open(inputFile,s,input!errorOK) THENB
*
Open for input access; return false if can't open write(logFile,"Unable to open file ",s,eol);RETURN END;
*
"RETURN" terminates execution of the*
initial procedure, and consequently of*
the program DOB read(inputFile,s);IF NOT $gotValue(s) THEN DONE;
*
Have we reached the end of inputFile?write (logFile,s,eol) END;
close(inputFile);
END;
END "copFil"
Example 9.3-2. Copying a Text File to logFile
BEGIN "nums"
INITIAL PROCEDURE;
BEGIN
INTEGER i,count;
LONG REAL r,sum;
POINTER (dataFile) inFile,outFile;
open(inFile,"Input file: ",prompt!input);
open(outFile,"Output file: ",create!prompt!output);
*
Create a new file for output accessDOB read(inFile,count); IF NOT count THEN DONE;
sum := O.OL;
FOR i := 1 UPTO count DOB
read(inFile,r); sum := sum + rEND;
write (outFile, sum) END;
close(inFile); close(outFile);
write(logFile,"File processed." & eol);
END;
END "nums"
Example 9.3-3. The Use of Data Files
+-- start of input file
V
+---+---+---+---+---+---+---+---+
I 3 I 6. OL I 4. 2L I -1.8L I 2 I 1.lL I 9. 04L I 0 I
+---+---+---+---+---+---+---+---+
+-- start of output file I
v
+---+---+ '
I 8. 4L I 10.14L I