man page(1) manual page
Table of Contents

NAME

qddb_rows - Row operations on tuples and keylists.

SYNOPSIS

qddb_rows all ?-format rows? ?-instance attr,inst? ?-rowdescs on|off? \ ?<options>? <tuple_desc>
Return value:
{ <row_desc> "row values" }
{ <row_desc> "row values" }
...
qddb_rows all ?-format table? ?-instance attr,inst? ?-rowdescs on|off? \ ?<options>? <tuple_desc>
Return value: a <table desc>

qddb_rows select ?-format rows? ?<options>? <keylist_desc> (default) ->Return value:
{ <tuple_desc> <row_desc> "row value" } { <tuple_desc> <row_desc> "row value" } ...
qddb_rows select -format query ?<options>? <keylist_desc> ->Return value:
{ { row value } { Start Length Number Type } { attr,inst ... } } { { row value } { Start Length Number Type } { attr,inst ... } } ...
qddb_rows select -format table ?<options>? <keylist_desc> ->Return value: a <table desc>

qddb_rows get <row_desc>
qddb_rows getval <attribute list> <row_desc> qddb_rows sort ?-ascending <attribute list>? <attribute list> <row_desc list> qddb_rows tuplename <row_desc>
qddb_rows delete <row desc>|all

<options>:
-attrs <attribute list> - unordered list of significant attributes ('qddb_rows select' only, obsolete)

-print <print list>
- ordered list of attributes to print (format: { attr[:width] attr[:width] ... })
-sortby <attr list>
- ordered list of attributes selected from the `-print' option's list -ascending <attr list> - unordered subset of list supplied by `-sortby' to be sorted in ascending order
-sep string
- use the supplied string as a column separator
-norows on|off
- suppress printing of attr,inst pairs when using `-format query' (default: off)
-suppress on|off
- suppress printing of row values (default: off)
-tclelements on|off
- return row values as Tcl elements (default: off)
-flush on|off
- flush each tuple from memory after producing rows to save memory (default: off)
-deldup_rows on|off
- delete duplicate rows from those produced by

the same tuple (default: off)

DESCRIPTION

<tuple_desc> is a tuple descriptor like that returned by a qddb_tuple read command. <keylist desc> is a keylist descriptor, generally returned by a qddb_search or some combination of qddb_keylist commands. <attribute list> is a list of attributes that matched a query, for example:

{ Name.First Name.Last Address.Street Address.City }

specifies that we want only rows that matched in those attributes. An example command sequence might be: set s [qddb_schema open Family]
set k0 [qddb_search $s George]
set k1 [qddb_search $s Harris]
set k2 [qddb_search $s Rosemont]
set k3 [qddb_search $s Richmond]

set k0 [qddb_keylist process prune -prunebyattr Name.First
$k0]
set k1 [qddb_keylist process prune -prunebyattr Name.Last
$k1] set k2 [qddb_keylist process prune -prunebyattr Address.Street $k2]
set k3 [qddb_keylist process prune -prunebyattr Address.City
$k3] foreach i [list $k1 $k2 $k3] { set k0 [qddb_keylist op intersection $k0 $i] } set r [qddb_rows select -format rows -deldup_rows on \ -attrs {Name.First Name.Last Address.Street Address.city} \ -print {Name.First:10 Name.Last:15 Address.Street} $k0] puts $r qddb_schema close $s qddb_keylist delete all qddb_rows delete all qddb_tuple delete all This sequence (1) searches for the keys, (2) prunes the keylists of any nodes not pertaining to the desired attributes, (3) performs an intersection on the resulting lists, and (4) selects the rows from the keylist, and (5) prints out the result.

<print list> is of the same form as <attribute list>, but with an optional width field:
{ Name.First:10 Name.Last:15 Address.Street:20 Address.City:15 } If the width field is absent, the attribute's value is not truncated and each field's value is a TCL-list element.

The -format query option forces qddb_rows select to throw away the tuples after it finds the row values. If -for_mat rows is in effect, then the tuples are all kept in memory. Obviously, if you have a very large database, and you don't control the number of tuples that a query can match, then you should use the -flush on option (unless you have a huge amount of RAM in your machine). qddb_rows all
traverses the tuple described by the given <tuple desc> to produce a set of rows. This command returns a list of {<row desc> <row values>} by default ('-format rows'), each of which describes a row in the tuple described by <tuple desc>. The values of the rows may be obtained with a call to qddb_rows get. If the -instance attr,inst argument is provided, then only those rows that match the (attr,inst) pair are returned. For example, if you supply -instance Person.Address,1.1, then the result is only rows containing the first instance of Address within the first instance of Person. In this case,

qddb_rows all -sep " " -instance Person.Address,1.1
-print { Person.Name.First Person.Name.Last Person.Address.Street } $tuple

would operate on the following readable tuple Person (
Name (
First = "Henry"
Last = "McKinney"
)
Name (
First = "Georgia"
Last = "McKinney"
)
Address (
Street = "123 Rowdy Way" )
Address (
Street = "2312 Dougherty Parkway" )
)
Person (
Name (
First = "Monrey"
Last = "Montavere"
)
Address (
Street = "321 Howdy Way" )
)
and produce rows containing:
Henry McKinney 123 Rowdy Way Georgia McKinney 123 Rowdy Way

To produce rows with all instances of the Per_son.Address attribute, you may specify -instance Person.Address,1. This will produce all rows with the 1st Person and any Address. For example, using the readable tuple above you would get: Henry McKinney 123 Rowdy Way Henry McKinney 2312 Dougherty Parkway Georgia McKinney 123 Rowdy Way Georgia McKinney 2312 Dougherty Parkway

qddb_rows all -format table
produces a table descriptor suitable for use with the qddb_table command. The table has the following properties:
1) each row is the same as would be returned by qddb_rows all -format rows 2) column names are fully qualified attribute names (in order) from the -print option's list
3) the column titles are the verbosenames of the corresponding attributes 4) each column type defaults to the corresponding attribute type 5) row comment fields are set to "<tuple_desc> <row_desc>" unless `-rowdescs off' is specified

