Recorded database

In some applications it is useful to store and retreive Prolog terms from C-code. For example, the XPCE graphical environment does this for storing arbitrary Prolog data as slot-data of XPCE objects.

Please note that the returned handles have no meaning at the Prolog level and the recorded terms are not visible from Prolog. The functions PL_recorded and PL_erase are the only functions that can operate on the stored term.

Two groups of functions are provided.The first group (PL_record and friends) store Prolog terms on the Prolog heap for retrieval during the same session. These functions are also used by recorda3 and friends. The recorded database may be used to communicate Prolog terms between threads.

record_tPL_recordterm_t +t Record the term t into the Prolog database as recorda3 and return an opaque handle to the term. The returned handle remains valid until PL_erase is called on it. PL_recorded is used to copy recorded terms back to the Prolog stack. voidPL_recordedrecord_t record, term_t -t Copy a recorded term back to the Prolog stack. The same record may be used to copy multiple instances at any time to the Prolog stack. See also PL_record and PL_erase. voidPL_eraserecord_t record Remove the recorded term from the Prolog database, reclaiming all associated memory resources.

The second group (headed by PL_record_external) provides the same functionality, but the returned data has properties that enable storing the data on an external device. It has been designed to make it possible to store Prolog terms fast an compact in an external database. Here are the main features:

char *PL_record_externalterm_t +t, unsigned int *len Record the term t into the Prolog database as recorda3 and return an opaque handle to the term. The returned handle remains valid until PL_erase is called on it.

It is allowed to copy the data and use PL_recorded_external on the copy. The user is responsible for the memory management of the copy. After copying, the original may be discarded using PL_erase_external.

PL_recorded_external is used to copy such recorded terms back to the Prolog stack. intPL_recorded_externalconst char *record, term_t -t Copy a recorded term back to the Prolog stack. The same record may be used to copy multiple instances at any time to the Prolog stack. See also PL_record_external and PL_erase_external. intPL_erase_externalchar *record Remove the recorded term from the Prolog database, reclaiming all associated memory resources.