NAME

relvar -
Operators for Relation Variables

SYNOPSIS

package require ral 0.7
::ral::relvar create relationVariable heading identifiers  ? name-value-list ... ? 
::ral::relvar delete relationVariable tupleVariable expression
::ral::relvar deleteone relationVariable name-value-list
::ral::relvar destroy  ? relationVariable ... ? 
::ral::relvar dump  ? -schema | -body ?   ? pattern ? 
::ral::relvar insert relationVariable  ? name-value-list ... ? 
::ral::relvar names  ? pattern ? 
::ral::relvar set relationVariable  ? relationValue ? 
::ral::relvar update relationVariable tupleVariable expression name-value-list
::ral::relvar updateone relationVariable id-name-value-list name-value-list
::ral::relvar virtual relationVariable relationExpression

DESCRIPTION

This manpage describes the relvar command. The relvar command is part of the Tcl Relational Algebra Library (ral) package.

TclRAL defines a variable space for relation variables. Relation variables hold relation values and the subcommands of the relvar command generally operate directly on the values storing the results back into the relation variables. For this reason, most of the relvar subcommands take the name of a relation variable as an argument.

In the relational model, relation variables play the important role of representing the persistent data base values. Relation variables are the leaves of the expression tree that performs the desired computation and represent the core data from which results may be computed. That computation is expressed as a single, sometimes complex expression. This allows for a non-procedural way of specifying the computation and allows optimizers to find the most efficient manner of computing the result.

In the TclRAL implementation, relation variables serve a similar role although there is no persistence supplied by the library. Relation values may be stored in Tcl variables like any other Tcl object. This does abandon the non-procedural nature of relational expressions as usually accomplished in the relational model, but is a better fit to the Tcl way of doing things.

Since it is possible to store a relation value in an ordinary Tcl variable, the user should be aware of some of the consequences of this. Because internally Tcl objects are reference counted, storing a relation value in a variable in effect creates another reference to the underlying object. Since the relvar commands operate directly on the underlying value, any changes to the value affected by the relvar subcommands will also be reflected in the value seen by any references to the value stored in ordinary Tcl variables. So, for example, if the value of a relation variable, say RV, is stored in a Tcl variable, say V, then any insert or delete operations on RV will also be seen when the value is accessed via V. This could be surprising to some, since most other Tcl commands will create a new copy of a shared value before performing any update operation on it. The behavior described here works well when it is remembered that the relvar commands can modify the underlying value directly and that the relation commands only operate on values in a read only fashion and never modify their arguments directly.

COMMANDS

::ral::relvar create relationVariable heading identifiers ? name-value-list ... ?

The create subcommand creates a new relation variable whose name is given by relationVariable. The subcommand has no return value. The heading is specified by an even numbered list consisting alternately of an attribute name and attribute data type. The identifiers argument is a list of identifying attribute sets. Each element of the identifiers list is in turn a list containing a set of attribute names that constititute an identifier. Relations must have at least one identifier. Relations may have an arbitrary number of identifiers however, no identifier may be a subset of another identifier. Optionally, an arbitrary number of tuples may be specified. Tuples consists of a list of alternating attribute name / attribute value pairs. Optional tuples are inserted into the relation variable as if relvar insert had been called.

relvar create OWNER {OwnerName string Age int City string} OwnerName

::ral::relvar delete relationVariable tupleVariable expression

The delete subcommands deletes tuples from the relation variable given by the relationVariable argument. Each tuple in the body of relationVariable is assigned to the tuple variable named tupleVariable and expression is evaluated. If expression returns true, then that tuple is deleted, directly modifying the value contained in relationVariable. The return value of the subcommand is the number of tuples deleted.

relvar delete OWNER o {[tuple extract $o OwnerName] eq "Sue"}

::ral::relvar deleteone relationVariable name-value-list

The deleteone subcommand deletes at most one tuple from the relation variable given by the relationVariable argument. The name-value-list must be list containing an even number of elements which are attribute names alternating with attribute values. The set of attribute names in name-value-list must form one of the identifiers of relationVariable. If relationVariable contains a tuple whose attribute values match those in name-value-list then that tuple is deleted and relationVariable is modified in place. Otherwise relationVariable is unchanged. This subcommand is useful in those contexts where the attribute values of an identifier are known and evaluating an expression over all the tuples in relationVariable is superfluous. The return value of the subcommand is the number of tuples deleted which will be either 1 or 0.

