DFINDM C-3


NAME



dfindm - find first matching record using secondary index

SYNOPSIS



#include

rno_t dfindm (buffer, fcb)
char *buffer;
DFILE *fcb;

DESCRIPTION



Dfindm finds the first record with field values equal to the
beginning field values placed in the data buffer.

An RMSfile may have several secondary indexes associated with it.
These are used to retrieve records by other than the primary key
value. Before dfindm is called, the dseti(C-3) function must be
called to select the secondary index to be used. The selected
secondary index has between one and eight fields associated with
it. The search values for the desired secondary index fields must
be stored in buffer before calling dfindm. If dnumidx(C-3) has
been called prior to this function,only the first n fields of the
current index are compared; otherwise, all fields of the current
index are compared.

Dfindm returns into the buffer the first record that contains
secondary field values equal to the field values passed in
buffer. Dfindm also saves the current position in the secondary
index, and additional records that match the field values may be
fetched with the dfindnm(C-3) function. Additionally, records may
be read in secondary key order with the dfindni(C-3) function.

Fcb is the file block pointer returned by dlopen(C-3) or
dopen(C-3).

The returned record number may be saved and used on a subsequent
call to dread(C-3).

All character positions in the primary key field are used in
determining the key value. The function strncpy is recommended
for storing string key values in buffer.

SEE ALSO



dlopen(C-3), dopen(C-3), dseti(C-3), dfindi(C-3),
dfindnm(C-3), dread(C-3), strncpy(3)
Chapter 4, RMS Programming Guide

DIAGNOSTICS




Dfindm returns a value of BAD (-1) if an I/O error occurred or if
there is no record that contains field values equal to the
beginning values passed in buffer. If no record is found, the
contents of buffer are undefined.