qddb_tuple manipulates a Qddb tuple. <tuple_desc> is a tuple descriptor returned from a
qddb_tuple read <schema_desc> <keylist node> command. <keylistnode> is a quadruple generally obtained from a within a list returned by
qddb_keylist get <keylist desc>
command. <schema_desc> is a schema descriptor returned from a
qddb_schema open <relation directory> command. <tuple value> is a tuple in one of the supported formats (external, readable, tclexternal, or tclvalue).

qddb_tuplenew
creates a new blank tuple filled with any default values and returns a new tuple descriptor.

qddb_tupleisvalid
returns true (1) if the keylist node points to a valid tuple, false (0) if it is invalid (deleted or changed).

qddb_tupleread
reads a tuple described by <keylist node> into memory from an open Qddb database described by <schema desc>. The value returned from this command is a descriptor that may be used in subsequent Qddb calls. If the tuple is invalid (that is, if it has been deleted or changed), qddb_tupleread returns an empty string (""). Any locks on the tuple being read are released.

qddb_tuplewrite
writes a tuple described by <tuple desc> back into the Qddb database as a changed entry.

qddb_tupleget
returns the contents of the tuple described by the given <tuple desc> in the requested format. Currently, four formats are available: external, readable, tclexternal, and tclvalue (See section on Supported Formats below).

qddb_tupleput
returns a <tuple_desc> describing a new tuple with the contents taken from the <tuple value> argument. The new tuple may then be written, or used in any way a normal tuple may be used. A qddb_tuplewrite of a tuple created with qddb_tupleput is entered into the database as a completely new tuple, regardless of whether the $NUMBER$ field is supplied (the $NUMBER$ field is supported for backward compatibility only).

qddb_tuplelock
locks a tuple for exclusive writing. Other Qddb applications honoring the locking protocol may still read the old tuple's data, but they may not obtain a lock for that tuple. qddb_tuplelock implicitly refreshes the tuple after the lock is obtained; you are guaranteed to always have the newest version of the tuple after qddb_tuplelock returns. If the lock is obtained, qddb_tuplelock returns 1, otherwise, it returns 0.

qddb_tupleunlock
removes the lock (if any) on the specified tuple.

qddb_tupleisempty
check the given tuple for non-blank fields. If it contains at least one non-blank field, a 1 is returned. Otherwise, a 0 is returned.

qddb_tuplerefresh
refreshes the given tuple from the disk. This command is generally used to refresh the tuple if changes are made and discarded.

qddb_tupleflush
flushes memory used by the tuple, but marks the tuple to be re-read from disk if the <tuple_desc> is used. This implements a form of read-on-demand. If <schema_desc> is provided instead of <tuple_desc>, then all tuples associated with the schema described by <schema_desc> are flushed. If the special keyword all is used, then all tuples in memory associated with any schema are flushed. Note that all views for the tuple(s) (as defined by qddb_view) are automatically deleted when a tuple is flushed. Flushing an in-memory tuple doesnot remove any locks.

qddb_tupleschemaname
returns the schema descriptor associated with the given tuple.

qddb_tuplekeylist
returns the given tuple's unique keylist descriptor suitable as an argument to qddb_tupleread.

qddb_tupleremove
invalidates the given tuple on disk and deletes the tuple from memory.

qddb_tupledelete
deletes the given tuple descriptor and frees all memory occupied by the tuple. The given <tuple_desc> may not be used again. If <schema_desc> is provided instead of <tuple_desc>, then all tuples associated with the schema described by <schema_desc> are flushed. The special <tuple_desc> all instructs Qddb to delete all active tuples from memory. Deleting an in-memory tuple implicitly removes all locks associated with the tuple.

external
A list of attributes in external format. The first element in the list is (optionally): %0 V <unique sequence number>

and each other element of the list is an attribute in the form:
{
{%1.1.1.1 data in the field} {%1.2.1.1 more data}
}
Above we show two separate attributes, both of which describe a different instance of a.b. The first line describes the first instance of a and within that instance, the first instance of b. The second line describes the second instance of a and within that instance, the first instance of b. This format is equivalent to the standard format of the Qddb Database file.

readable
A single list element containing the Qddb readable form of the tuple. The readable form (for the schema above) might be:
{
$NUMBER$ = "319";
a (
b = "some data for attribute a.b" b = "some data for attribute a.b" c = "some data for attribute a.c" c = "some data for attribute a.c" )
a (
d = "some data for attribute a.d" )
}
Here we have two instances of the structured attribute a, each contains some instances of a's subattributes. The $NUMBER$ line describes the tuple's unique sequence number and is optional.

tclexternal
A list containing a number of (attribute,value) pairs. The tclexternal form for a tuple in the database described by the schema above might be: {
{$NUMBER$} 319
a.b,1.1 "some data for attribute a.b" a.c,2.1 "some data for attribute a.c" }
Here we have two instances of the structured attribute a, each containing data in exactly one attribute. The $NUMBER$ element tells us that the next element in the list is the unique sequence number for that tuple; the first two elements may be omitted. This is suggested format for use in network-based applications (client/server-style).