Synopsis:

       rec_num=db_first(db_handle,fieldnr/name,search_term)

Arguments:

       db_handle - The database handle

       fieldnr/name - the field number or field name of the index field

       search_term - The value to search for

Description:    This function carries out an index search on the index associated with the given fieldnr/name (which must have previously been opened with the db_ixopen() call).        

The db_first() function works in conjuction with the db_next() and db_prev() function calls to maintain an index pointer for a specific database handle that allows the calling task to search and step though an index in index key order.

If an exact match for search_term is found in the index then the index pointer will be positioned at that key and the record number of the corresponding record in the database table will be returned.         

If an exact match for the search_term is not found then the index pointer will be positioned in between keys in the index and the function will return record number 0 (to indicate that no exact match was found).        Calls to db_next() or db_prev() can then be used to step through the index keys in forward or reverse order from that point.

If a search is made for a index key value that is beyond then last key in the index then the index pointer will be positioned after the last key in the index.    A call to db_next() will then return 0 to indicate that the index pointer is beyond the end of the index,  whereas db_prev() will then return the last record in the index.

Similarly if a search is made for a key that is before the first entry in the index then the index pointer will be positioned prior to the first key in the index.    A call to db_prev() will then return 0, whereas a call to db_next() will return the first key in the index.

Note that calls to db_first(), db_next() and db_prev()  cannot be nested within a single task,   since only one index pointer is maintainted per task.    

Returns:   If an exact match is found then the record number of that match is returned.    If no exact match is found then the function will return 0 and the index pointer will be postitioned just before the next key that would match.           If an invalide db_handle or non index fieldnr/name is specified then the function will return a negative error code.