Using the TERR Operator

The TERR operator is a member of the Java Operators group in the Palette view in StreamBase Studio. Select the operator from the Insert an Operator or Adapter dialog. Invoke the dialog with one of the following methods:

In order run correctly, the operator assumes that the machine running StreamBase Server and your application has a 64-bit version of TERR version 2.7 or later installed locally. The TERR operator has been tested and validated with TERR versions 2.7, 3.0, 3.1, and 3.2.

The TERR bin directory does not need to be in the system PATH, and no environment variables are required. The TERR operator recognizes and honors the TERR_HOME environment variable if set, and if it points to the local TERR installation directory; however, setting TERR_HOME is not required.

TIBCO customers can download TERR from http://edelivery.tibco.com, or download an evaluation copy of TERR from the TIBCO Access Point.

To connect StreamBase and its TERR operator to your local TERR installation, you must either:

This operator creates an external TERR process which it then uses to run R scripts and retrieve the results. With each input tuple, the values in the tuple are merged with the supplied script and the script sent to the TERR process for execution. When the script finishes, the result is retrieved and translated into an output tuple.

The script can be supplied as data in the operator itself or can be read from a resource file. The script is a standard R script with one addition: fields in the script that are to be replaced by tuple data must have the format $[name] where name is the name of an input tuple field. The data in the tuple can be any supported simple data type or list of a supported simple data type. The supported StreamBase data types for input are: string, int, boolean, double, list, and timestamp (which is converted to a string). TERR result types supported are: string, int, boolean, double, array (list), byte, factor, and dataFrame.

Script substitution is done on a purely textual basis and it is up to R to parse the results. For example, the string "3", the integer 3 and the float 3 all appear the same when inserted into a script. On input, lists are handled a little differently, with the outer brackets removed. For example, the integer list [1,2,3] is converted to the string "1,2,3". Any substitution variables should be carefully looked at as to context. In general, if a substitution can be either a scalar value or a list, it should probably be placed in a c() construct such as c($[var]), which handles both scalar and list cases.

Booleans are treated specially. On input, a true is converted to TRUE, false is converted to FALSE and null is converted to NA; on output, the opposite conversion is done. For numbers, null is converted to NA.

The operator can be configured to watch the script and dataset files. If either one changes, it is reloaded before the next tuple is processed. This is useful for script development as the script can be in an editor, changes made and the file saved before sending a new tuple.

A single TERR instance can be shared among multiple operators within a container, or each operator can have its own instance. If sharing, take care to ensure that the same initial dataset is specified for each use. This is because the TERR instance is started and initialized by the first instance of the operator to run and the other operators will use the already existing TERR instance. The various parameters used in starting the TERR instance should also be the same for the same reason. Startup parameters are discussed later.

An example script along with some input tuples and results are shown next. First, a TERR script:

n <- $[names]
s <- $[vals]
b <- $[bools]
result <- data.frame(n, s, b)

The input tuple (names="one", vals=2, bools=true) results in:

n <- "one"
s <- 2
b <- TRUE
result <- data.frame(n, s, b)

The input tuple (names=["one","two"], vals=[2,4], bools=[true,null]) results in a TERR parse error, because by default TERR considers each comma as the start of a new field. The solution is to enclose the field variables in c() constructs in your TERR script, like so:

n <- c($[names])
s <- c($[vals])
b <- c($[bools])
result <- data.frame(n, s, b)

In this case, with the same input tuple as above, the results are:

n <- c("one", "two")
s <- c(2, 4)
b <- c(TRUE, NA)
result <- data.frame(n, s, b)

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Operator: A read-only field that shows the formal name of the operator.

Class: A field that shows the fully qualified class name that implements the functionality of this operator. Use this class name when loading the operator in StreamSQL programs with the APPLY JAVA statement. You can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start with application: If this field is set to Yes or to a module parameter that evaluates to true, an instance of this operator starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the operator does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

These options are used to setup the TERR instance.

These options are used to adjust the Java environment for the TERR instance.

Use the Schemas tab to specify the schema of the output tuple for this adapter.

For general instructions on using the Edit Schema tab, see the Properties: Edit Schema Tab section of the Defining Input Streams page.

The custom schema should use the same names for fields as does the generic schema as those are what are looked at when filling the output tuple.

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

The status port emits tuples that describe the status of processing each input tuple. It is only present when the Output Status Tuples option is selected. The schema of the output tuple consists of four strings:

The default schema of the result port consists of:

Because the TERR operator cannot know the data type of the TERR result in advance, the terrResult field contains a subfield for each possible TERR result data type. Only one terrResult subfield is filled in per input tuple, depending on the value assigned to the result variable by the script. The other subfields are left empty (null) for each input tuple.

The top-level schema of the terrResult field is shown in the following table:

Each terrResult subfield is a tuple of lists. The first third-level field of every terrResult subfield is named names. This is a list of one or more names of the result fields of the input script.

You can specify a custom schema that contains only the result data you know to expect. For a custom schema, the names of the fields must be the same as in the default schema described above, and the sub-schemas must also match exactly.