qddb_rows select
finds all rows for all tuples in the keylist (described by <keylist desc>) that have at least one node in the given keylist for each supplied attribute. That is, <attribute list> describes the attributes used in the search(es) that produced the keylist, and qddb_rows select produces only rows that match in every attribute used in the search. If no <attribute list> is supplied, then all rows for each tuple described in the keylist are selected. If no <print list> is supplied, then the return value is list of triples: { <tuple desc> <row desc> {} } { <tuple desc> <row desc> {} } If <print list> is supplied, then the value for each attribute specified in <print list> is returned as the fourth sub-element in each element of the returned list and all duplicate rows are deleted:
{ <tuple desc> <row desc> { <formatted string> } { <tuple desc> <row desc> { <formatted string> } The option -suppress on forces the suppression of the formatted string, but still deletes duplicate rows based on the -print options. The -sortby and -ascending options each accepts a list of leaf attributes. -sortby specifies the sorting order of the rows, while -ascending determines which attributes are sorted in ascending (increasing) order. The default sorting order is descending (decreasing). The option -tclelements on replaces the formatted string with a list of full element values. The <tuple desc> in each row is a readyto-use tuple descriptor, distinct from any tuple descriptor that was open at the time of the call.

Each returned <tuple desc> must be deleted when the application is finished with it (as well as each <row desc>). The option -flush on flushes tuple from memory as it reads them to obtain row values. The flush option is faster when memory is limited and many tuples are returned from a query (it is somewhat slower when memory isn't an issue).

qddb_rows select -format table
produces a table descriptor suitable for use with the qddb_table command. The table is set up with the following properties:
1) each row is the same as would be returned by qddb_rows select -format rows 2) column names are fully qualified attribute names (in order) from the -print option's list
3) the column titles are the verbosenames of the corresponding attributes 4) each column type defaults to the corresponding attribute type 5) row comment fields are set to "<tuple_desc> <row_desc>" if `-rowdescs on' is specified (default is `off'). Since the option `-rowdescs on' provides a tuple and row descriptor in the comment field for each row, the user is responsible for explicitly deleting the tuples and rows after use. For example, the following code will walk through such a table, delete all tuple and row descriptors, then finally delete the table itself.
...

