XOPEN for ISAM
Updated July 2021
XOPEN #ch, fspec$, mode, recsiz {, flags}
XOPEN is an alternative to the traditional OPEN statement, offering the following advantages:
| • | Replacement of the literal compiler keywords (e.g. WAIT'RECORD) with a flexible flags parameter, allowing a single generic, parameterized, XOPEN statement to be used for all variations. |
| • | Elimination of the requirement for the recnovar to remain in scope, by eliminating it entirely. Instead, you can specify the record number explicitly using the XREAD, XWRITE, XUNLOKR or SET'RECNO statements. |
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). |
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.
flags (B,4 or numeric expression) [in]
flags optionally specifies zero or more of the following modifiers:
Symbol |
Value |
Meaning |
|---|---|---|
FDVF_FORCED |
&h0010 |
Convert RANDOM to RANDOM'FORCED (shared) |
FDVF_EXCLUSIVE |
&h0800 |
Convert INDEXED to INDEXED'EXCLUSIVE |
FDVF_READONLY |
&h1000 |
READONLY |
FDVF_SPANBLOCKS |
&h2000 |
SPAN'BLOCKS |
FDVF_W_RECORD |
&h4000 |
WAIT'RECORD |
FDVF_W_FILE |
&h8000 |
WAIT'FILE |
Definition file: ashinc:addsfdv.def |
||
Note that if flags is expressed as a variable, it must be of type B,4. Since flags occupies the same position as recnovar in the traditional OPEN statement, requiring it to be of type B,4 here reduces the chance of accidentally confusing the two statements in your coding.
Example
if Fn'Open'ISAM(ch=1234, fspec$="MYFILE", recsiz=128, flags= FDVF_EXCLUSIVE+FDVF_W'FILE) > 0 then
isam #ch, 1, mykey$
...
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$, ISAM'INDEXED, recsiz, flags
endif
endif
.fn = ch
EndFunction
The above function could easily be upgraded to trap errors and deal file locking conflicts, including logging, user interfacing, etc., allowing you to implement all of that logic in a single place with more modularity than would otherwise be possible with the traditional OPEN statement.
See Also
