PLOGHELP RECORD                                  Chris Mellish July 1983
                                Revised by Kathryn Seifert  October 1986

Library file providing indexed database facilities of DEC-10 Prolog

-- Introduction -------------------------------------------------------

LIBRARY RECORD provides the indexed database facilities of DEC System-10
Prolog. It enables an arbitrary non-circular term to be stored under a
particular "key". Once the same key is specified again, the term can be
retrieved relatively quickly, without a search being necessary among all
recorded terms. Apart from the extra "key" arguments, "record"ing a term
is very like "assert"ing it.

The programmer can provide any non-variable Prolog term to specify a
key. When a key specifier is a complex term, the functor of that term
(name + arity) is used as the key.

-- Loading the Library ------------------------------------------------

You can load the library with the directive

    :- library(record).

(see PLOGHELP * LIBRARY for a discussion of the library mechanism). You
should be aware however that loading the library re-initialises the
record database to be empty. If you load the library once, record some
data and then load it again, all your data will be lost. This can happen
by accident if the library is loaded in more than one file.

You can guard against this by using the "once-only" library mechanism,
uses/1, described in PLOGHELP * USES. The directive

    :- uses(record).

ensures that the library is loaded at most once.

-- List of Predicates Defined -----------------------------------------

record(Key, Term, Ref)
    Record the given Term under the specified Key. Key must be
    instantiated. As a result, Ref is instantiated to a special
    "reference" term identifying the recorded term. Term is recorded
    AFTER any terms already recorded under the same key so that it will
    be found last.

recorda(Key, Term, Ref)
    This is similar to 'record' except that the term is placed BEFORE
    any other terms already recorded under the Key so that it will be
    found first. This can be significantly faster than 'record' if there
    are large numbers of terms with the same key.

recordz(Key, Term, Ref)
    This is the same as 'record'; the suffix "z" emphasises that the
    term is recorded at the end of the list of terms with the same key.

recorded(Key, Term, Ref)
    Find a term matching Term under the key Key. Key must be
    instantiated. Ref will be instantiated to the "reference" of the
    recorded term. This goal will in general produce multiple solutions
    on backtracking.

instance(Ref, Term)
    Given the "reference" for some term, produces the term.  Ref should
    be instantiated.

erase(Ref)
    Erases the term whose reference is Ref.

record_init(Number)
    Resets the record data structures.  If you use this, all recorded
    terms will be lost. You should choose a number at least as big as
    the number of different keys which you wish to use.  The package
    starts up with 500.

record_purgeinit(Number).
    If you are worried about speed ... The recorded items are kept in
    lists, and the lists are copied only during 'recordz' or after
    Number 'recorda's (for a given key). The 'erase'd items are only
    removed during the copying.  If you do a lot of 'erase'ing and use
    only 'recorda', then the dead items will remain until a copying.
    'record_purgeinit' sets the number of 'recorda's before copying takes
    place, and it is possible to tune this to reduce the frequency and
    speed of garbage collections.  If this number is too small, GC will
    be frequent (because of the old copies); if it is too large, GC will
    be frequent (because of the large list).  The default number is 50.


-- RELATED DOCUMENTATION ----------------------------------------------

PLOGHELP * COMPATIBILITY
    DEC10 predicates not implemented in POPLOG Prolog

PLOGHELP * DEC1O
    Library file to change operator precedences to those of DEC10 Prolog

PLOGHELP * DATABASE
    Overview of Prolog database operations

--- C.all/plog/help/record ---------------------------------------------
--- Copyright University of Sussex 1988. All rights reserved. ----------