set table [qddb_rows select -format table -attrs
{A B C} -print {A B C} -rowdescs on $keylist] set maxnum [qddb_table row maxnum $table] for {set i 1} {$i <= $maxnum} {incr i} { set tuple [qddb_table row cget $table $i -comment] catch "qddb_tuple delete [lindex $tuple 0]" } qddb_table delete $table

This command finds all rows in exactly the same manner as qddb_rows select. The return value is a table descriptor suitable as an argument to qddb_table. Each column in the table is named by the corresponding attribute (i.e. A.B.C), has the same type, and the title is the verbosename of the attribute. The -rowdesc on option places a row descriptor in the comment field of each row in the table; if -rowdesc is off, the corresponding tuples and rows are not saved and are deleted from memory as each tuple is read. The -flush on option flushes each tuple from memory, but still saves the row descriptor in the comment field of each row for later use. Note that table operations are generally much faster than manipulating standard Tcl lists. If speed of table operations is important to you, you should use this command instead of qddb_rows select.

qddb_rows get
returns a list of (attribute,value) pairs for the given <row_desc>. qddb_rows get provides a way to get different combinations of attribute values from a particular row.

qddb_rows getval
returns a list of unformatted values associated with each element of <attribute list>. For example: % qddb_rows getval { Person.Name.First Person.Name.Last } $r {Eric} {Herrin}
Note that any spaces in the attributes' values are not trimmed.

qddb_rows sort
returns a list of row descriptors identical to the given list of row descriptors, except they are sorted according to the given <attribute list>. For example, given a set of rows: qddb_row1 {Henry} {McKinney}
qddb_row2 {George} {Wilbur}
qddb_row3 {Zoe} {Appleton}
qddb_row4 {George} {Arthur}
an example use of qddb_rows sort might be: % qddb_rows sort -ascending {Person.Name.Last Person.Name.First} \ {Person.Name.First Person.Name.Last} \ {qddb_row1 qddb_row2 qddb_row3 qddb_row4} qddb_row1 qddb_row4 qddb_row2 qddb_row3 % qddb_rows sort -ascending {Person.Name.Last Person.Name.First} \ {Person.Name.Last Person.Name.First} \ {qddb_row1 qddb_row2 qddb_row3 qddb_row4} qddb_row3 qddb_row4 qddb_row1 qddb_row2 % qddb_rows sort {Person.Name.Last Person.Name.First} \ {qddb_row1 qddb_row2 qddb_row3 qddb_row4} qddb_row2 qddb_row1 qddb_row4 qddb_row3 The -ascending option's argument is a subset of the <attribute list> specifying which of the columns are to be sorted in an ascending fashion. The default is descending. The qddb_rows getval command may then be used to get the values from the individual rows for viewing purposes. Note that the sorting process uses the natural sorting method for the type of attribute (integer, real, string, or date).

qddb_rows tuplename
returns the tuple descriptor associated with the given row descriptor.

qddb_rows delete
deletes the in-memory row given by <row_desc>. The special <row_desc> all deletes all rows from memory.

SEE ALSO

qddb_instance(n), qddb_keylist(n), qddb_schema(n), qddb_search(n), qddb_table(n), qddb_tuple(n), qddb_view(n)

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

qddb_rows select operates on the values permanently stored in the Qddb database. If modifications to the tuple have been made at run-time (and not saved), qddb_rows select may not produce reasonable results. Rows produced with qddb_rows all may be processed with qddb_rows getval to produce current values as long as the values aren't changed between the calls. qddb_rows select is generally used to produce a set of rows for tuple selection by the user (or report generation).

BUGS

None known.


Table of Contents