Rewritten June 2020
OPEN #ch, fspec, mode, recsiz, recnovar {,wait'file} {,wait'record} {,read'only} {,span'blocks}
Parameters
ch (Num) [in]
an integer expression (>0) specifying the file channel which will be needed for subsequent I/O operations on the file.
fspec (String) [in]
string expression containing file specification, in native or AMOS syntax. May contain embedded %env% variables, e.g. "%temp%\myfile.dat". If no directory information is included, the search path consists of the current directory, followed by the [p,0] directory.
mode (literal keyword) [in]
specifies the file access mode, and must be one of the following (case insensitive) compiler keywords:
Symbol |
Description |
|---|---|
RANDOM |
When LOKSER enabled, requests exclusive access; otherwise same as RANDOM'FORCED |
RANDOM'FORCED |
Shared access |
recsiz (Num) [in]
integer expression specifying the record size—i.e. the number of bytes transferred in each subsequent READ and WRITE operations. See span'blocks below.
recnovar (F6) [in]
holds the record number for record-level operations such as XREAD, XWRITE, XUNLOKR that require one. This variable must be F,6. It gets linked by address to the file's entry in the open file table, and thus must remain in scope for the duration of the open file channel. If this is not possible, for example, across function or SBX calls, you can manually reassign it to another variable using MX_FLSET. Or, to eliminate this limitation entirely, use XOPEN instead of OPEN.
wait'file, wait'record and read'only (literal keyword) [in]
have meaning only when LOKSER is enabled, otherwise they are ignored. wait'file causes the statement to wait until access can be granted. If requesting exclusive access, no other process may have the file open except for read'only. If requesting shared access, no other process can have the file open exclusively. Otherwise, if access cannot be granted, error 37 will be returned. wait'record causes READ operations to wait if the requested record is locked, otherwise error 38 is returned. read'only disables LOKSER—and WRITE operations—for this file access session, and is useful when you're just going to be reading from the file and it isn't critical that the file isn't modified during the read operations. Also see Xcall ASFLAG for a way to achieve this effect without using the BASICplus compiler extensions. See History.
span'blocks (literal keyword) [in]
disables 512-byte blocking. This is a historical hold-over, which performed random file access in 512 byte blocks and did not allow logical records to be split between two blocks. If the record size didn't divide evenly into 512, the remaining number of bytes would simply be unused at the end of each 512 byte block. In the worst case, a record size of 257 bytes would result in 255 out of every 512 bytes wasted. In span'blocks mode, records are adjacent with no wasted space between them and no consideration for how they map onto physical disk "blocks". 512-byte blocking remains the default, for compatibility with existing files, but serves no useful purpose in the modern world and is therefore deprecated. span'blocks is always recommended, except when compatibility with older file layouts is required. span'blocks is automatic when the record size is greater than 512.
See Also
History
2020 July, A-Shell 6.5.1688: LOKSER wait'file and wait'record enhancement: when waiting for more than five seconds for access to a file or record, a status message will now display on the bottom unshifted status line of the main terminal window indicating the name of the file, access type, and elapsed wait time.
