Reads the record indicated by the value of an arbitrary key (random read).
long cobfa_rdkey ( long fd, /* file descriptor */ long readflgs, /* read attribute */ char *recarea, /* record area */ const struct fa_keydesc *keydesc, /* Record key structure */ long keynum /* record key number */ );
Description
In the file indicated by the file descriptor <fd>, the record indicated by the value of the arbitrary key retained in the record area <recarea> is read. The record is stored in the record area <recarea>.
The read attribute <readflgs> includes the following two categories, which are associated by a logical OR. If omitted, default values are assigned (default: *).
Read mode
* | FA_EQUAL | Reads the record corresponding to the specified record key value. |
Record lock flag
FA_LOCK | Reads with lock. (READ WITH LOCK) | |
FA_NOLOCK | Reads with no lock. (READ WITH NO LOCK) |
The default of record lock flag is affected by lock mode specification when the file is opened. If the lock mode is automatic lock (FA_AUTOLOCK), the default is READ WITH LOCK (FA_LOCK). Otherwise, the default is READ WITH NO LOCK (FA_NOLOCK).
An arbitrary record key is specified with record key structure specification <keydesc>. For the struct fa_keydesc type, see "4.1.1 struct fa_keydesc".
If NULL is specified for this record key structure specification, record key number specification <keynum> is valid as an arbitrary record key. To use the primary record key, specify 1 for the record key number. To use an alternate record key, specify 2 or greater for the record key number. This value corresponds to the list of the order in which alternate record keys were declared when the indexed file was created. For the first alternate record key, specify 2. For the second alternate record key, specify 3. For the following alternate record keys, specify the corresponding numbers in the same way.
Execution Conditions
File Organization | Sequential file | - |
Record sequential file | - | |
Relative file | - | |
Indexed file | Executable | |
Open Mode | INPUT mode | Executable |
OUTPUT mode | - | |
I-O mode | Executable | |
EXTEND mode | - | |
Access Mode | Sequential | - |
Random | Executable | |
Dynamic | Executable |
Return Values
0: Successful | Function executed successfully. A code indicating the status may be set in the I-O status. |
-1: Failed | Function failed. To get extended error information, call the cobfa_errno or cobfa_stat functions |
Generated Status
Return value of cobfa_errno () | Return value of cobfa_stat () | ||
|---|---|---|---|
Successful | FA_ENOERR | 0 | Function executed successfully |
FA_ENOERR | 2 | The value of the reference key in the record that is read is equivalent to the value of the reference key in the next record | |
Failure (not all) (*) | FA_ENOTOPEN | 47 | The specified file is opened in a mode other than INPUT mode and I-O mode. Alternatively, an invalid file descriptor is specified |
FA_EBADACC | 90 | The file is opened with the file organization or access mode that does not allow this function to be executed | |
FA_EBADFLAG | 90 | The read mode not allowing execution of this function is specified. Alternatively, another flag specification is incorrect | |
FA_ENOREC | 23 | The record indicated by an arbitrary record key value does not exist | |
FA_EBADKEY | 90 | The specified record key structure or record key number is incorrect or does not exist | |
FA_ELOCKED | 99 | The record specified with the primary record key value has been locked | |
* : Typical status values are described above. For other values, see "Chapter 5 Error Number and I-O Status".
