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

 

NAME

dbmatch_range, dbget_index, dbupdate_index, dbrecord - direct access to Datascope indexes

SYNOPSIS

#include "db.h" ;

int dbmatch_range(Dbptr dbk, Dbptr dbt,
                 Tbl **kpatternp, Tbl **tpatternp,
                 void **hookp, Dbindex **index, long *ns,
                 long *ne)

int dbget_index(Dbptr db, Tbl *pattern,
                 Dbindex **index)

int dbupdate_index(Dbindex *dbindex)

long dbrecord(Dbindex *dbindex, long j)

DESCRIPTION

dbjoin(3), dbmatches(3) and dbsort(3) implicitly use Datascope indexes. However, sometimes more direct access is desirable. These routines provide that access.

dbmatch_range corresponds rather closely to dbmatches(3), which returns a list of records which satisfy some join criteria. dbmatch_range returns the result of searching an index for records matching some join criteria. Instead of returning the record numbers, dbmatch_range returns the index, and the range of index records which appear to match the criteria. When the index is over a range (e.g., time::endtime), it may be that not all the corresponding records actually satisfy the criteria: each record must be individually tested. dbmatches(3) performs this test; dbmatch_range does not.

Index record numbers are converted to the corresponding table record numbers with the routine dbrecord -- provided with an index and a record number j, dbrecord returns the corresponding table record number.

While dbmatch_range returns the index as a side effect of searching, it is also possible to obtain the index directly using dbget_index. This is mostly useful when the table in question is changing, and must be repeatedly searched. dbsort(3) creates a sorted, but static, view of the table which is more convenient if the table is static. When the table is changing, however, you would need to continually recreate the sorted view to get an up-to-date result. On the other hand, the index is updated automatically if your process is adding or deleting records. If another process is adding records, you can use dbupdate_index to force your copy of the index to be updated. Note, however, that neither deleted records nor updated records are reflected in the index.

RETURN VALUES

dbmatch_range returns the number of records which match, or dbINVALID if an error occurs.

dbget_index returns 0 if a new index is created, 1 if an index is read from a saved file, or dbINVALID if the index could not be created.

dbupdate_index always returns 0.

dbrecord returns a record number, or dbINVALID if the input argument j is outside the range of index records.

LIBRARY

$(DBLIBS)

DIAGNOSTICS

BUGS AND CAVEATS

Because Datascope is based on a library which directly reads and writes the table files, indexes are not synchronized between processes.

The routines dbdelete(3), dbputv(3), and dbmark(3) do not update indexes. Only dbaddv(3) updates indexes, and it only updates indexes which have explicitly been opened.

Datascope saved indexes are platform specific; they contain binary representations of the index keys. Hence, you can't copy an index from a DEC machine, for example, to a Sun.

AUTHOR

Daniel Quinlan
Printer icon