ILE C/C++ Run-Time Library Functions
Format
#include <recio.h>
_RIOFB_T *_Rlocate(_RFILE *fp, void *key, int klen_rrn, int opts);
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 _Rlocate() function positions to the record in the file
associated with fp and specified by the key,
klen_rrn and opts parameters. The
_Rlocate() function locks the record specified by the
key, klen_rrn and opts parameters unless
__NO_LOCK is specified.
- Note:
- The key parameter string must be EBCIDIC, even if the
program is compiled using LOCALETYPE(*LOCALEUTF).
The _Rlocate() function is valid for database and DDM files
that are opened with the _Ropen() function. The following
are valid parameters of the _Rlocate()function.
- key
- Points to a string containing the key fields to be used for
positioning.
- klen_rrn
- Specifies the length of the key that is used if positioning by key or the
relative record number if positioning by relative record number.
- opts
- Specifies positioning options to be used for the locate operation.
The possible macros are:
- __DFT
- Default to __KEY_EQ and lock the record for update if the file is
open for updating.
- __END
- Positions to just after the last record in a file. There is no
record that is associated with this position.
- __END_FRC
- Positions to just after the last record in a file. All buffered
changes are made permanent. There is no record that is associated with
this position.
- __FIRST
- Positions to the first record in the access path that is currently being
used by fp. The key parameter is ignored.
- __KEY_EQ
- Positions to the first record with the specified key.
- __KEY_GE
- Positions to the first record that has a key greater than or equal to the
specified key.
- __KEY_GT
- Positions to the first record that has a key greater than the specified
key.
- __KEY_LE
- Positions to the first record that has a key less than or equal to the
specified key.
- __KEY_LT
- Positions to the first record that has a key less than the specified
key.
- __KEY_NEXTEQ
- Positions to the next record that has a key equal to the key value with a
length of klen_rrn, at the current position. The
key parameter is ignored.
- __KEY_NEXTUNQ
- Positions to the next record with a unique key from the current position
in the access path. The key parameter is ignored.
- __KEY_PREVEQ
- Positions to the previous record with a key equal to the key value with a
length of klen_rrn, at the current position. The
key parameter is ignored.
- __KEY_PREVUNQ
- Positions to the previous record with a unique key from the current
position in the access path. The key parameter is
ignored.
- __LAST
- Positions to the last record in the access path that is currently being
used by fp. The key parameter is ignored.
- __NEXT
- Positions to the next record in the access path that is currently being
used by fp. The key parameter is ignored.
- __PREVIOUS
- Positions to the previous record in the access path that is currently
being used by fp. The key parameter is
ignored.
- __RRN_EQ
- Positions to the record that has the relative record number specified on
the klen_rrn parameter.
- __START
- Positions to just before the first record in the file. There is no
record that is associated with this position.
- __START_FRC
- Positions to just before the first record in a file. There is no
record that is associated with this position. All buffered changes are
made permanent.
- __DATA_ONLY
- Positions to data records only. Deleted records will be
ignored.
- __KEY_NULL_MAP
- The NULL key map is to be considered when locating to a record by
key.
- __NO_LOCK
- The record that is positioned will not be locked.
- __NO_POSITION
- The position of the file is not changed, but the located record will be
locked if the file is open for update.
- __PRIOR
- Positions to just before the requested record.
If you specify the start and end options (__START,
__START_FRC, __END or __END_FRC) with any other
options, the other options are ignored.
If you are positioned to __START or __END and perform a
_Rreads operation, errno is set to EIOERROR.
Return Value
The _Rlocate() function returns a pointer to the
_RIOFB_T structure associated with fp. If the
_Rlocate() operation is successful, the num_bytes field
contains 1. If __START, __START_FRC, _END or
__END_FRC are specified, the num_bytes field is set to EOF.
If the _Rlocate() operation is unsuccessful, the num_bytes
field contains zero. The key and rrn fields are
updated, and the key field will contain the complete key even if a
partial key is specified.
The value of errno may be set to:
Table 5.
Value
| Meaning
|
EBADKEYLN
| The key length that is specified is not valid.
|
ENOTREAD
| The file is not open for read operations
|
EIOERROR
| A non-recoverable I/O error occurred.
|
EIORECERR
| A recoverable I/O error occurred.
|
See Table 12 and Table 14 for errno settings.
Example that uses _Rlocate()
#include <stdio.h>
#include <stdlib.h>
#include <recio.h>
int main(void)
{
_RFILE *in;
char new_purchase[21] = "PEAR 1002022244";
/* Open the file for processing in keyed sequence. */
if ( (in = _Ropen("MYLIB/T1677RD4", "rr+, arrseq=N")) == NULL )
{
printf("Open failed\n");
exit(1);
};
/* Update the first record in the keyed sequence. */
_Rlocate(in, NULL, 0, __FIRST);
_Rupdate(in, new_purchase, 20);
/* Force the end of data. */
_Rfeod(in);
_Rclose(in);
}
Related Information
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.