Several utility routines exist to manipulate chains. Each chain consists of zero or more objects, and each object has one or more elements defined by a schema. Only objects with TYPEs defined in dervish can be manipulated. Additional utilities to view chains can be found in the curses utilities.
Most commands manipulate chains based on accessing one or more elements. These elements can be referenced using the full handle expression syntax of dervish. Thus, for example, if one has a chain of REGIONs with each region containing a pointer to a mask structure, one could select all regions with masks that have 512 rows by using the command: chainSearch h1 {{mask->nrow = 512}} (where h1 is a handle to the chain).
Some commands require predicates. The format of the predicates is as follows:
{{pred1} {pred2} {pred3} ... }where each individual predicate can have one of two forms: either
{arg <op> value} or {value1 <op> arg <op> value2}.Each arg is an element or an element expression (that can be parsed by the dervish handle expression evaluator). Each <op> is one of the 6 standard boolean operators: <, >, = (== also works), <=, >=, !=. value or value1 or value2 are constants to be used for the comparison. The second type of predicate is called a "range". The operators should have the same sense in this case (but no checking is done). If one specifies a range such as {23 < ra < 1} where the upper limit is smaller than the lower limit, the range "wraps around" so all objects with ra < 23 or ra > 1 are selected. This is useful, obviously, for selecting on elements such as right ascension that are periodic. NOTE: spaces between the value, op, and arg parameters are REQUIRED. (this is because arg can involve subscripting, which is done using angle brackets). If you want to use the standard TCL parameter substitution inside the braces, then the following archane syntax must be used instead: e.g. "\{$lowerlimit < ra < $upperlimit\}".
Note added in proof: I think one can get away without the \'s above; thus one can just type "{$lowerlimit < ra < $upperlimit}". The double quotes neutralize the embedded braces.
EXAMPLES: Suppose one has a Dervish type STAR defined as:
typedef star { float ra; float dec; float mag; int id; char filter[1]; REGION *reg; } STAR; Then a predicate to a search command might be: "{180. < ra < 195.} {0 < dec < 10.} {mag <= 18.}" Another one might be "{reg->nrow = 512}" which will return all stars derived from regions with exactly 512 rows. In the following documentation, it is assumed that h1 and h2 are each handles to chains of STARs.
The command are as follows:
chainSearch
Search an unsorted chain for all elements satisfying a given predicate;
return a new chain with selected items";
TCL SYNTAX: chainSearch <CHAIN> <predicate> <CHAIN> handle of the chain <predicate> The search conditions RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason EXAMPLE: chainSearch h1 "{180. < ra < 195.} {0 < dec < 10.} {mag <= 18.}"
chainSelect
Select from a sorted chain all objects with elements satisfying a given
predicate; return a new chain with selected items.
TCL SYNTAX: chainSelect <CHAIN> <predicate> <CHAIN> handle of the chain <predicate> The selection conditions Note: Only one predicate is allowed in this command. The element used for the selection in the predicate is the element on which the list must be sorted; however, there is no check to verify that this is the case. This command is much faster than "chainSearch" for long chains since it performs a binary search. RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason EXAMPLE: chainSelect h1 "{23. < ra < 1.}" The chain must first have been sorted on ra. Although this looks bizarre mathematically, in this form of predicate, the selection will "wrap-around" from 23 hrs to 1 hr.
chainFSort
Sort a chain based on the specified argument. The argument can be an element
or handle expression. Sorting is done "in place".
TCL SYNTAX: chainFSort <CHAIN> <arg> [-reverse] <CHAIN> handle of the chain <arg> The argument on which the chain is to be sorted. If the "reverse" flag is specified, reverse the ordering from ascending to descending. RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason EXAMPLE: chainFSort h1 ra Sorts the chain on ra.
chainMatch
Match two chains based on one or more sets of arguments with the chains
lying within a specified window. A chain is return consisting of TSMERGE
objects, whereby each object contains a pair of pointers to the matching
objects in the input chains. The objects are not copied. The chains need
not be of the same type.
TCL SYNTAX: chainMatch <CHAIN1> <CHAIN2> <match-args> [-type TYPE] <CHAIN1> handle of the first chain <CHAIN2> handle of the second chain <match-args> A list of matching conditions The match-args list has the following format: {{c1arg1 c2arg1 window [wrap]}} {c1arg2 c2arg2 window [wrap]} ... } One or more matching conditions can be on the list. For each matching condition, the first item is the name of an argument on the 1st chain, the second item is the name of an argument on the 2nd chain, the third item is a window such that the absolute value of the different in the value of the two arguments must be smaller than the window. The fourth argument is optional; if supplied, it gives the "wrap-around" value for the two arguments. Thus, e.g., if "wrap" is 24, then pairs of objects with argument values of 23.9999 and 0.0001 will be match (provided the window condition is otherwise met). (CAUTION: The "wrap" feature has not been properly tested yet.) The arguments being matched need not be of the same type but must be of a numeric type. The -type flag is optional. If specified, the types of objects on the output list will be set to the specified TYPE rather than SHMERGE; it is up to the user to be sure that the first 2 element of TYPE are pointers (this feature is convenient when the pointers of TYPE have the types appropriate to the chains being matched; the TSMERGE pointers are declared as void *). RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason EXAMPLE: chainMatch h1 h2 "{ra ra .001 360.} {dec dec .001}" -type STARMERGE This assumes that one has defined a Dervish type typedef starmerge { STAR *object1; STAR *object2; ... } STARMERGE;There is a higher level TCL command chainMatchType that will create a new type if necessary based on the input chain types and then carry out the matching operation, all in one step.
chainSet
Set a specified element in all objects on a chain to a specified value.
TCL SYNTAX: chainSet <CHAIN> <arg> <value> <CHAIN> handle of the chain <arg> The argument to be set. <value> The value to which the argument is set RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason EXAMPLE: chainSet h1 id 17
chainSetFromHandle
Set a specified element in all objects on a chain to a specified value.
The input value is given by a handle
TCL SYNTAX: chainSet <CHAIN> <arg> <handle> <CHAIN> handle of the chain <arg> The argument to be set. <value> A handle to the value to which the argument is set RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason EXAMPLE: chainSetFromHandle h1 id h17.id This assumes that h17 is a handle to a structure with integer element id.
chainExtract
Extract a portion of a chain as specified by a starting index and a size.
TCL SYNTAX: chainExtract <CHAIN> <start> <len> <CHAIN> handle of the chain <start> The starting index (0-based) <len> Number of successive elements to be extracted. If len < 0, go from start to abs(len) and reverse the ordering RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason EXAMPLE: set subchain [chainExtract h1 17 4] New chain has size 4
chainScale
Scale a specified argument for all objects on a chain by specified coefficients.
TCL SYNTAX: chainScale <CHAIN> <arg> <a> <b>"; <CHAIN> handle of the chain <arg> The argument on which the scaling is performed <a> <b> The transformation coefficients. The scaling is as follows: x(new) = a + b*x RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason EXAMPLE: chainScale h1 ra 0 15. Convert ra from hrs to degrees
chainTransXY
Perform a "trans" operation on two aruments in each object on a chain.
The transformation is done "in place"
TCL SYNTAX: chainTrans <CHAIN> <xarg> <yarg> <a> <b> <c> <d> <e> <f>"; <CHAIN> handle of the chain <xarg> <yarg> The arguments on which the operation is performed <a> <b> <c> <d> <e> <f> The transformation coefficients. The transformation is as follows: x(new) = a + b*x + c*y y(new) = d + e*x + f*y RETURNS: TCL_OK Successful completion. No result string TCL_ERROR Error occurred. Interp result will contain the reason