This routine opens an existing indexed file. If it is successful, the value in RETURN-CODE should be moved to a data item that is USAGE POINTER. This data item is passed as the open file handle to the other file handling routines. If it fails, RETURN-CODE is set to a NULL value. After the file is opened, the primary key is set as the current key of reference and is positioned at the beginning of the file.
The OPEN routine has three parameters, name, mode and l_parms.
is the name of the file to open. It must be null-terminated.
is one of the following values (defined in filesys.def):
| Finput | open for input only |
| Foutput | open for output only |
| Fio | open for input and output |
| Fextend | same as Foutput |
This routine only opens already existing files. If the file does not exist, the routine fails, even when opening with mode Foutput.
Foutput does not delete the current file (this is different from the OPEN OUTPUT verb in COBOL).
Mode may furthermore have one of the following flags added to it to indicate file locking options (defined in filesys.def):
| Fread_lock | locks file against other updaters |
| Fwrite_lock | locks file against all others |
| Fmass_update | same as Fwrite_lock |
| Ftrans | extended locking rules for transaction management |
Some file systems cannot support the Fread_lock option correctly. For these systems, the setting of the external variable F_UPGRADE_RLOCK determines what happens. If this variable is set to the default, then the Fread_lock setting is treated as a normal open (no file locking). If this variable is non-zero, then the Fread_lock setting is treated as Fwrite_lock instead.
A few file systems do not support any form of file locking. If locking is requested on one of these file systems, the open proceeds as if file locking were not specified, but the external variable F-ERRNO is set to W_NO_SUPPORT. This is also returned for file systems that cannot support multiple record locks when Fmulti_lock is specified.
If Fmass_update is used, then the file system is also requested to emphasize speed of updates over file security.
Additionally, Fmulti_lock may be also added to mode to request that more than one record lock be maintained in the file by this process. If this option is not specified, then any I/O operation on the file will first release any currently locked record. This results in only one record lock being set in the file at any time. When this option is used, locked records are released only when the file is closed or when the UNLOCK routine is called.
points to a null-terminated string that describes the key structure for the file. The l_parms parameter is the same as the l_parms parameter passed when using the MAKE op-code. This parameter is a string that contains three comma-separated numbers. These values are (in order):
| 1 | the maximum record size |
| 2 | the minimum record size |
| 3 | the number of keys for the file. |
If the maximum record size does not match the minimum record size, then variable sized records are implied. This parameter is not used by all file systems, but is supplied for those file systems that cannot determine these values on their own.