• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

dbmatches - find matching records in second table

SYNOPSIS

#include "db.h"

long dbmatches(Dbptr dbk, Dbptr dbt, Tbl **kpattern,
                 Tbl **tpattern, Hook **hookp, Tbl **tblp)

DESCRIPTION

dbmatches is the companion routine to dbjoin. Sometimes, you may not need to form a joined table; it may be more convenient or useful to find the set of records which match some input parameters. This is particularly true when either the matching parameters or the table to be matched against is dynamically changing. A view (join) is static once it has been formed.

dbk should specify a single record of some table (this could be the scratch record). dbt specifies a whole table (it might be the same table). kpattern and tpattern are patterns (lists of field names, expressions or ranges) on which the record specified by dbk is to be matched in the table specified by dbt.

Just as in dbjoin, these two patterns may be specified as null, or as Tbl *pointers which are initially zero. If the patterns are not specified, they are inferred from the primary and alternate keys of the respective tables.

The process of setting up to perform a match involves computing some intermediate results, among them an index. The routine requires a place to store this information, which is provided by hook. *hook should be set to zero at the first call to dbmatches. Each separate call to dbmatches should have its own hook; the hook minimizes initial computations between successive calls with the same input parameters (but different rows in the table for dbk, or perhaps an updated table dbt).

The returned list is a list of the record numbers which satisfy the match. It is the responsibility of the caller to free this list with the call:


        freetbl(tbl, 0) ;

The list is reallocated at every call to dbmatches.

RETURN VALUES

The return value is the number of matching records, or dbINVALID in the event of an error.

LIBRARY

$(DBLIBS)

SEE ALSO

hook(3)
dblist2subset(3)

BUGS AND CAVEATS

dbmatches relies on indexes, which are only partially dynamic. When records are added or deleted in the same process which holds an index on a table (is using dbmatches), that index is updated. However, changing a record with dbputv(3) or replacing a record with dbput(3) does not update the indexes. When other processes change the table, the index may become corrupt, but this is not recognized by dbmatches.

AUTHOR

Daniel Quinlan
Printer icon