Database References

A database reference is a term that uniquely identifies a clause or recorded term (see ref-mdb-idb) in the database. Database references are provided only to increase efficiency in programs that access the database in complex ways. Use of a database reference to a clause can save repeated searches using clause/2. However, it does not normally pay to access a clause via a database reference when access via first argument indexing is possible.

Consistency checking is done whenever a reference is used; any attempt to use a reference to a clause that has been retracted will cause an existence error to be raised.

There is no restriction on the use of references. References may be included in asserted clauses. Database references to clauses and in clauses are preserved across saving and restoring via QOF files (see also sap-srs-bas-cld).

In release 3, a database reference reads and writes like a Prolog term of the form '$ref'(integer,integer); however, it is actually represented as a distinguished atomic data type by the Prolog system. As a result, Prolog operations like functor/3 and arg/3 treat database references as they would numbers or atoms:

     | ?- assert(foo,M).
     M = '$ref'(1296804,1)
     | ?- functor('$ref'(1296804,1), N, A).
     N = '$ref'(1296804,1),
     A = 0
     | ?- arg(1, '$ref'(1296804,1), A).
     | ?-

Database references can be identified using the type test db_reference/1.

In previous releases of Quintus Prolog, operations such as the above were occasionally used on database references so that their components could be indexed on in asserted clauses. Such operations have always been discouraged. In release 3, full indexing is automatically available on the entire database reference, so it is unnecessary to have access to its components.

As in the past, the representation of database references may change in future releases, so programs should not rely on it.