[Tinyos-commits] CVS: tinyos-1.x/tos/lib/VM/languages/tinysql tinysql.txt, 1.5, 1.6

[David Gay]

Update of /cvsroot/tinyos/tinyos-1.x/tos/lib/VM/languages/tinysql
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1909

Modified Files:
	tinysql.txt 
Log Message:
support displaying results of global aggregates with the "tinysql log" command


Index: tinysql.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/tos/lib/VM/languages/tinysql/tinysql.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tinysql.txt	1 Nov 2005 02:37:11 -0000	1.5
--- tinysql.txt	18 Nov 2005 00:04:44 -0000	1.6
***************
*** 130,138 ****
  ------------------
  
- WARNING: "tinysql log" does not currently handle global queries
-          correctly. You can work around this by editing the
- 	 // SCHEMA line. Replace avg aggregates by three fields
- 	 (epoch, count, sum) and min and max by two (epoch, min or max)
- 
  The syntax of a global query is:
    select GLOBAL1[VALUE11, VALUE12, ...],
--- 130,133 ----
***************
*** 153,160 ****
  tree.  Computing an aggregate thus causes signifcantly less network
  traffic than collecting all the data at the root and computing the
! aggregate there. The set of global aggregates available is:
  - min, max and avg
  - the global aggregates defined in motlle code (see Section 5)
  
  4) The tinysql command
  ======================
--- 148,170 ----
  tree.  Computing an aggregate thus causes signifcantly less network
  traffic than collecting all the data at the root and computing the
! aggregate there. However, to support this, results from aggregates
! are delayed by a number of epochs (to allow time for parents to 
! aggregate the results of their descendants within the network).
! 
! The set of global aggregates available is:
  - min, max and avg
  - the global aggregates defined in motlle code (see Section 5)
  
+ A single global aggregate becomes multiple attributes in a query's schema
+ (see the "tinysql log" command below). The exact set of attributes
+ is up to each aggregate implementation, but will typically include 
+ the actual epoch this aggregate result is for (necessary because of the
+ delay in global aggregates mentioned above). For the three predefined
+ global aggregates, these attributes are:
+ - avg: epoch, count and sum. The actual average is sum/count.
+ - min: epoch and value. The minimum is value,
+ - max: epoch and value. The maximum is value,
+ 
+ 
  4) The tinysql command
  ======================
***************
*** 196,199 ****
--- 206,213 ----
    to install your patched code in the sensor network. However, if you
    change the message layout, "tinysql log" will likely fail.
+ - tinysql log displays the query's schema, which consists of the current
+   epoch and the value of each aggregate. See the discussion under global
+   queries above for more information on the representation of global
+   aggregates in the schema.
  
  5) Extending TinySQL: User-specified attributes, aggregates
***************
*** 286,293 ****
--- 300,320 ----
    Y and the result of X_get sent by the child mote.
  
+ You must also include information on the global aggregate's internal
+ attributes, so that "tinysql log" can generate the correct schema. This
+ information takes the form of a comment
+   // <X>_SCHEMA: <internal attributes for X, separated by spaces>
+ Note that this information must match the encoding used by X_get.
+ "tinysql log" assumes that each internal attribute is encoded as a 2-byte
+ little-endian integer.
+ 
  As you can probably tell, all of this is somewhat tricky to implement. Here
  is some code that could be used to implement the avg[] global aggregate in
  motlle (untested, but converted from the built-in average aggregate):
  
+   // The schema for avg
+   //   AVG_SCHEMA: epoch count sum
+   // where epoch is chosen so that our descendant's results have
+   // reached us before we try and send them on. The result of the
+   // average is sum/count.
    any maxdepth = 5; // max routing tree depth supported
    any window = 2 * maxdepth;
***************
*** 348,355 ****
    any avg_update(Y, val) add_avg(Y, epoch(), 1, val);
  
!   // avg_get returns a six-byte string containg encoded
    //   epoch, count, sum (2 bytes each)
-   // where epoch is chosen so that our descendant's results have
-   // reached us before we try and send them on
    any avg_get(Y) {
      any start = Y[2 * window];
--- 375,380 ----
    any avg_update(Y, val) add_avg(Y, epoch(), 1, val);
  
!   // avg_get returns a six-byte string containg the encoded values of
    //   epoch, count, sum (2 bytes each)
    any avg_get(Y) {
      any start = Y[2 * window];