Additional TCL Interfaces to CHAIN utilities

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

chainTransZXY

Perform a "trans" operation on two aruments in each object on a chain. The result is stored in a third argument.
TCL SYNTAX:
   chainTransZXY <CHAIN> <z arg> <xarg> <yarg> <a> <b> <c>";

   <CHAIN>		handle of the chain
   <xarg> <yarg>	The arguments on which the operation is performed
   <a> <b> <c>		The transformation coefficients.

The transformation is as follows:
      z = a + b*x + c*y

RETURNS:
   TCL_OK      Successful completion. No result string
   TCL_ERROR   Error occurred. Interp result will contain the reason