Tcl Interface to Various Set Operations

List Sets

Use vtk_trace_list_sets to list all the sets. Usage details can be found in the VOV Reference Guide.

Example:

# -- List sets alphabetically
foreach set [lsort [vtk_trace_list_sets]] {
    puts "Set: $set"
}

Find Sets by Name

To map a set name to a VovId, use vtk_set_find as in:

set setId [vtk_set_find $setName]

This procedure returns zero (actually 00000000) if there is no set by the given name. All usage details of API procedures for sets are located in the VOV Reference Guide.

List Set Elements

To list the elements of a given set, use vtk_set_get_elements. This procedure requires at least two arguments, the VovId of a set and a formatting string.

Example:

set setId [vtk_set_find "System:files"]
foreach info [vtk_set_get_elements $setId "@ID@ @NAME@"] {
    puts "$info"
}

Smart Sets

Smart sets are sets that automatically update after every node change and include all nodes based on a selection rule given at set creation time. This feature can be very powerful, but very expensive.

Smart sets created with the -smartc argument only update on node creation, reducing the load created by smart sets.

Create Sets

From a Tcl script, use the procedure vtk_set_create, which requires two arguments, the name of the new set and the selection rule.

The procedure returns the VovId of the new set. If a set by the same name exists already, it is forgotten and a new set with a new VovId is created.

Example:

# Create an empty set by using "" (the null string) as the selection rule.
set setId [vtk_set_create "tmp:myNewSet" ""]

# Create a set of all jobs that are FAILED at the moment of the
# creation of the set
set setId [vtk_set_create "my_failed_jobs" "isjob status==FAILED"]

# Create a set of all jobs that are not VALID at the moment of the
# creation of the set. The set will be destroyed when the calling
# process exists (-client).  The set creation will not create events (-transient).
set setId [vtk_set_create  -client -transient "tmp:failed" "isjob status!=VALID"]

# Create a smart set of all jobs that are SUSPENDED.
# The smart set is updated automatically by vovserver.
# The set expires after 5 minutes from the creation.
set setId [vtk_set_create -smart -expire 5m "My:Suspended" "isjob status==SUSPENDED"]

# Create a hierarchical set. In the following example, MySet and Subset are created,
# Subset becomes the subset of MySet.
set setId [vtk_set_create -hier MySet:Subset ""]

Forget Sets and Elements of Sets

Use vtk_set_forget to forget a set. This procedure returns "ok" if the set has been forgotten and returns an error otherwise, e.g. if the VovId is not valid for a set.

vtk_set_forget $setId

To forget all the elements of a set, use the option -elements as in:

vtk_set_forget -elements $setId

To forget a set and all the subsets, use the option -hier as in:

vtk_set_forget -hier $setId

To forget all elements in the set and the subsets:

vtk_set_forget -hier -elements $setId

Rename Sets

To rename a set, use vtk_set_rename as in:

vtk_set_rename $setId "new set name"

Operations on Sets

Many operations may be performed on sets. All operations can be performed from the Tcl interface using a procedure called vtk_set_operation. Many operations are also available from the CLI and from the GUI. This section deals only with the Tcl interface.

Attaching and detaching nodes

To attach and detach nodes from a set, you need the VovId of the set and the VovId of the node you want to attach or detach. Then you use one of these two forms:

vtk_set_operation $setId $nodeId ATTACH
vtk_set_operation $setId $nodeId DETACH

To detach all elements of a set, use:

vtk_set_operation $setId ignored CLEAR

The second argument is ignored. Detached nodes remain in the trace.

Testing for membership

To test for membership of a node in a set, you need the VovId of the set and the VovId of the node. The following expression returns 1 if the node is a member of the set, and 0 otherwise: Note: in 2015.03 and later releases, ISMEMBER may be used as an alternate to CONTAINS.

vtk_set_operation $setId $nodeId CONTAINS

Intersection and union of sets

To intersect or unite two sets you need the VovId's of both sets. One of the sets will be the "accumulator" set, because it collects the result of the operation. In the case of intersection, all elements in the accumulator that do not belong in the other set are detached from the accumulator set. In the case of union, all elements in the other set are attached to the accumulator set.

vtk_set_operation $accId $setId INTERSECTION
vtk_set_operation $accId $setId UNION

In the vtk_set_operation calls, the first argument is always the VovId of the accumulator set.

Complement of a set

This operation also requires two sets. The result, stored into the accumulator set, is effectively the intersection of the accumulator with the complement of the other set.

vtk_set_operation $accId $setId COMPLEMENT

Input set, Output set and cones

These operations are similar to union and intersection. Upon entry, the accumulator set, which collects the result, should be an empty set.

vtk_set_operation $accId $setId INPUTS
vtk_set_operation $accId $setId OUTPUTS
vtk_set_operation $accId $setId UPCONE
vtk_set_operation $accId $setId DOWNCONE

Subselection

Given a set, you can subselect the elements from the set that satisfy a selection rule using vtk_set_subselect. The result is a new set. For the original set, you can use either the name or the VovId.

set newSetId [vtk_set_subselect $nameOrIdOfSet $rule]

By default, the name of the new set is computed by vtk_set_subselect using the name of the original set and the selection rule in the following form:

SUBSELECT(<setName>,<Rule>)

You can specify the name of the new set with the option -setname:

set newId [vtk_set_subselect -name "MyNewSet" $setId $rule]

If the original set has subsets and you want to collect elements from subsets as well, use -hier option.

set newId [vtk_set_subselect -hier -name "MyNewSet" $setId $rule]

Subselection generates a large number of detach/attach events, and this may overflow the event queues for the GUI's connected to the server. In those cases in which the subselected set is immediately forgotten, the attach/detach events are of no interest. It is possible to inhibit the generation of these events by declaring the set as transient with the option -transient. Example:

set newId [vtk_set_subselect -transient $setId $rule]
doSomething $newId
vtk_set_forget $newId