FOpen Function (ROM Call 0x3DE)

AMS 2.00 or higher files.h

unsigned short FOpen (const char *fileName, FILES *fsPtr, unsigned short mode, const char *typeName);

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_READThe file must exist and can only be read.
FM_WRITEOpen the file for writing and erase its contents. Create the file if it does not exist.
FM_APPENDIf 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_OKThe file was opened for the specified mode.
FS_ERRORThe 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_NAMEfileName is invalid.
FS_MEMORYNot 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