DFINDM C-3

NAME

dfindm - find first matching record using secondary index

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.

dlopen(C-3), dopen(C-3), dseti(C-3), dfindi(C-3),

dfindnm(C-3), dread(C-3), strncpy(C-3)

Chapter 4,

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.