XOPEN for ISAM-A

Updated July 2021

XOPEN #ch, fspec$, mode, recsiz {, flags}

This is equivalent to the traditional OPEN statement for ISAM files, except:

• OPEN eliminates the implicit connection between the fstatvar and recnovar variables normally specified in the OPEN, and the file access statements. The recnovar and fstatvar parameters are eliminated.

• XOPEN allows for the various flags (WAIT'RECORD, WAIT'FILE, END'FILE,...) which must normally be specified as literals to the compiler to instead be evaluated at runtime.

Parameters

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]

specifies the file access mode, and must be one of the following (case insensitive) compiler keywords:

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).

flags (B,4 or numeric expression) [in]

flags optionally specifies zero or more of the following modifiers:

Symbol	Value	Modifiers*
FDVF_EXCLUSIVE	&h0800	Convert INDEXED to INDEXED'EXCLUSIVE
FDVF_READONLY	&h1000	READ'ONLY
FDVF_END_FILE	&h2000	END'FILE
FDVF_W_RECORD	&h4000	WAIT'RECORD
FDVF_W_FILE	&h8000	WAIT'FILE
Definition file: ashinc:addsfdv.def

* These are the literal file OPEN modifiers that can be tacked on to the end of an ISAM-A OPEN statement.

Example

This example illustrates a generic Open function for ISAM-A files. Note that the mode parameter is hard-coded as ISAMP'INDEXED, but the flags parameter allows the possibility of upgrading that to exclusive (via the FDVF_EXCLUSIVE flag). This function checks if the file channel is already open and does nothing if it is, assuming that the specified channel matches the fspec).

Function Fn'Open'ISAMA(ch as b2:inputonly, fspec$ as s260:inputonly, recsiz as b2:inputonly, flags as b4:inputonly) as i4

if ch # 0 then ! if a non-zero channel specified

if eof(ch) = -1 then ! and it's not already open

xopen #ch, fspec$, ISAMP'INDEXED, recsiz, flags

endif

.fn = ch

EndFunction

A typical call might look like...

if Fn'Open'ISAMA(ch=1234, fspec$="MYFILE", recsiz=128, flags= FDVF_EXCLUSIVE+FDVF_W'FILE) > 0 then

get #ch, isam'key(0) = mykey$, myrec