_Rreadk() — Read a Record by Key
Format
#include <recio.h>
_RIOFB_T *_Rreadk(_RFILE *fp, void *buf, size_t size,
int opts, void *key, unsigned int keylen);
Language Level
ILE C Extension
Threadsafe
Yes
However, if the file pointer is passed among threads, the I/O feedback area is shared among those threads.
Description
The _Rreadk()
function
reads the record in the keyed access path that is currently being
used for the file that is associated with fp.
Up to size number of bytes are copied from
the record into buf (move mode only). If
the file is opened for updating, the _Rreadk()
function
locks the record positioned to unless __NO_LOCK is specified. You
must be processing the file using a keyed sequence path.
_Rreadk()
function.
- buf
- Points to the buffer where the data that is read is to be stored. If locate mode is used, this parameter must be set to NULL.
- size
- Specifies the number of bytes that are to be read and stored in buf. If locate mode is used, this parameter is ignored.
- key
- Points to the key to be used for reading.
- keylen
- Specifies the total length of the key to be used.
- opts
- Specifies the processing options for the file. Possible values
are:
- __DFT
- Default to __KEY_EQ.
- __KEY_EQ
- Positions to and reads the first record that has the specified key.
- __KEY_GE
- Positions to and reads the first record that has a key greater than or equal to the specified key.
- __KEY_GT
- Positions and reads to the first record that has a key greater than the specified key.
- __KEY_LE
- Positions to and reads the first record that has a key less than or equal to the specified key.
- __KEY_LT
- Positions to and reads the first record that has a key less than the specified key.
- __KEY_NEXTEQ
- Positions to and reads the next record that has a key equal to the key value at the current position. The key parameter is ignored.
- __KEY_NEXTUNQ
- Positions to and reads the next record with a unique key from the current position in the access path. The key parameter is ignored.
- __KEY_PREVEQ
- Positions to and reads the last record that has a key equal to the key value at the current position. The key parameter is ignored.
- __KEY_PREVUNQ
- Positions to and reads the previous record with a unique key from the current position in the access path. The key parameter is ignored.
- __NO_LOCK
- Do not lock the record for updating.
The positioning options are mutually exclusive.
- __KEY_NULL_MAP
- The NULL key map is to be considered when reading a record by key.
- __NO_LOCK
- The record that is positioned will not be locked.
The _Rreadk()
function
is valid for database and DDM files.
Return Value
The _Rreadk()
function
returns a pointer to the _RIOFB_T structure associated with fp.
If the _Rreadk()
operation
is successful the num_bytes field is set
to the number of bytes transferred from the system buffer to the user's
buffer (move mode) or the record length of the file (locate mode).
The key and rrn fields
will be updated. The key field will always contain the complete key
if a partial key is specified. When using record blocking with _Rreadk()
, only
one record is read into the block. Thus there are zero records remaining
in the block and the blk_count field of the _RIOFB_T structure will
be updated with 0. The blk_filled_by field is not applicable to _Rreadk()
and
is not updated. If the record specified by key cannot
be found, the num_bytes field is set to
zero or EOF. If you are reading a record by a partial key, then the
entire key is returned in the feedback structure. If it is unsuccessful,
the num_bytes field is set to a value less
than size and errno will be changed.
- Value
- Meaning
- EBADKEYLN
- The key length specified is not valid.
- ENOTREAD
- The file is not open for read operations.
- ETRUNC
- Truncation occurred on an I/O operation.
- EIOERROR
- A non-recoverable I/O error occurred.
- EIORECERR
- A recoverable I/O error occurred.
Example
#include <stdio.h>
#include <recio.h>
#include <stdlib.h>
int main(void)
{
_RFILE *fp;
_RIOFB_T *fb;
char buf[4];
/* Create a physical file */
system("CRTPF FILE(QTEMP/MY_FILE)");
/* Open the file for write */
if ( (fp = _Ropen("QTEMP/MY_FILE", "wr")) == NULL )
{
printf("open for write fails\n");
exit(1);
}
/* write some records into the file */
_Rwrite(fp, "KEY9", 4);
_Rwrite(fp, "KEY8", 4);
_Rwrite(fp, "KEY7", 4);
_Rwrite(fp, "KEY6", 4);
_Rwrite(fp, "KEY5", 4);
_Rwrite(fp, "KEY4", 4);
_Rwrite(fp, "KEY3", 4);
_Rwrite(fp, "KEY2", 4);
_Rwrite(fp, "KEY1", 4);
/* Close the file */
_Rclose(fp);
/* Open the file for read */
if ( (fp = _Ropen("QTEMP/MY_FILE", "rr")) == NULL )
{
printf("open for read fails\n");
exit(2);
}
/* Read the record with key KEY3 */
fb = _Rreadk(fp, buf, 4, __KEY_EQ, "KEY3", 4);
printf("record %d with value %4.4s\n", fb->rrn, buf);
/* Read the next record with key less than KEY3 */
fb = _Rreadk(fp, buf, 4, __KEY_LT, "KEY3", 4);
printf("record %d with value %4.4s\n", fb->rrn, buf);
/* Read the next record with key greater than KEY3 */
fb = _Rreadk(fp, buf, 4, __KEY_GT, "KEY3", 4);
printf("record %d with value %4.4s\n", fb->rrn, buf);
/* Read the next record with different key */
fb = _Rreadk(fp, buf, 4, __KEY_NEXTUNQ, "", 4);
printf("record %d with value %4.4s\n", fb->rrn, buf);
/* Close the file */
_Rclose(fp);
}
Related Information
- _Rreadd() — Read a Record by Relative Record Number
- _Rreadf() — Read the First Record
- _Rreadindv() — Read from an Invited Device
- _Rreadl() — Read the Last Record
- _Rreadn() — Read the Next Record
- _Rreadnc() — Read the Next Changed Record in a Subfile
- _Rreadp() — Read the Previous Record
- _Rreads() — Read the Same Record