 |
FOpen |
Function (ROM Call 0x3DE) |
Open a file for a specific mode.
FOpen opens the file fileName for the mode mode. fileName is not a tokenized variable name (as required by the symbol
table code), but rather a normal zero-terminated C string of characters. It must not be a reserved
name. If fileName does not contain a folder name, the file will be stored in (or read from)
the current folder. Internally, files are stored as custom (third-party) data-type files
(OTH_TAG). They will show up to the user in the VAR-LINK screen
as the type specified when the file was opened (up to four letters).
When a file is opened with FOpen in FM_WRITE or FM_APPEND mode,
the associated variable is locked and inaccessible by any other routines in
the system. It must be closed with FClose to return the variable to a not-in-use mode,
to write the file type and the OTH_TAG, and to close
the associated buffer. For files opened in FM_READ mode, the call to FClose
will merely update the mode of the file in the FILES structure to closed and
clear the associated error status.
There is no separate mode to open a file for both reading and writing.
However, if a file is opened in FM_APPEND mode, the contents of the file
are not erased and the file may be subsequently positioned to any location
in the file (random access) and either read from or written to.
For all access modes, the given name must not be a system variable. For
FM_READ and FM_APPEND the name must correspond to an existing file of a custom data-type. For
FM_WRITE the file must either not exist or correspond to a file of a custom
data-type which is not locked or marked in-use.
Note that for files in read mode, FClose merely updates the
fsPtr->fileMode field in the FILES structure to indicate it is closed. For write mode, it must be
called to update information in the file needed by the system. While a file is
in write mode, it is marked as in-use so that no other application, nor the
system itself, will try to access it (it will not be visible in the VAR-LINK screen
either). Files in write or append mode may be accessed randomly by
using FSetPos.
Note: Any number of files may be simultaneously opened in read mode. If multiple
files are opened simultaneously in write (or append) mode, all but the
first file must already exist before they are opened. Use the FCreate routine if
they need to be created as empty files before they are opened with FOpen.
typeName must point to a normal (non-tokenized) zero-terminated C string of at most four characters
which describes the file type (FS_ERROR is returned
if it does not). If there is an existing file with the
same name as fileName, the types must match.
fsPtr is a pointer to a structure of type FILES.
The parameter mode can be one of the following commands, as described in the fileMode enum:
FM_READ | The file must exist and can only be read. |
FM_WRITE | Open the file for writing and erase its contents. Create the file if it does not exist. |
FM_APPEND | If the file exists, open it for writing at the end of the file. If it does not exist, then create it and open it for writing. |
FOpen returns one of the following values as described in the FileStatusEnum enum:
FS_OK | The file was opened for the specified mode. |
FS_ERROR | The file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type, or typeName may be invalid.) |
FS_BAD_NAME | fileName is invalid. |
FS_MEMORY | Not enough memory. |
The return value is also stored in fsPtr->fileStatus in the FILES structure.
The FILES pointer fsPtr may then be used in subsequent file routines.
This routine may cause heap compression or invalidate any current HSyms.
Uses: ER_catch, ER_success, HToESI, memset, strcmp, strlen, ROM Call 0x3E8, TokenizeName, DerefSym, VarRecall, VarStore
Used by: FAccess, FCreate, FType
See also: FAccess, FClose, FRead, FGetC, FSetPos, FStatus, FWrite, FPutC