Figure 43–5. open (GENERIC)
PROCEDURE open (PRODUCES POINTER(textFile) f;
PRODUCES OPTIONAL STRING msg);
PROCEDURE open (PRODUCES POINTER(dataFile) f;
PRODUCES OPTIONAL STRING msg);
open is used to open a file, i.e., to make the file available for input and/or output. The predeclared CLASSes textFile and dataFile are explained in Section 22.2.
A file with the name fileName is opened in accordance with the bits specified in openBits. If the file is successfully opened, a POINTER to the file is produced in f (which is used for later access to the file) and the open PROCEDURE returns TRUE. If the file is not successfully opened (and errorOK is set), f is set to NULLPOINTER, msg is set to be an error message, and the PROCEDURE returns FALSE.
43.5.1. File Names
It is an error if fileName is the null STRING
(unless the prompt bit is set in openBits).
The names of files passed to open may be surrounded by double quote characters. This simplifies the processing of quoted file names parsed from command lines (see Section 42.12).
The double quote character is not special unless it occurs at the beginning of the file name. An error message is issued if a file name starts with an unmatched double quote, or if extraneous text follows a closing quote. For example:
|File Name Passed to open||File Name Used|
|abc def||abc def|
|"abc def"||abc def|
Note that it is not necessary to quote a file name just because it contains blank characters.
MAINSAIL does not handle files whose real names (e.g., as known
to the operating system) contain a double quote character; the
treatment of such files is undefined.
For a description of the treatment of carriage returns in
a text file, see Section 39.1.1.
If random is specified, but neither
input nor output, then both input
and output are assumed. If output
is specified, but not random, then
create is assumed. That is, a
sequential file opened for output has to
be a file that does not already exist; specifying create would
be redundant information.
The permissible combinations of input, output,
random, and create
(after the default rules have been applied) are:
The BITS constants below
are valid for openBits:
Create a new file. If this bit is not set, it is an error
if the file does not already exist.
Allow random access. If this bit is not set, it is an error
to attempt to call relPos or setPos for the file.
This bit should also be set if the same file is to be closed
and reopened for random access in the future.
Allow read access.
Allow write access.
fileName is really a prompt to be written to logFile.
After writing the prompt, read the real file name from
Each implementation has a null character that is
normally discarded when read from a text file. On many
systems, carriage return is also discarded by default.
keepNul means do not discard any null characters or
carriage returns from this file. delete
Delete the file when it is closed.
Permission is normally requested from cmdFile
when an existing file is deleted or altered.
alterOK suppresses the request for permission
and performs the operation silently (unless an
error occurs and errorOK is not set).
If the operating system is unable to carry out
the open as requested, an error message is by
default written to logFile and a new file name
read from cmdFile. If errorOK is set, the error
message is suppressed, f is set to NULLPOINTER,
and open returns FALSE.
Do not allocate a buffer for the file (this bit
may be ignored for some file types, e.g., memory
files, which are necessarily buffered). Input
and output must be performed by means of
$pageRead, $pageWrite, $storageUnitRead,
$characterWrite, fldRead (textFile form only)
and the MAINSAIL Structure Blaster. The
PROCEDUREs setPos, getPos, relPos,
and close may
also be called for an unbuffered file, but the
use of other I/O PROCEDUREs (e.g., read, write,
scan, etc.) generates an error. If large
amounts of data are to be read or written at
once, the use of the $unbuffered bit may result
in a substantial speed increase for I/O. If the
file is being created, the random bit should be
set if the $unbuffered bit is set to ensure that
unbuffered I/O can be performed on the file.
Open the file for PDF I/O.
PDF I/O is described in detail in Chapter 26.
Do not look up logical names or use a
searchpath; use the file name specified.
create output (sequential)
create random output
random input and output
create random input and output
43.5.3. Error Behavior
If errorOK is not set and the file cannot be opened,
an error message is issued and the user may type either:
For a description of the treatment of carriage returns in a text file, see Section 39.1.1.
If random is specified, but neither input nor output, then both input and output are assumed. If output is specified, but not random, then create is assumed. That is, a sequential file opened for output has to be a file that does not already exist; specifying create would be redundant information.
The permissible combinations of input, output, random, and create (after the default rules have been applied) are:
Example 43–6. Use of open
Open the file named notes for text input (it must already exist). Use f for subsequent references to the file.
The prompt is written to logFile, and then a file name is read from cmdFile. A new file is created for random text output. Only write access is allowed. If creation of the new file requires that an existing file be deleted, permission must be obtained before proceeding.
If errorOK is set and the file cannot be opened, open returns FALSE and sets the msg parameter to a STRING that describes the error. The first line of the error STRING is one of the STRINGs in Table 43–7. The error STRING may contain additional lines that give more detailed information about why the open failed.
An identifier is defined for the text of each possible first line of msg. When testing for one of these STRINGs, always use the predefined identifiers, since the text of the STRINGs is subject to change.
Note: XIDAK reserves the right to add new values to this list.
Note: The value of the msg parameter is undefined when open returns successfully.
|Temporary feature: subject to change|
In MAINSAIL Version 12.16 and earlier, although MAINSAIL expanded operating system environment variables that appeared within file names, MAINSAIL did not record the result of that expansion in the name field of the file record. Thus, after the call:
f.name was $MYDIR/myfile.msl. Starting with MAINSAIL Version 14.10, however, the name field of the file record reflects the expansion of environment variables, so that if MYDIR is defined as /usr/foo, f.name would be "/usr/foo/myfile.msl".
When the MAINSAIL compiler produces an intmod, it records the name of each source file that contributed to the intmod in the intmod itself. The name recorded comes from the name field of the file record. This is also the name of the source file that MAINDEBUG tries to open when it uses an intmod.
Thus, under Version 12.16, if you compiled $MYDIR/myfile.msl debuggable, the debugger later opened the file $MYDIR/myfile.msl. If you wanted to move your source directory, say, from /usr/foo to /usr/bar, you could just do:
setenv MYDIR /usr/bar
and the debugger would continue to find your source files.
In Version 14.10 and later, however, if you compile $MYDIR/myfile.msl debuggable, the name recorded in the intmod is expanded to /usr/foo/myfile.msl. If you moved your sources to /usr/bar and changed MYDIR as above, the debugger would still be unable to find your source files. You could get around this by issuing the MAINEX subcommand:
SEARCHPATH /usr/foo/* /usr/bar/*
However, some users find the 12.16 behavior more convenient. XIDAK has introduced a temporary feature to make the current version of MAINSAIL behave like Version 12.16 in its treatment of environment variables in file names.
If the STRING global symbol saveUnexpandedFileNames has the value "TRUE" when a file is opened, any operating-system-dependent transformations of the file name (such as the expansion of environment variables, or on UNIX, of the ~userName shorthand for a user's home directory) are not reflected in the name field of the file record. Thus, you can set this symbol (e.g., with:
GLOBALSYMBOL saveUnexpandedFileNames TRUE
in the site.cmd file on the MAINSAIL directory) when compiling MODULEs debuggable to ensure that the debugger follows Version 12.16 rules to find source files.
If saveUnexpandedFileNames is not defined or is defined to be a STRING other than "TRUE", MAINSAIL records operating-system-dependent changes to a file name in the file's name field.
In a future version of MAINSAIL, this mechanism is likely to be replaced by more general mechanisms for specifying how the debugger is to search for source files.