RBB Programming with Command-Line Utilities (Scripting)

This section documents executable programs included with RBB that share information through files or pipelines. The pipeline might manipulate the contents of the RBB, or output data into a plotting program or spreadsheet file.

For brevity, the examples will environment variables to run RBBMain from rbb.jar, and for a database URL. This URL specifies a database that is persistent, accessed through a server, and is stored in the current working directory.

RBB="java -cp rbb-1.7.1.jar:h2-1.3.168.jar gov.sandia.rbb.tools.RBBMain"
DB="jdbc:h2:tcp:localhost/mydb"

Starting a Database Server

The H2 server is launched with the command:

$RBB server

Accessing the database through a server is not always necessary; a program can access a database in embedded mode (i.e. in-process) using a url such as jdbc:h2:file:mydb, which typically executes faster if the program will execute many separate queries. However, in the command-line paradigm it is typical to run many short-lived "utility" programs, and opening a large database takes much longer than connecting to a server that already has it open. Also, embedded database access is exclusive, precluding processing pipelines where multiple utilities access the blackboard concurrently (e.g. a pipeline that starts with RBB get, modifies the data to create new timeseries, and ends by re-inserting the new timeseries with RBB put).

Creating an RBB

The following command creates an RBB:

$RBB create $DB

The underlying H2 database will be created if it did not already exist. It will fail and do nothing if run on an existing RBB.

Creating an Event

The basic concept in RBB is a discrete Event. Try the command:

echo "\
name=joe,start=2,end=4
name=bob,start=1,end=3
name=bob,time=4
" | $RBB put $DB

To see all the events and timeseries in the RBB run:

$RBB get $DB ''

The last argument is the empty string, which means all the contents are retrieved (more on this in the section on retrieving data below).

Creating a Timeseries

Sending a textual Timeseries to RBB 'put' creates, populates, and ends the timeseries. The start and end times of the timeseries are assumed to be the times of the first and last observations in the timeseries. Create a text file infile.txt with the contents:

test=draw,color=pink,src=cmdline,id=1
1,150,100
4,450,400

test=draw,color=blue,src=cmdline,id=2
2,100,100
3,130,80
6,100,400

Then read it into the RBB:

$RBB put $DB < infile.txt

The following command creates one million observations of particles in Brownian motion (100 timeseries of length 10,000):

time perl -e '$n=100; @colors=qw(red green blue pink black orange gray); 
for $i(1..$n) { 
  print STDERR "$i/$n\n"; 
  print "test=draw,color=",$colors[rand(@colors)],"\n"; 
  $s=15; ($cx,$cy)=($x,$y)=(250,250); 
  for $j(0..10000){ 
    print join(",",$j/20,$x,$y),"\n"; $x+=rand($s)-$s/2; $y+=rand($s)-$s/2; } }' | 
$RBB put $DB

These can be replayed in DrawTimeseries (but do not select "Show Paths"!):

$RBB ui draw -filterTags test=draw -eventTags test=draw -maxTime 500 $DB

Retrieving data

Events

The "get" utility retrieves timeseries, selecting them by tagsets and time:

$RBB get $DB name=joe

Or, limiting the time range:

$RBB get -start 2 -end 3 $DB name=bob

Result:

end=3.0,name=bob,start=2.0

Note: The event overlapping with the specified time range was truncated to that range, and the other name=bob event was excluded because it starts and ends at t=4 which is outside the specified start and end time.

By specifying additional tagsets, concurrent observation timeseries are retrieved:

$RBB get $DB name=bob name=joe

Output:

`end=3.0,name=bob,start=2.0`	`end=3.0,name=joe,start=2.0`
`name=bob,time=4.0`	`name=joe,time=4.0`

Two Tagsets were specified for the get command: name=bob and name=joe. Together these are called a Problem Set. All combinations of one event from the first tagset and an event from the second tagset are reported, one per line, separated by a space. The start and end times are clamped to the time during which the set of events co-occurred; sets of events that don't co-occur are not reported.

Timeseries

Retrieving timeseries is similar except the timeseries data is included in the output. Following the Brownian Motion example above, run the command:

$RBB get $DB color=pink,src=cmdline color=blue

The output is two columns of approximately 20 short timeseries:

color=pink,id=1,src=cmdline,test=draw color=blue,test=draw
1.0,150.0,100.0 1.0,256.71457,243.55803
4.0,450.0,400.0 4.0,256.16394,304.43698

color=pink,id=1,src=cmdline,test=draw color=blue,test=draw
1.0,150.0,100.0 1.0,233.90707,242.30684
4.0,450.0,400.0 4.0,175.41002,234.18991

color=pink,id=1,src=cmdline,test=draw color=blue,test=draw
1.0,150.0,100.0 1.0,265.10046,247.70923
4.0,450.0,400.0 4.0,282.88406,244.76569

...

All the samples on each row are estimated at the same time. Since the timeseries might not have been observed at the same instant, all but the leftmost timeseries are resampled to the times of the leftmost.

Deleting timeseries

Timeseries and / or events are normally deleted by matching a tagset. In this example no value is specified for the name tag, so any tagset with any value for name matches.

$RBB delete $DB name

Output:

Deleted 3 events

Event-driven processing

RBB supports event-driven processing by sending notifications of Event (or Timeseries) creation or modification over a TCP socket. To get the server address and port number (after starting the TCP server, if necessary), call:

$RBB TCPServer $DB

The client sends one line of input to the server, which lists the tagset for which the client will be notified. (Multiple tagsets can be specified, separated by semicolon ';'). For example, you can watch as Samples are posted to the RBB by the draw program. First run draw:

$RBB ui draw -filterTags test=draw -eventTags test=draw -maxTime 500 $DB &

Then, assuming you have the open-source netcat program:

echo test=draw | nc `$RBB TCPServer $DB`

Now click Play in the draw tool and click-and-drag to create a new timeseries. The nc program will output:

eventCreated    333     18.166  1.7976931348623157E308  test=draw
eventDataAdded  333     18.166  1.7976931348623157E308  test=draw       RBB_TIMESERIES  S333    18.166  713.0   336.0   -18.166
eventDataAdded  333     18.166  1.7976931348623157E308  test=draw       RBB_TIMESERIES  S333    18.217  714.0   339.0   -18.217
eventDataAdded  333     18.166  1.7976931348623157E308  test=draw       RBB_TIMESERIES  S333    18.414  714.0   340.0   -18.414
eventDataAdded  333     18.166  1.7976931348623157E308  test=draw       RBB_TIMESERIES  S333    18.511  714.0   341.0   -18.511
eventModified   333     18.166  18.621  test=draw

Note: The final eventModifed line is produced when the end time of the Timeseries is determined. Prior to this it is assumed to be MAX_DOUBLE.
Note: This CLI tutorial assumes the client is NOT written in Java, for which RBB provides an interface for event-driven clients.