Content-type: text/html; charset=UTF-8 Man page of qddb_tuple

qddb_tuple

Section: Herrin Software Development, Inc. (1)
Updated: 21 Oct 2000
Index Return to Main Contents

NAME

qddb_tuple - Manipulate a Qddb tuple.

SYNOPSIS


qddb_tuple new <schema_desc>
qddb_tuple isvalid <schema_desc> <keylist node>
qddb_tuple read <schema_desc> <keylist node>
qddb_tuple write <tuple_desc>
qddb_tuple get external|readable|tclexternal|tclvalue <tuple_desc>
qddb_tuple put external|readable|tclexternal|tclvalue <schema_desc> <tuple value>
qddb_tuple lock <tuple_desc>
qddb_tuple unlock <tuple_desc>
qddb_tuple isempty <tuple_desc>
qddb_tuple refresh <tuple_desc>
qddb_tuple flush <tuple_desc>|<schema_desc>|all
qddb_tuple schemaname <tuple_desc>
qddb_tuple keylist <tuple_desc>
qddb_tuple remove <tuple_desc>
qddb_tuple delete <tuple_desc>|<schema_desc>|all

DESCRIPTION

qddb_tuple manipulates a Qddb tuple. <tuple_desc> is a tuple descriptor returned from a

        qddb_tuple read <schema_desc> <keylist node>

command. <keylist node> 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_tuple new: creates a new blank tuple filled with any default values and returns a new tuple descriptor.
qddb_tuple isvalid: returns true (1) if the keylist node points to a valid tuple, false (0) if it is invalid (deleted or changed).
qddb_tuple read: 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_tuple read returns an empty string (""). Any locks on the tuple being read are released.
qddb_tuple write: writes a tuple described by <tuple desc> back into the Qddb database as a changed entry.
qddb_tuple get: 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_tuple put: 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_tuple write of a tuple created with qddb_tuple put 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_tuple lock: 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_tuple lock implicitly refreshes the tuple after the lock is obtained; you are guaranteed to always have the newest version of the tuple after qddb_tuple lock returns. If the lock is obtained, qddb_tuple lock returns 1, otherwise, it returns 0.
qddb_tuple unlock: removes the lock (if any) on the specified tuple.
qddb_tuple isempty: 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_tuple refresh: refreshes the given tuple from the disk. This command is generally used to refresh the tuple if changes are made and discarded.
qddb_tuple flush: 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 does not remove any locks.
qddb_tuple schemaname: returns the schema descriptor associated with the given tuple.
qddb_tuple keylist: returns the given tuple's unique keylist descriptor suitable as an argument to qddb_tuple read.
qddb_tuple remove: invalidates the given tuple on disk and deletes the tuple from memory.
qddb_tuple delete: 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.

SUPPORTED FORMATS

For examples in this section, we will use the following schema:

        a ( b* c* d* )*

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).

tclvalue

(not yet implemented).

REFERENCES

A Guide to QDDB
Eric H. Herrin II and Raphael A. Finkel

Qddb User's Guide

An ASCII Database for Fast Queries of Relatively Stable Data
Eric H. Herrin II and Raphael A. Finkel
Computing Systems, Volume 4 Number 2
University of California Press, Berkeley CA

Schema and Tuple Trees: An Intuitive Structure for 
Representing Relational Data
Eric H. Herrin, II and Raphael A. Finkel
Computing Systems, Volume 9, Number 2
MIT Press, Cambridge MA

TCL and the TK Toolkit 
John K. Ousterhout
Addison-Wesley, 1994
ISBN 0-201-63337-X

DIAGNOSTICS

BUGS

None known.

This document was created by man2html, using the manual pages.
Time: 18:55:30 GMT, October 31, 2018