DNUMDIX C-3

dnumidx - set significant fields for index query

An RMSfile may have one primary and several secondary keys defined for rapid searching of the RMSfile records. Each key can be composed of one to eight fields concatenated together. When values are supplied for each field of a key, the associated record, if any, can be found quickly using an index.

When only some of the fields in a key are known, the index searches can still be used. However, an exact match is not guaranteed in this case. There may be several records that match the partial key value. The important thing to remember is that only the beginning fields of an index may be used. You cannot, for example, search an index using the last of four fields in a key.

To accurately search an index using a partial key, three things must be done: select a key, specify the number of fields being used in that key, and read the records in index order. Call dseti(C-3) to specify the desired key. Call dnumidx to specify the desired number of fields.

Finally, call one of the index find functions (dfindi(C-3), dfindni(C-3), dfindpi(C-3), dfindm(C-3), dfindnm(C-3), dfindpm(C-3), or dfindlm(C-3) ) to return records from the RMSfile in index order starting at the given key value. The data buffer values must be checked after record is read to determine when enough data has been read (for 8-100 C/Base Functions example, dfindi only guarantees values equal to or greater than the key values specified).

n is the number of fields in the key that are significant. As stated before, this number means that the first n field(s) are significant.

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

dlopen(C-3), dopen(C-3), dseti(C-3) dfindi(C-3), dfindni(C-3), dfindpi(C-3), dfindm(C-3), dfindnm(C-3), dfindpm(C-3), dfindlm(C-3)

Dnumidx returns a value of -1 (BAD) if fcb is not a valid open file block pointer, if there is no current index, or if the number of fields parameter, n, is less than zero or greater than the number of fields in the index.