OPEN for ISAM-A

OPEN #channel, filespec, mode, recnovar, fstatvar {,end'file} {, wait'record} {,wait'file} {,read'only}

Opens the file. (Note that while internally there may be multiple physical files, from BASIC, the combination of the data file and index is treated as a single file. Unlike old ISAM, there is no need or possibility of opening up additional index files.)

Also note that unlike the OPEN statements for random and ISAM files, there is no record size parameter. The actual data record size on disk is one byte larger (due to a control byte) than the logical record size specified in the file index. There is also no span'blocks parameter, because it is effectively always on—i.e. the records are contiguous without regard to disk block size.

ch (Num) [in]

an integer expression (>0) specifying the file channel which will be needed for subsequent I/O operations on the file. copied from random open.

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. copied from random open.

In ISAM-A, the specification is of a primary or secondary index (IDX) file. In the case of a primary index, the associated data (DAT) 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 DAT files.

mode (literal keyword) [in]

must be one of the following:

Open Mode	Meaning
ISAMP' INDEXED	Same as INDEXED but forces operation to be interpreted as an ISAM-A open rather than an ISAM open, regardless of the COMPIL mode. Otherwise the COMPIL mode will determine whether to assume old ISAM or ISAM-A.
ISAMP'INDEXED' EXCLUSIVE	Same as INDEXED'EXCLUSIVE but forces operation to be interpreted as an ISAM-A open rather than an ISAM 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 BASIC error 37 (file in use). See comment below this table.
INDEXED' EXCLUSIVE	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 BASIC error 37 (file in use).

Although the OPEN for ISAM-A syntax differs somewhat from the OPEN for ISAM 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.

recnovar (F6) [in]

holds the current record number. Normally, you never need to do anything explicitly with this variable since all operations are based on the index, but it will be set to the data record number after each successful index operation and is used as input by some record-level operations such as UPDATE'RECORD.

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. copied from random open. Also see the .RECNO(channel) dot function.

fstatvar (F6) [in]

set to indicate the status of most operations, from the following table:

Symbol	Value	Meaning
ISAM_NF	-3	Not found
ISAM_NA	-2	Not available (record locked)
ISAM_LT	-1	Key found which is less than specified key
ISAM_EQ	0	Key found equal to specified key
ISAM_OK	0	OK
ISAM_GT	1	Key found greater than specified key
ISAM_DK	2	Duplicate key error in CREATE’RECORD (if AF_ISAMNODUPERRS set)

The same limitations apply here as to recnovar above. Also see the .FSTAT(channel) dot function.

The remaining parameters are all optional modifiers and may be specified in any order:

Open Modifier	Meaning
end'file	Positions the internal index pointer at the end of the primary index, rather than at the beginning (so that a GET'PREV or FIND'PREV will return the last record in the index).
wait'record	If an attempt is made to read a locked record, the program will wait until the record is freed.
wait'file	Causes the OPEN operation to wait until the file is available (instead of returning error 37 if it is not).
read'only	Indicates that the file will only be accessed for read operations. Attempts to perform updates will fail with an error.