% relvar deleteone OWNER {OwnerName Sue}
1

::ral::relvar destroy ? relationVariable ... ?

The destroy deletes all the relation variables whose names are given as the subcommand arguments.

::ral::relvar dump ? -schema | -body ? ? pattern ?

The dump subcommand returns a Tcl script that when evaluated will reconstruct the relation variables in the state that existed at the time the dump subcommand is issued. This command provides a primative means of persistence for the relation variables since the value returned from dump may be stored in a file to be source'ed in later. If the -schema argument is present then only relvar create commands are included in the dump, in effect dumping only the schema. If the -body argument is present then only relvar insert commands are included in the dump, in effect dumping only the data. If neither -schema or -body are present then both the necessary relvar create and relvar insert commands are returned. If the pattern is present then only those relation variables names matching pattern are dumped. Matching of relation variable names against pattern happens in the same manner as for the string match command.

set c [::open vars.tcl w]
puts -nonewline [relvar dump]
::close $c

::ral::relvar insert relationVariable ? name-value-list ... ?

The insert subcommand inserts the tuples given by name-value-list arguments into the value of the relation stored in relationVariable. The value is modified in place. The subcommand has no return value. It is an error to attempt to insert a duplicate tuple or a tuple whose heading does not match the relation heading. All values of the tuple must be specfied with a valid value representation of the type associated with the attribute.

relvar insert OWNER {OwnerName Sue Age 20 City {New York}} {City {San Francisco} Age 32 OwnerName Frank}

::ral::relvar names ? pattern ?

The names subcommand returns a list of the currently defined relation variables. If the pattern argument is specified then only those names matching pattern are returned. Name matching is performed as for the string match command.

::ral::relvar set relationVariable ? relationValue ?

The set subcommand replaces the current value held by the relation variable named relationVariable with the value given by relationValue. The set subcommands operates differently depending upon whether relationVariable is a base relvar or a virtual relvar. If relationVariable is a base relvar, then set attempts to assign relationValue, if present, to the relvar. It is an error to attempt to assign a relation value to a relation variable that is of a different type than the type of the value that the variable currently holds. If relationVariable is a virtual relvar, then relationValue is interpreted as a relational expression string and is associated in a macro-like fashion to relationVariable. The return value of the subcommand the current value held by relationVariable. If relationVariable is virtual, then its associated relation expression is evaluated and returned as the value of the set subcommand. If the relationValue argument is missing, then no attempt is made to change the value of relationVariable. This command operates in a manner analogous to the set command for ordinary Tcl variables.

::ral::relvar update relationVariable tupleVariable expression name-value-list

The update subcommand modifies the values of tuples in the relation value contained in the relation variable given by relationVariable. Each tuple in relationVariable is successively assigned to the tuple variable given by tupleVariable and expression is evaluated. If the result of the evaluation is true, then the attributes whose names are mentioned in the name-value-list are set to the corresponding values. The name-value-list argument consists of alternating attribute names and attribute values. The return value of the subcommand is the number of tuples updated. The example below updates Sue's Age to be 20.

relvar update OWNER o {[tuple extract $o OwnerName] eq "Sue"} {Age 20}

::ral::relvar updateone relationVariable id-name-value-list name-value-list

The updateone subcommand modifies at most one tuple from the relation variable given by the relationVariable argument. The id-name-value-list must be list containing an even number of elements which are attribute names alternating with attribute values. The set of attribute names in id-name-value-list must form one of the identifiers of relationVariable. If relationVariable contains a tuple whose attribute values match those in name-value-list then then the attributes whose names are mentioned in the name-value-list are set to the corresponding values and relationVariable is modified in place. Otherwise relationVariable is unchanged. This subcommand is useful in those contexts where the attribute values of an identifier are known and evaluating an expression over all the tuples in relationVariable is superfluous. The return value of the subcommand is the number of tuples updated.

::ral::relvar virtual relationVariable relationExpression

The virtual subcommand creates a virtual relvar whose name is given by relationVariable and whose value is given by relationExpression. The relationExpression is a script that is evaluated each time that the value stored in relationVariable is fetched (via the relvar set command). Thus a virtual relvar behaves as a kind of macro. It is an error to attempt to perform any updates on a virtual relvar except to use relvar set to change the script associated with the relvar. It is also an error if the result of evaluating the script associated with a virtual relvar is not an object that can be converted into a Relation type.

SEE ALSO

tuple, relation

KEYWORDS

relation, variable