This is Rewritten June 2020
OPEN #ch, fspec, mode, recsiz, recnovar {,wait'file} {,wait'record} {,read'only} {,span'blocks}
The OPEN for ISAM syntax is identical to the OPEN for Random Access syntax except for the mode options. However, note that in the ISAM case, one OPEN statement may actually open two files, the index or IDX file, and the data or IDA file; see the fspec parameter for more details.
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.
In ISAM, the specification is of a primary or secondary index (IDX) file. In the case of a primary index, the associated data (IDA) file will also be opened at the same time and accessed via the same channel. To reduce confusion, the file extension (IDX) is normally omitted, since the operation will open both the IDX and IDA files. In the case of a secondary index, only the index file is opened.
mode (literal keyword) [in]
specifies the file access mode, and must be one of the following (case insensitive) compiler keywords:
Open Mode |
Meaning |
|---|---|
ISAM' |
Same as INDEXED but forces operation to be interpreted as an ISAM open rather than an ISAM-A open, regardless of the COMPIL mode. Otherwise the COMPIL mode will determine whether to assume old ISAM or ISAM-A. |
ISAM'INDEXED' |
Same as INDEXED'EXCLUSIVE but forces operation to be interpreted as an ISAM open rather than an ISAM-A open, regardless of the COMPIL mode. |
INDEXED |
Normal shared open. If file is already open by another user exclusively, job will wait (if the wait'record option specified) or receive ASB error 37 (file in use). See comment below this table. |
INDEXED' |
Open for exclusive use. If file is already open by another user in any mode, job will wait (if the wait'record option specified) or receive ASB error 37 (file in use). |
Although the OPEN for ISAM syntax differs somewhat from the OPEN for ISAM-A syntax, there is enough overlap that they can be confused if the INDEXED or INDEXED'EXCLUSIVE mode is specified without the ISAM' (or ISAMP' for ISAM-A) prefix. In the absences of the disambiguating prefix, the compiler will assume ISAM if the /I switch is specified, else it will assume ISAM-A.
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.
If opening a secondary index, specify the same record number variable as for the primary index.
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
