StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References
StreamBase References
This Guide contains reference pages for various StreamBase features.
Contents
StreamBase Data Types
StreamBase Environment Variables
StreamBase Java System Properties
StreamBase Expression Language Features
StreamBase Expression Language Functions
StreamBase Pattern Matching Language
StreamBase Server Configuration File XML Reference
StreamBase Deployment File XML Reference
StreamBase Command Reference
sbadmin â starts the StreamBase Administration Client
jsbadmin â starts the StreamBase Administration Client, Java implementation
sbargen â runs the StreamBase archive generator
sbbundle â Creates StreamBase application bundles.
sbc â starts the StreamBase client to send commands to a running server
jsbc â starts the StreamBase Client, Java implementation
sbcipher â enciphers text or generates cipher keys for use in StreamBase Server configuration files
sbconfutil â Shows as a single file the merged results of multiple configuration file fragments.
sb-config â a tool to determine and set StreamBase-related compiler and linker flags
sbfeedsim â starts the StreamBase Feed Simulator.
sbfeedsim-old â starts the StreamBase feed simulator for legacy feed simulator files.
jsbclientgen â Generates a simple Java dequeue client for the running StreamBase application
sbhelp â starts StreamBase Help Viewer
sb-install-zing-system-support â verifies presence of Azul Zing JDK and installs it
sb-manage-zing-system-support â starts, stops, and provides status of Zing JVM
sbmanager â starts the StreamBase Manager
sbmonitor â starts the StreamBase Monitor utility
sbprofile â Runs the StreamBase profiler to produce formatted statistics about operators and queues
in a running server.
sbproxy â starts the StreamBase Proxy server
sbrecord â Records data enqueued onto all Input Streams
sbd â the StreamBase event processing server
StreamBase References
1
StreamBase References
sbstudio â starts StreamBase Studio
sbtest â runs a unit test defined in a StreamBase test file
sbunit â runs a StreamBase JUnit test defined in a Java JUnit class
sburi â Describes the StreamBase URI format and its shortcut forms.
sbuseradmin â runs the StreamBase authentication system user management tool
StreamBase API Documentation
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
StreamBase References
2
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Data Types
StreamBase Data Types
StreamBase recognizes the following data types:
blob Data Type
bool Data Type
capture Data Type
double Data Type
int Data Type
list Data Type
long Data Type
Named Schema Data Type
string Data Type
timestamp Data Type
tuple Data Type
See Specifying Literals in Expressions for information on entering literals for each data type in expressions.
blob Data Type
Blobs provide a way of representing binary data in a tuple. They are designed to efficiently process large data
objects such as video frames or other multimedia data, although performance might diminish with larger sizes.
In expressions, blobs can be used in any StreamBase function that supports all data types, such as string()
or firstval(). To use a blob in other functions, the blob must first be converted to a supported data type.
For example, error() does not accept a blob, but you can call error(string(b)), where you first
recast the blob as a string.
The StreamBase blob() function converts a string to a blob.
Two or more blob values are comparable with relational operators; the comparison is bytewise.
StreamBase Data Types
3
StreamBase References
bool Data Type
A Boolean always evaluates to either true or false.
Two or more bool values are comparable with relational operators as follows: true > false.
capture Data Type
When you declare a capture field as part of the schema for a hygienic module, you assign a type name for that
capture field. Thereafter, that capture type name appears in the drop-down list of data types in Studio, and can
be referenced as @capture-typename in expressions. While a capture field is not strictly a type of data in
the same sense as the other types on this page, a capture field's type name is effectively a data type in some
circumstances. See Capture Fields in the Authoring Guide.
double Data Type
A double is always 8 bytes. Any numeric literal in scientific notation is considered a double. That is, you do
not need a decimal point for a numeric literal to be recognized as a double (instead of an int). For example,
1e1 is considered to be 10.0 (double) instead of 10 (integer).
Two or more double values are comparable numerically with relational operators.
int Data Type
An int is always 4 bytes. The valid range of the int data type is -2,147,483,648 [â 231] to
2,147,483,647 [231â 1], inclusive. Integers are always signed. Thus, the following expression is not
valid, because the number 2,147,483,648 is not a valid int:
2147483648 + 0
However, integer computations wrap around cleared, so the following expression is valid and evaluates to
-2,147,483,648:
2147483647 + 1
The following expression is valid, because the period means that the number is treated as a floating-point
value, which can have a much greater value:
2147483648. + 0.
Two or more int values are comparable numerically with relational operators.
bool Data Type
4
StreamBase References
list Data Type
A list is an ordered collection of values, called elements, each of which is of the same StreamBase data type,
called the list's element type. The element type can be any StreamBase data type, such as an int, a tuple, or
even a list (thus allowing for constructions such as a list of list of int).
Lists are returned by a variety of functions in the StreamBase expression language, such as list() and
range(). Individual elements in a list can be accessed using their zero-based integer position (their index) in
the list. In any expression in an EventFlow or StreamSQL program, use brackets to address individual
elements of a list. Thus, for a field named L with data type list, use L[0] to address the first element in the
list, L[1] for the second element, and L[length(L)-1] to address the last element.
In most list-related functions that take an index, you can also use a negative index to count backward from the
end of the list. Thus, for a list L, L[-1] is equivalent to L[length(L)-1].
The number of elements in a list can range from zero to a theoretical maximum of 231â 1 elements
(although that maximum cannot be reached in typical practice). The number of elements in a list is determined
at application run-time.
Two or more lists are comparable with relational operators. The comparison is performed lexicographically:
that is, like words in a dictionary, with each element in list AAA compared to its corresponding element in list
BBB, just as the letters in two words are compared, one by one. For example, the list [1, 2, 3] is less than the
list [1, 9, 3], and the list [1, 2] is less than the list [1, 2, 3].
Lists with numeric element types can be coerced if two lists are concatenated or merged in a Union operator,
following the rules listed in Data Type Coercion and Conversion. For example, if you have a list(int) merging
with a list(double), the result is a merged list(double). Two list(tuple) will successfully merge if a valid
supertype tuple can be found. Coercion rules do not apply to output streams with declared, explicit schemas.
See Null Lists for a discussion of null lists compared to empty lists.
Using Lists in Expressions
Most lists you deal with in the StreamBase expression language are tuple fields with a declared list type in the
tuple's schema. You address such a list by means of the field's name, optionally using the bracket syntax
shown above to address individual elements of the list. Functions are provided to append to a list, insert
elements, replace elements, return the first, last, minimum, or maximum element in a list, and much more. See
the list management elements in Simple Functions: Lists.
You can create lists of your own using one of the functions that returns a list, such as list() and range().
As an alternative, you can define a list and specify its contents by placing a comma-separated list of elements
in square brackets. Thus, list(100.00, 130.00, 78.34) and [100.00, 130.00, 78.34]
express the same list.
Viewing and Specifying List Data in CSV Format
In contexts where list data appears in string form, such as the output of of sbc dequeue, lists are output in
standard array format within square brackets. For example:
list Data Type
5
StreamBase References
list(int) [1,3,5]
list(double) [34.78,123.23,90.84,85.00]
Lists of strings do not show each element enclosed in quotes, because the element type of such a list is known
to be string. For example:
list(string) [IBM,DELL,HPQ]
When specifying lists as input to sbc enqueue, enclose the list in quotes to escape the commas inside the list
brackets. For list(string), there is no need to quote each element. For example, to input data for a stream with
schema {int, list(double), list(string), list(int)}, use the following format:
9456,"[234.0,2314.44]","[IBM,DELL]","[3000,2000]"
When specifying strings and lists that occur within a tuple data type, use one pair of quotes around the tuple
value, and use two pairs of quotes to surround the string and list members of that tuple. For example, to input
data for a stream with schema tuple(int, int, int), tuple(string, list(string)), use
the following format:
"1, 3, 3"," ""Alpha"", ""[Beta,Gamma,Delta]"" "
In the example above, quotes surround the first tuple field, consisting of three int values. Quotes surround the
second tuple field, from the comma after the 3 to the end. Within the second field, two pairs of quotes
surround the string sub-field, and surround the list(string) sub-field. Notice that there is still no need to quote
each element of the list(string) sub-field.
When using sbc dequeue with its â v option, elements in a list of strings are shown surrounded with \",
backslash-quote. This is a display-only convention meant to convey that the quotes around list(string)
elements are escaped. Do not use backslash-quote to enter data with sbc enqueue. For example, the previous
example displayed by sbc dequeue -v looks like the following example:
OutputStream1: (tupleid=3,T=(i1=1,i2=3,i3=3),W=(x1="Alpha",
x2="[\"Beta\",\"Gamma\",\"Delta\"]"))
(This example is shown here on two lines for clarity, but appears as a single unbroken line in practice.)
long Data Type
A long is always 8 bytes. The range is -9,223,372,036,854,775,808 [-263] to
+9,223,372,036,854,775,807 [263 -1]. You can use the long data type to contain integer
numbers that are too large to fit in the four-byte int data type.
When specifying a long value in a StreamBase expression, append L to the number. Thus, 100L and
314159L are both long values. Without the L, StreamBase interprets values in the int data type's range as
ints. Values outside the range of an int are interpreted as longs without the L.
Two or more long values are comparable numerically with relational operators.
Viewing and Specifying List Data in CSV Format
6
StreamBase References
Named Schema Data Type
When you define a named schema for a module or interface, StreamBase automatically generates a new
function in the StreamBase expression language that allows you to construct tuples with that schema.
Thereafter, the names of named schemas appear in the drop-down list of data types in Studio, which allows
you to use a named schema's name wherever you would use the tuple data type. Thus, while not strictly a
type of data in the same sense as the other entries on this page, the names of named schemas can be used as an
effective data type. See Named Schema Constructor Function in the Authoring Guide.
string Data Type
A string is a field of text characters.
In previous StreamBase releases, the string data type required specifying the string length. For backwards
compatibility, StreamBase still accepts string length specifications, but silently ignores the length.
The theoretical maximum for a string in a single-field tuple is around 2 gigabytes, but the practical limit is
much smaller. While StreamBase does support large tuples, including large string fields, be aware that moving
huge amounts of data through any application negatively impacts its throughput.
Two or more string values are comparable with the relational operators. By default, strings are compared
lexicographically based on ASCII sort order. If Unicode support is enabled for StreamBase Server (as
described in Unicode Support), string elements are compared in the sort order for the current character set.
timestamp Data Type
The timestamp data type can hold either an absolute timestamp or an interval timestamp.
An absolute timestamp represents a date and time. Its value is the number of seconds between the epoch and
that date and time, with a maximum precision of milliseconds. The epoch is defined as midnight of January 1,
1970 UTC.
An interval timestamp represents a duration. Its value is the number of seconds in the interval, with a
maximum precision of milliseconds.
The range for timestamp values is â 262 to (262 â 1), which holds absolute timestamps for plus or minus
146 million years, and hold interval timestamp values between -4,611,686,018,427,387,904 and
+4,611,686,018,427,387,903.
Absolute timestamps are expressed in the time format patterns of the java.text.SimpleDateFormat
class described in the Sun Java Platform SE reference documentation. For example, the now() function
returns a timestamp value for the current time. The returned value is a representation of the internal value as a
date and time. Thus, the now() function run on 27 May 2011 in the EST time zone returned:
(timestamp) 2011-05-27 12:06:31.968-0400
Named Schema Data Type
7
StreamBase References
By contrast, the expression hours(1) returns an interval timestamp, showing the number of seconds in one
hour:
(timestamp) 3600.0
You can add and subtract timestamp values in expressions, using the rules in the following table:
Operation
Result
Example
days(1) + hours(2)
interval + interval interval
Result: 93600.0, the number of seconds in 26 hours.
days(1) â
hours(2)
interval â
interval
interval
absolute +
interval
absolute
absolute â
absolute
interval
Result: 79200.0, the number of seconds in 22 hours.
now() + hours(1)
Result: an absolute timestamp representing the time one hour from now.
today_utc() - today()
Result: an interval timestamp representing the number of seconds between
midnight UTC and midnight in the local time zone.
absolute +
Error
â
absolute
Two or more timestamp values are comparable with relational operators such as > and <. You must compare
timestamp values interval-to-interval or absolute-to-absolute. You cannot compare interval-to-absolute or
absolute-to-interval.
In comparison expressions that use the operators ==, !=, <=, >=, <, or >, if one side of the comparison is a
timestamp, and the other side is a string literal, StreamBase tries to interpret the string as a valid timestamp. If
the string literal does not contain an explicit time zone, the string is interpreted as having the time zone set in
the operating system of the computer that compiles the application. If the conversion of the string literal fails,
then the comparison fails typechecking.
tuple Data Type
The tuple data type is an ordered collection of fields, each of which has a name and a data type. The fields in
the collection must be defined by a schema, which can be unnamed or named. Fields can be of any
StreamBase data type, including other tuples, nested to any depth. The size of a tuple depends on the
aggregate size of its fields.
See Null Tuples for a discussion of null tuples and empty tuples.
Two or more tuples are comparable with relational operators as long as the tuples being compared have
identical schemas.
The following sections discuss features of the tuple data type:
Addressing Tuple Sub-Fields
timestamp Data Type
8
StreamBase References
Using the Tuple Data Type in StreamSQL
Using the Tuple Data Type in Expressions
Viewing and Specifying Tuple Data in CSV Format
Copying Tuple Contents
Null Tuples, Empty Tuples, No-Fields Tuples
Addressing Tuple Sub-Fields
In expressions, you can address a tuple field's individual sub-fields using dot notation:
tuplename.tuplefieldname.
In an EventFlow application, tuplename is the name of a field of type tuple, and tuplefieldname is
name of a sub-field.
In StreamSQL, tuplename is either:
• The name of a named schema created with CREATE SCHEMA.
• The name of an individual tuple created with the tuple() function, and named with the final AS
keyword.
Using the Tuple Data Type in StreamSQL
In StreamSQL, tuple is not a keyword like string or blob. Instead, you use the tuple data type when you define
a schema, either named or anonymous. The following example shows how the tuple data type is used in
StreamSQL to form a tuple with a tuple sub-field:
CREATE SCHEMA NamedSchema1 (myInt1 int, myDouble1 double);
CREATE SCHEMA NamedSchema2 (myInt2 int, myTuple1 NamedSchema1);
CREATE INPUT STREAM in (
myInt3 int,
AnonTupleField1 (myDouble2 double, myString1 string (8)),
AnonTupleField2 (myString2 string, mySubTuple NamedSchema1)
);
These comments refer to lines with callout numbers in the example above:
Create a named schema containing an int field and a double field.
Create another named schema, this time containing an int field and a tuple field. The tuple field's
schema consists of a reference to the first named schema, and therefore, its fields are MyInt1
and myDouble1. Notice that named schemas are defined independently of any other
component.
The input stream's schema includes an int field followed by two tuple fields with anonymous
schemas.
The second tuple field's schema includes a string followed by a nested tuple, which references
one of the named schemas.
See the CREATE SCHEMA Statement reference page for more on the distinction between named and
anonymous schemas.
tuple Data Type
9
StreamBase References
Using the Tuple Data Type in Expressions
In an expression, use the tuple() function to create both schema and field values of a single tuple.
The name of a named schema automatically becomes a generated function that returns a single tuple with that
schema. See named schema constructor function for details.
Viewing and Specifying Tuple Data in CSV Format
In contexts where a tuple value appears in textual string form, comma-separated value (CSV) format is used.
Examples of such contexts include the contents of files read by the CSV Input Adapter, written by the CSV
Output Adapter, and in the result of the Tuple.toString() Java API method.
Use the nested quote techniques in this section to enter a field of type tuple when specifying input data at the
command prompt with sbc enqueue.
The string form of a tuple with three integer fields whose values are 1, 2, and 3 is the following:
1,2,3
We will refer to the above as tuple A.
When tuple A appears as a field of type tuple inside another tuple, surround tuple A with quotes. For example,
a second tuple, B, whose first field is a string and whose second field is tuple A, has a CSV format like the
following:
IBM,"1,2,3"
These quotes protect the comma-separated values inside the second field from being interpreted as individual
field values.
With deeper nesting, the quoting gets more complex. For example, suppose tuple B, the two-field tuple above,
is itself the second field inside a third tuple, C, whose first field is a double. The CSV format of tuple C is:
3.14159," IBM,""1,2,3"" "
The above form shows doubled pairs of quotes around 1,2,3, which is necessary to ensure that the nested
quotes are interpreted correctly. There is another set of quotes around the entire second field, which contains
tuple B.
StreamBase's quoting rules follow standard CSV practices, as defined in RFC 4180, Common Format and
MIME Type for Comma-Separated Values (CSV) Files (link to the HTML version).
Copying Tuple Contents
You can duplicate any tuple field into another field of type tuple without using wildcards. For example, a Map
operator might have an entry like the following in its Additional Expressions grid, where both
IncomingTuple and CopyOfIncomingTuple are the names of tuple fields:
Action
Field Name
Expression
Using the Tuple Data Type in Expressions
10
StreamBase References
Add
CopyOfIncomingTuple IncomingTuple
Use the .* syntax to flatten a tuple field into the top level of a stream.
For example, a Map operator might define an entry like the following in its Additional Expressions grid.
When using this syntax, you must have an asterisk in both Field Name and Expression columns.
Action Field Name
Expression
Add
*
IncomingTuple.*
Use the * AS * syntax for tuples defined with a named schema to copy the entire tuple into a single field of
type tuple.
For example, let's say the tuple arriving at the input port of a Map operator was defined upstream with the
NYSE_FeedSchema named schema. To preserve the input tuple unmodified for separate processing, the
Map operator could add a field of type tuple using settings like the following in the Additional Expressions
grid. When using the * AS * syntax in the Expression column, the name of the tuple field in the Field Name
column has an implied asterisk for all of its fields.
Action Field Name
Expression
Add
OriginalOrder NYSE_FeedSchema(input1.* as *)
Because the Map operator has only one input port, the port does not need to be named:
Action Field Name
Expression
Add
OriginalOrder NYSE_FeedSchema(* as *)
Null Tuples, Empty Tuples, No-Fields Tuples
A null tuple results when the entire tuple is set to null (not just the fields of the tuple).
An empty tuple is a tuple with each individual field set to null.
A no-fields tuple is what is sent to an input stream that has an empty schema, which is a schema with no fields
defined, as described in Using Empty Schemas. An input stream with an empty schema might be declared, for
example, as a trigger for a Read All Rows operation on a Query Table. In this case, the tuple sent to this input
stream is itself neither null nor empty, it is a no-fields tuple.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
Copying Tuple Contents
11
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Environment Variables
StreamBase Environment Variables
StreamBase recognizes a set of environment variables that affect the behavior of StreamBase Server; some
variables affect StreamBase Studio. You can define StreamBase environment variables using any of the
methods native to your system. Environment variables control and take precedence over certain properties
defined in StreamBase Server configuration files.
Environment variable expansion in StreamBase Server configuration files is not limited to the variables on
this page. The values of all variables in the environment that starts the StreamBase Server instance can be
used, as described in Using Environment Variables in Configuration Files.
The environment variables on this page affect:
• The behavior of the next StreamBase Server instance or client you start. That is, a change in an
environment variable setting does not affect a currently running server or client.
• The behavior of clients built with the StreamBase C++ or .NET APIs. (Java clients use Java
properties instead of environment variables, as described in StreamBase Java System Properties.)
The environment variables are:
• SB_CLIENT_CLASSPATH
• STREAMBASE_APPGEN_ERROR_SCHEMA_VERSION
• STREAMBASE_CODEGEN_TRACE_TUPLES
• STREAMBASE_CRASH_HANDLER
• STREAMBASE_CRASH_QUIET (Windows only)
• STREAMBASE_CRASH_TRACE (Linux only)
• STREAMBASE_DATA
• STREAMBASE_HOME
• STREAMBASE_LOG_LEVEL
• STREAMBASE_JVM_ARGS
• STREAMBASE_MAX_INPUT_PACKET_SIZE
• STREAMBASE_PACKING_PERCENT
• STREAMBASE_QUIESCENT_LIMIT
• STREAMBASE_RECONNECT_SLEEP
• STREAMBASE_RETITLE_TERMINALS
• STREAMBASE_SERVER
StreamBase Environment Variables
12
StreamBase References
• STREAMBASE_STUDIO_VMARGS
• STREAMBASE_TCP_NODELAY
• STREAMBASE_TUPLE_CONNECTION_QUIESCENT_LIMIT
• STREAMBASE_TUPLE_CONNECTION_TIMEOUT
• STREAMBASE_USE_INTERNAL_JDK
• STREAMBASE_USE_CUSTOM_LOGGING
• STREAMBASE_XMLRPC_TIMEOUT
• STUDIO_BOOT_CLASSPATH
• TMP
Notes
• On Windows, environment variables that you explicitly set take precedence over any corresponding
StreamBase keys in the Windows registry. For further information, see Running StreamBase Server
as a Windows Service, in the Administration Guide.
• The StreamBase installer does not set the STREAMBASE_HOME or PATH environment variables,
which allows support for installing multiple versions of StreamBase. See StreamBase Command
Prompt for details.
SB_CLIENT_CLASSPATH
Use this variable in conjunction with the STREAMBASE_USE_CUSTOM_LOGGING variable. When
setting that variable to true, set SB_CLIENT_CLASSPATH to the full, absolute path to sbclient.jar or
one of its alternatives (sbclient-no-logging-backend.jar or sbclient-no-logging.jar).
See Using StreamBase Logging to understand these alternatives.
STREAMBASE_APPGEN_ERROR_SCHEMA_VERSION
Set to 1 to emit error tuples using the pre-7.1 schema, with the orginalTuple field emitted as a blob. Set
to 2 (the default in StreamBase 7.1.0 or later) to emit error tuples using the 7.1+ schema, with
originalTuple emitted as a JSON object string. This variable is also available as a Java system property,
streambase.appgen.error-schema-version. See Managing Error Tuple Schema Upgrades for
more on this subject.
STREAMBASE_CODEGEN_TRACE_TUPLES
When set to true, you can use the runtime tracing features of StreamBase Server, as described in Runtime
Tracing and Creating Trace Files. You can make the same setting with the
-Dstreambase.codegen.trac-tuples=true system property.
STREAMBASE_CRASH_HANDLER
When set to yes (the default), the StreamBase Server process can create a crash dump in the event of a
segmentation fault.
Notes
13
StreamBase References
STREAMBASE_CRASH_QUIET
When set to yes (the default), the StreamBase Server process can create the crash dump without having to
launch a dialog box. The no setting may be appropriate in development, but should not be used in production,
or when you are starting the StreamBase Server as a service.
STREAMBASE_CRASH_TRACE
Available on Linux only. If the STREAMBASE_CRASH_HANDLER value is yes (the default),
STREAMBASE_CRASH_TRACE=yes causes the crash handler to print a stack trace.
STREAMBASE_DATA
Sets the directory to be used for persistent data when using disk-based Query Tables (available only in
StreamBase Enterprise Edition). The precedence order is:
1. If present on the sbd command line, the path specified in the --datadir option.
2. The path specified with this STREAMBASE_DATA environment variable, if present.
3. In the server configuration file, the value of the datadir parameter in the server section.
4. On Windows only, the path specified in the Windows Registry at the following location:
HKEY_LOCAL_MACHINE\SOFTWARE\StreamBase
Systems\StreamBase.n.m\DataDir
5. If not specified, or if the special value +TEMP+ is used, a temporary directory is created on server
startup and deleted on shutdown.
For more information, see Using the Query Table Data Construct in the Authoring Guide.
STREAMBASE_HOME
Specifies the directory in which StreamBase was installed. On UNIX, set this variable before running
StreamBase commands. For example:
export STREAMBASE_HOME=/opt/streambase
The recommended method to set StreamBase environment variables on UNIX, and an essential method if you
use the tar.gz installation method, is to use sb-config --env, as shown in this example:
eval `/opt/streambase/bin/sb-config --env`
On Windows, before release 5.0, this and the PATH environment variable were set by the StreamBase
installer. Beginning in release 5.0, StreamBase does not set these variables, because you can now install
multiple versions of StreamBase on Windows. StreamBase instead provides the StreamBase Command
Prompt in the Start menu. For StreamBase 5.0 and later, run StreamBase utilities and start the sbd server
process from a StreamBase Command Prompt, not an ordinary Windows command prompt.
STREAMBASE_CRASH_QUIET
14
StreamBase References
If you have a single StreamBase installation on a Windows machine, you may prefer to set
STREAMBASE_HOME and PATH in the global environment with sb-config --setenv . If you have a mixed
installation of StreamBase 3.x and 6.x, do not use --setenv, as explained in StreamBase Command
Prompt.
The first command below sets the global environment for the currently logged-in Windows user. The second
command does the same for all users.
"C:\Program Files\StreamBase Systems\StreamBase.n.m\bin\sb-config" --setenv
"C:\Program Files\StreamBase Systems\StreamBase.n.m\bin\sb-config" --setsysenv
STREAMBASE_HOME is referenced in the template sbd.sbconf configuration file for the StreamBase
Server. The following is an example of STREAMBASE_HOME used in sbd.sbconf:
<authentication>
<param name="enabled" value="true"/>
<param name="type" value="sb-password-file"/>
<param name="filepath" value="${STREAMBASE_HOME}/etc/sbpasswd"/>
</authentication>
STREAMBASE_LOG_LEVEL
Sets the level of information, warning, and debug messages emitted by StreamBase Server. For all supported
platforms, the log levels are integers from -2 to 3, inclusive. See the table in Log Levels to understand the log
level meanings.
Note that setting the STREAMBASE_LOG_LEVEL variable is only useful when running sbd interactively in
StreamBase Command Prompts or in UNIX terminal windows. When you run sbd in background mode with
the -b flag, it is configured by default to write messages to syslog instead of to stdout. See Server
Background Mode and Logging for more information.
STREAMBASE_JVM_ARGS
The variable is largely superseded by the -J option, which is honored by the same set of commands listed
below. For more on the -J option, see the reference page for any of those commands.
Use STREAMBASE_JVM_ARGS to specify one or more arguments to append to the default arguments for the
JVM that will run a StreamBase command. For example, set STREAMBASE_JVM_ARGS=-Xms1024M to
specify a minimum of one gigabyte of RAM. Remember that if you change any of the primary
memory-setting JVM arguments (-Xms, -Xmx, -XX:MaxPermSize, and for 64-bit servers,
-XX:+UseCompressedOops), then the StreamBase Server defaults for those settings no longer apply.
Thus, if you set one of these settings with this variable, set them all.
The following commands from the base StreamBase kit check for and append the contents of this variable to
their startup routines: jsbadmin, jsbc, jsbclientgen, sbargen, sbbundle, sbcipher, sbd, sbfeedsim,
sbprofile, sbproxy, sbrecord, and sbtest. The following commands from external adapter kits also respond
to this variable: sb-ems-* and sb-jdbc.
STREAMBASE_HOME
15
StreamBase References
Because so many commands are affected by this variable, it is unwise to export this variable to the global
environment, because the JVM settings for one command are not likely to be appropriate for all commands.
Instead, use it for ad hoc adjustments to the JVM arguments per invocation. For the Bash shell on UNIX, use
syntax like the following:
STREAMBASE_JVM_ARGS=settings sbbundle sbbundle-args
For Windows, you can configure per-invocation usage by wrapping the command of interest in a batch script,
surrounded by setlocal and endlocal commands.
STREAMBASE_MAX_INPUT_PACKET_SIZE
Use STREAMBASE_MAX_INPUT_PACKET_SIZE to increase the maximum size of packets used by C++
clients when communicating with StreamBase Server. If unspecified, the default is 1 megabyte.
STREAMBASE_PACKING_PERCENT
To use StreamBase 3.7 clients with StreamBase Server and the proxy server from release 6.3 or later, you
must set the environment variable STREAMBASE_PACKING_PERCENT to zero on the hosts (and user
environments) running both the proxy server and the client.
STREAMBASE_QUIESCENT_LIMIT
This environment variable controls how many milliseconds a C++ StreamBase dequeuing client will tolerate
not receiving anything from the StreamBase Server to which it is connected. The default value is 120 seconds
(120000). By default, StreamBase Servers emit client heartbeats every 10 seconds, so that StreamBase
applications have no requirement to send data regularly.
StreamBase Servers can be configured to send heartbeats faster, slower, or not at all. The quiescent timer only
starts after the first heartbeat is received; so if a server never sends a heartbeat, clients will not have quiescent
protection.
STREAMBASE_RECONNECT_SLEEP
When designing a high availability StreamBase cluster, you can use this environment variable for clients, to
set how often the client should try to reconnect to the primary or secondary machine when the connection to
the server is dropped. The value is in milliseconds. The default is 5000 (5 seconds). This environment variable
is useful with C++ clients. By contrast, Java clients can use the streambase.reconnect-sleep system
property as described in StreamBase Java System Properties.
STREAMBASE_RETITLE_TERMINALS
If set to any value, StreamBase programs assign a terminal window title to match the name of the executable
being run. By default, terminal titles are not affected. On UNIX, this can be helpful if you have many terminal
STREAMBASE_JVM_ARGS
16
StreamBase References
windows open for sbd, sbfeedsim, sbc dequeue, sbmonitor, and so on.
STREAMBASE_SERVER
The URI for StreamBase Server. The default is sb://localhost:10000. You can set this environment
variable if the Server is on another node or listening on another port. For example, if the Server is running on
host server.example.com at port 20000, set the STREAMBASE_SERVER value as
sb://server.example.com:20000. This environment variable can be read by C++ clients, adapters,
and most StreamBase command-line utilities (such as sbc) to determine a non-default StreamBase Server
location or port.
STREAMBASE_STUDIO_VMARGS
Specifies a list of arguments for the JVM that runs StreamBase Studio. This variable should only be necessary
on rare occasions, usually under the direction of StreamBase Systems Technical Support.
Important
Using this variable overrides and replaces the default vmargs passed to Studio. If you use the variable for
any purpose, you MUST include the default values like the following.
STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx768M -XX:MaxPermSize=256M
On 64-bit platforms with physical RAM of 4 GB or more, you can set the â
such as â Xmx1024m or even â Xmx2048m.
Xmx setting to a larger value,
To use this environment variable correctly, set the default values, then add your setting at the end:
STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx512M -XX:MaxPermSize=256M \
-Dyour-setting
For example:
STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx512M -XX:MaxPermSize=256M \
-Dstreambase.tuple-charset=UTF-8
You may also want to re-specify the default GC settings as described in Garbage Collection Policy Settings
STREAMBASE_TCP_NODELAY
Set STREAMBASE_TCP_NODELAY to true to disable the Nagle algorithm on network connections. In
addition, for Java clients, you can set the system property streambase.tcp.nodelay to true. While it
is best to set STREAMBASE_TCP_NODELAY on both the client and server, setting it on the server is often
more important than setting it on the client.
STREAMBASE_RETITLE_TERMINALS
17
StreamBase References
Note
Disabling the Nagle algorithm can improve latency characteristics, but it can also make network utilization
less efficient. This may reduce the maximum throughput rates for a given network interface.
STREAMBASE_TUPLE_CONNECTION_QUIESCENT_LIMIT
When designing a high availability StreamBase cluster, you can use this environment variable in conjunction
with client dequeue heartbeats to set the timeout for dequeues. The value is in milliseconds, and the default is
120000 (120 seconds). By default, StreamBase Servers emit client heartbeats every 10 seconds, so that
StreamBase applications have no requirement to send data regularly. StreamBase Servers can be configured to
send heartbeats faster, slower, or not at all. The quiescent timer only starts after the first heartbeat is received.
Thus, if a server never sends a heartbeat, clients will not have quiescent protection.
This environment variable is useful with C++ clients. By contrast, Java clients can use the
streambase.tuple-connection-quiescent-limit system property as described in StreamBase
Java System Properties.
STREAMBASE_TUPLE_CONNECTION_TIMEOUT
When designing a high availability StreamBase cluster, you can use this environment variable for clients, to
set a timeout value on reads and writes between the client and server. This timeout is used by the client to
recognize failure of the server. Consider carefully when using this property. A timeout value that is too long
may cause the client to hang for that period before it fails over to the other server. Too short of a value may
cause the client to disconnect prematurely from the server if the server is busy. The value is in milliseconds,
and the default is 15000 (15 seconds). A value of 0 disables the timeout (some operations will block forever).
For further information, see Creating C++ Clients.
This environment variable is useful with C++ clients. By contrast, Java clients can use the
streambase.tuple-connection-timeout system property as described in StreamBase Java System
Properties.
STREAMBASE_USE_INTERNAL_JDK
If set to true (the default value), or if not set, StreamBase uses its internal JDK installed in
streambase-install-dir/jre, and ignores any setting of the JAVA_HOME environment variable.
This applies to both StreamBase Studio and StreamBase Server run independently of Studio with the sbd
command.
If set to false, Studio and sbd use the external JDK defined in the JAVA_HOME environment variable.
JAVA_HOME must be set to the full, absolute path to the top-level directory containing your JDK.
If set to false, but no JAVA_HOME is defined, StreamBase searches the system PATH for a JDK. If not
found, StreamBase looks in standard installation locations for a JDK. If still not found, neither Studio nor sbd
will start.
Note
18
StreamBase References
STREAMBASE_USE_CUSTOM_LOGGING
If set to true, StreamBase automatically calls sbclient-no-logging-backend.jar wherever
sbclient.jar would be used. This allows you to use an alternative Java logging system as described on
Using StreamBase Logging. When set to true, the JAR files that support your alternative logging system must
be specified on the Server's classpath, or in a jar child element of the java-vm element of the server
configuration file. You can also specify the path to sbclient.jar (and its embedded Logback logging) or
to one of its alternatives with the SB_CLIENT_CLASSPATH environment variable described above in
SB_CLIENT_CLASSPATH.
STREAMBASE_XMLRPC_TIMEOUT
Specify a timeout value in milliseconds that clients built with the StreamBase Client Library will wait for a
response from StreamBase Server. This setting applies in the rare case when the server is alive and listening,
but not responding.
STUDIO_BOOT_CLASSPATH
Use this environment variable to place Java code in the classpath of StreamBase Studio, and of StreamBase
Server as launched from Studio. For example, set STUDIO_BOOT_CLASSPATH, pointing to the full,
absolute path to a database vendor's JDBC JAR file in order to use a JDBC database as the data source for a
feed simulation. See Feed Simulation with a JDBC Data Source for details.
TMP
StreamBase Server writes internally generated temporary files to a temporary directory. The location of the
temporary directory used is the first valid directory path found in the following search sequence:
â Specified with the streambase.tmpdir Java system property
â The value of the TMP environment variable
â Specified with the java.io.tmpdir system property (Windows only)
â /var/tmp on UNIX or C:\Windows\Temp on Windows
Because the TMP environment variable is used before java.io.tmpdir, on Windows, make sure that any
TMP environment variable you use specifies a path with no spaces in any path element. If another program
requires a TMP path with spaces, then use the streambase.tmpdir property to override the temporary
directory location for StreamBase Server.
The java.io.tmpdir system property uses a platform-specific algorithm to identify a temporary
directory. On Windows, this search calls the Windows API GetTempPath(), which searches the TMP,
TEMP, and USERPROFILE environment variables in that order. In Windows domain login environments, it
is possible that your USERPROFILE directory is on a network share, and it is also possible that TMP or
TEMP variables point to a subdirectory of your USERPROFILE directory on a network share. In these cases,
explicitly set streambase.tmpdir or explicitly set TMP in the environment that runs StreamBase Server
to avoid writing temporary files to a network location.
STREAMBASE_USE_CUSTOM_LOGGING
19
StreamBase References
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
TMP
20
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Java System Properties
StreamBase Java System Properties
The StreamBase Java Client library uses the Java system properties described on this page. You can set
properties on the Java command line using -Dproperty-name=value when you start a StreamBase
client, or you can set the property in your Java client code using the System.setProperty() method.
The following example shows command line usage:
java -Dstreambase.tuple-connection-timeout=4000 \
-Dstreambase.reconnect-sleep=7000 MyClient
Or, in your Java client code:
System.setProperty("streambase.tuple-connection-timeout", "4000");
Note
Each system property on this page can also be implemented as an environment variable. If both environment
variable and system property are specified for the same setting, the system property prevails. To convert a
system property from the table below to an environment variable, uppercase all letters, and substitute an
underbar for periods and hyphens. For example, convert streambase.tcp-nodelay to
STREAMBASE_TCP_NODELAY.
The following table describes the StreamBase Java system properties.
Property Name
Description
streambase.appgen.error-schema-version
Set to 1 to emit error tuples using the pre-7.1 schema, with the orginalTuple field emitted as a blob.
Set to 2 (the default in StreamBase 7.1.0 or later) to emit error tuples using the 7.1+ schema, with
originalTuple emitted as a JSON object string.
streambase.check-app-environment-variables-changed
Set to true or false. When true, StreamBase Server runs the precompiled archive file present in a
bundled archive file it is asked to run, and does not recompile the EventFlow or StreamSQL source files in
the bundle.
StreamBase Java System Properties
21
StreamBase References
Under some circumstances, StreamBase Server can emit warning messages at startup that indicate an
environment variable has changed since the application was compiled. In most cases, these warnings have
no consequences and can be ignored. However, when the server is loading a bundle file that includes a
precompiled archive file, an environment variable warning message has the unintended side effect that the
server ignores the bundled archive file and recompiles the application from the bundled source files. The
bundled application does run normally, but for very large applications, at the cost of the recompilation
time.
streambase.client.max-tuples-in-queue
Specify an integer maximum number of tuples allowed in the client connection queue, to promote better
client behavior. The default value is 10000 tuples. This Java property also affects the queue of incoming
tuples when using the StreamBase to StreamBase input adapter.
streambase.client.log-connection-status
Set to true or false; the default is false. In the default setting, StreamBase clients log both
connection and disconnection events at the DEBUG level. Set to true to have your clients log at the
INFO level for connection events and at the WARN level for disconnection events.
This property is available since release 7.3.0, and requires your client code to import
com.streambase.sb.client.ConnectionStatusCallback.
streambase.codegen.trace-tuples
Set to true or false. When true, you can use the runtime tracing features of StreamBase Server, as
described in Runtime Tracing and Creating Trace Files.
streambase.codegen.generate-bytecodes
streambase.codegen.compileinprocess
streambase.codegen.jarinprocess
Use these properties together to specify that StreamBase Server is to use an external javac command to
compile EventFlow and StreamSQL instructions to byte code, instead of using an internal compilation
process (the default). Using an external compiler can increase the memory available for large applications
on memory-constrained systems, such as 32-bit Windows. To specify this option, set both
compileinprocess and jarinprocess to false, and set generate-bytecodes to javac.
Using these three system properties is the same as selecting the Compile StreamBase application in
separate process option on the Main tab of StreamBase Studio's Launch Configuration dialog.
streambase.codegen.digest-type-names
Set to true or false; the default is true. Some file systems supported by StreamBase restrict the
maximum length of file names. To avoid hitting these limits, StreamBase uses a hash to shorten the
internal names of code generated by compiling EventFlow XML and StreamSQL code, and to avoid name
collisions in that internal code namespace. These shortened names make debugging StreamBase internal
code more difficult. Set this property to false to temporarily disable internal code name shortening to
improve readability while debugging, at the cost of occasionally encountering a file name collision or
length restriction.
streambase.codegen.intermediate-stream-dequeue-regex
Limits the number of output streams the application will expose when running in debug mode, by setting
the server's JVM property to include the this property set to a regular expression pattern, using an
argument of the form regex=expr
For example, you can set the JVM arguments to include a pattern like the following:
-Dstreambase.codegen.intermediate-stream-dequeue-regex=Map\\d
Note
22
StreamBase References
This allows any intermediate stream that contains the pattern of "a Map followed by a digit" to be exposed
as a dequeueable stream. All other intermediate streams normally available in debug mode will not be
available.
streambase.ide.component-exchange-force-auth
Set to true or false. Use this property in conjunction with the site-specific Component Exchange
feature described in StreamBase Studio Panel and Site-Specific Component Exchange. If you supply a
URL that begins with HTTPS or FTP, Studio automatically prompts for credentials. If you supply a URL
for another protocol, you can force authentication prompting for that protocol by setting this property to
true for the VM that runs Studio.
streambase.ide.debugger.remote-call-timeout-ms
The default value is 10000 (10 seconds). Set this property to change the timeout period that prevents the
EventFlow Debugger from hanging in rare cases of hung remote calls.
streambase.jdbc.max-repeat-exceptions
The default value of 1 tells StreamBase Server that a single instance of a JDBC exception is regarded as an
exception. Specify zero to mean that JDBC exceptions can be repeated without limit. Use an integer, n,
greater than 1 to specify that JDBC exceptions might occur n times before succeeding.
streambase.log-adapter-async
Set to true or false. Use this property to set the synchronous state of all Log adapter instances in an
application at the same time, without having to edit the Properties view for all Log adapters in the
application. Set to true to force all Log adapters to enable the Log Asynchronously option. Set to false
to restore the default synchronous state of all Log adapters. See The Log Asynchronously Option.
streambase.log-level
Specify an integer value, one of -2, -1, 0, 1, 2, or 3. Sets the severity of log messages emitted by the
standard StreamBase logging mechanism, Logback. See the table Log Levels for a mapping of integer
keys to logging levels. The default is 0, which provides INFO level messages and higher.
streambase.low-latency-mode
Set to true or false; false is the default. This switch provides a single switch that enables several
other properties to direct StreamBase Server to run in low latency configuration. Setting this property to
true performs the following subordinate actions:
• Enables the low latency option on all StreamBase to StreamBase adapters, including those used
internally to implement remote container connections.
• Enables the streambase.tcp-nodelay system property, which disables the Nagle algorithm
on network connections.
• Sets the system property streambase.queue-flush-interval to zero, which disables
queue flushes for client connections.
• Sets low latency mode on dequeue output queues.
streambase.operator.parameters.log-level
Specify an integer corresponding to the StreamBase log level in which you want operator property log
entries included. Specify 0=OFF to disable this feature, or specify 1=ERROR, 2=WARN, or 3=INFO.
When set to 1, 2, or 3, StreamBase log messages include entries for each property setting for all operators
and adapters that inherit from the Operator class in the StreamBase Client Library. This includes any
custom Java operators and most adapters, but does not include global operators such as the Map or Filter
operators included with StreamBase.
The messages are sent from the Operator caretaker class, and are in the format of the following example,
Note
23
StreamBase References
where this setting was set to 1:
2010-12-01 12:58:28.030-0500 [Thread-4] ERROR \
c.s.sb.runtime.OperatorCaretakerImpl - \
Operator: OrderInput, Parameter: OrderManagementPort, \
Value: 8889
Values set with variables in the operator or adapter's Properties view are shown with the variable's runtime
expansion. For example, the value of the OrderManagementPort property in this example was specified
with ${MGMTPORT} but is shown in the log message with its runtime value, 8889.
If an adapter uses an adapter-specific configuration file, the file's name is shown as a property setting.
However, the contents of such configuration files are not shown.
streambase.max-queue-size
Specify an integer number of result sets, the maximum size of the queue that a StreamBase client is to
maintain when dequeuing result sets. Each result set entry contains a list of tuples. The default is 500 result
sets.
streambase.max-stat-tuples-cache
Specify an integer number of tuples, the default maximum size of the system.statv2 stream's tuple
cache, which grows dynamically as needed by the application. The default value of â 1 means the
statistics stream cache can grow as large as needed, limited only by available memory. (For StreamBase
releases before 7.0, the statistics stream was named system.stat.)
streambase.queue-flush-interval
Specify an integer number of milliseconds to wait between queue flushes for client connections. The
default is 20. Set this value to a lower number to improve latency. While setting this value to 0 does
minimize latency, a zero setting may have an impact on the system load.
streambase.read-buf-size
Specify an integer number of bytes, the default read buffer size used by the client when dequeuing tuples.
Changing this value may have an effect on client dequeue performance. The default value is 32768 (32K
or 32*1024).
streambase.reconnect-sleep
Specify an integer number of milliseconds to set how often a StreamBase client should try to reconnect to
the primary or secondary StreamBase Server in a high availability StreamBase environment when the
connection to the server is dropped. The default is 5000 (5 seconds).
streambase.runtime.send-zero-stats
Set to true or false. The default setting is true, which means the statv2 stream of the system
container includes tuples with zero values. Set this property to false to exclude zero value tuples from
the system.statv2 stream (or the system.stat stream in StreamBase releases before 7.0). This
excludes zero value tuples from consideration in the statistics shown by StreamBase Monitor and
StreamBase Manager.
streambase.runtime.stream-queue-max-buffer
Specify the number of bytes to which you wish to limit buffer doubling. Default value is 1 GB per buffer.
The value must be a power of 2. New buffers are only needed if the consuming region continues to be
slower than the producing region. Before a new buffer is allocated, the producing region will pause briefly
in an effort to aid the consuming region to catch up.
streambase.sbd.max-input-packet-size
Specify an integer maximum number of bytes per packet, the maximum limit sent to the server in a client
enqueue connection. The default value is 67108864 (64 MB, or 64*1024*1024).
Note
24
StreamBase References
streambase.sbd.max-tuples-in-dequeue-packet
Specify an integer maximum number of packets the server includes in any one dequeue packet. The default
value is 10000, which matches the default of the streambase.client.max-tuples-in-queue
property described above. Administrators can set both server and client with matching values to make sure
client dequeues are not overwhelmed.
streambase.sbd-shrink-after-process
Set to true or false; the default setting is false. Set to true for servers with dozens of StreamBase
client connections. This forces client buffers to shrink after each use instead of remaining a fixed size,
which reduces the overall memory footprint of the server, at the expense of higher memory churn and
consequent garbage collection.
streambase.tcp-nodelay
Set to any value, such as 1, to disable the Nagle algorithm for StreamBase Server and for StreamBase
clients. The Nagle algorithm is a throughput optimization implemented by default in the TCP/IP network
code of the Server and Client Libraries. The algorithm adds about 40 milliseconds of latency on Linux and
about 200 milliseconds on Windows. Make this setting independently for Server and clients.
streambase.tuple-connection-quiescent-limit
Specify an integer number of milliseconds, the timeout value for how long a Java StreamBase dequeuing
client tolerates not receiving anything from the StreamBase Server to which it is connected. The default
value is 120000, or 120 seconds. By default, StreamBase Servers emit client heartbeats every 10 seconds,
so that StreamBase applications have no requirement to send data regularly. StreamBase Servers can be
configured to send heartbeats faster, slower, or not at all. The quiescent timer only starts after the first
heartbeat is received. Thus, if a server never sends a heartbeat, clients do not have quiescent protection.
streambase.tuple-connection-timeout
Specify an integer number of milliseconds. In a high availability StreamBase application environment, this
property sets a timeout value on reads and writes between the client and server. This timeout is used by the
client to recognize failure of the server. The default value is 15000 (15 seconds). A value of 0 disables the
timeout (some operations will block forever).
Consider carefully when using this property. A timeout value too long may cause the client to hang for that
period before it fails over to the other server. Too short of a value may cause the client to disconnect
prematurely from the server if the server is busy.
streambase.uri
Overrides the default URI of the StreamBase Server instance to which connections are to be made. The
default is sb://localhost:10000. See sburi for the syntax of StreamBase URIs.
streambase.write-buf-size
Specify an integer number of bytes, the default read buffer size used by the client when enqueuing tuples.
Changing this value may have an effect on client enqueue performance. The default value is 32768 (32K
or 32*1024).
streambase.xmlrpc-timeout
Specify an integer number of milliseconds to set a timeout value that clients built with the StreamBase
Client Library are to wait for a response from StreamBase Server. This setting applies in the rare case
when the server is alive and listening, but not responding. The default value is zero, which specifies no
timeout.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
Note
25
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Expression Language Features
StreamBase Expression Language Features
This topic describes the StreamBase expression language and each of the built-in functions that you can use
with StreamBase applications. In EventFlow applications, you use StreamBase functions in operators that take
expressions. You can also use StreamBase expressions in statements in StreamSQL applications, as described
in the StreamSQL Guide.
Reference Pages
StreamBase Environment Variables
StreamBase Java System Properties
StreamBase Expression Language Functions
Using StreamBase Functions
Function Assistance in StreamBase Studio
Using Your Own Functions in Expressions
Evaluating Expressions with sbd --eval
Using Quotes in Expressions
Data Types
Case Sensitivity
Identifier Naming Rules
Reserved Words
Qualifying Field Names
Arithmetic Operators
Modulus Operator
IN Operator
Between-And Operator
Unary Operators
Relational Operators
Logical Operators
Precedence Order
White Space
StreamBase Expression Language Features
26
StreamBase References
Comments
Specifying Literals in Expressions
Null Literals
Conditional Expressions
Compound Conditional Expressions
Concatenation in Expressions
Timestamp Expressions
Parameters in Expressions
Using StreamBase Functions
This topic provides reference information for the StreamBase expression language.
StreamBase provides two types of functions:
Simple Functions
The majority of functions in the StreamBase expression language are simple functions, which operate
on a single tuple field at a time. You can use simple functions in expressions for any StreamBase
operator (except the Heartbeat, Metronome, and Union operators, which do not accept expressions).
Aggregate Functions
Aggregate functions are used on sets of data to return a single result. Aggregate functions evaluate
columns of data from windows or tables. In EventFlow applications, aggregate functions can only be
used:
• In aggregate expressions in Aggregate operators
• In output expressions in Query Operators that perform Read or Delete operations
In StreamSQL applications, aggregate functions can be used in SELECT statements related to
aggregate or query read or delete operations.
StreamBase provides sample applications that feature custom functions for you to load into StreamBase
Studio to see how they are built and configured. The custom sample applications are listed in Extending
StreamBase Samples.
Back to Top ^
Function Assistance in StreamBase Studio
StreamBase Studio provides the following user assistance features to aid writing expressions:
Expression Auto-completion
When the cursor is in a field in the Properties view that accepts expressions, press Ctrl+Space to
open a command-completion dialog. Type a few letters to show the expression language functions
that begin with those letters. Select a function to see its syntax and description in a separate pane.
Press Enter to finish typing from the selected function. See Expression Auto-Completion and Content
Assistance for more on auto-completion.
Functions Tab in Properties View
The Functions tab shows a categorized list of all expression language functions. Type a regular
expression in the filter box to narrow the selection to matching functions. Double-click a function
name to see its syntax and description in the Detail sub-tab.
Reference Pages
27
StreamBase References
Expression QuickRef Tab in Properties View
The Expression QuickRef tab shows a summary of the features of the expression language. Click a
Show in Help link to open the corresponding section of this page in the Help window.
See Properties View for more information on these features.
Back to Top ^
Using Your Own Functions in Expressions
If you do not find a built-in function that you need, you can use the StreamBase custom function APIs to
implement your own function and configure your application to use it. Your custom functions can be written
by extending the StreamBase APIs for Java or C++. For details on writing your own functions, see these
topics in the API Guide:
• Developing Custom Functions
• Using the StreamBase Java Function Wizard
• Creating Custom C++ Functions
You can call your custom functions in expressions by calling a function alias you have declared in the server
configuration file, or by using calljava() or callcpp().
Using Function Aliases
You can define aliases for your custom functions using the custom-function element in the StreamBase
Server configuration file. This allows you to reference your custom functions directly, without using a
calljava() or callcpp() function. For example:
myCustomFunction(x, y)
See <custom-functions> for instructions on defining aliases for your custom functions.
Back to Top ^
Evaluating Expressions with sbd --eval
Use the sbd --eval command to evaluate and test your expressions at the command prompt before using them
in your StreamBase applications. sbd --eval works with simple functions, but not with aggregate functions.
You must evaluate aggregate functions using other methods, such as running a test application and checking
the results.
On Windows, be sure to run sbd --eval from the StreamBase Command Prompt, not a standard Windows
command prompt.
Note
Some functions in the StreamBase expression language do not work with sbd --eval because the --eval
option causes sbd to run with a limited environment and immediately exit after the function evaluation. This
Function Assistance in StreamBase Studio
28
StreamBase References
includes any function that requests the status of the server or its environment, or that requests a further
function evaluation.
The following expression language functions are not expected to work with sbd --eval:
get_conf_param()
getNodeName()
get_boolean_conf_param() getParallelRoot()
get_inf_conf_param()
getPath()
get_long_conf_param()
getServerURI()
get_double_conf_param() securitytag()
getContainer()
eval()
getLeadeshipStatus()
The following examples show how to use sbd --eval. These examples work as shown at the StreamBase
Command Prompt on Windows and at the Bash prompt on Linux. See Using Quotes in Expressions for
further details on the quoting rules for StreamBase expressions.
1. You can evaluate any expression, whether or not it contains an expression language function. For
example:
sbd --eval "1e1 * (15 % -4)"
returns:
(double) 30.0
2. For Windows, you must surround with double quotes the entire expression you are testing. For Bash,
you can use either double or single quotes, but using double quotes is recommended. The next
example tests the cube root function:
sbd --eval "cbrt(27)"
which returns:
(double) 3.0
3. If you need to quote strings in your expression, you can either escape the extra double quotes with a
backslash or use single quotes inside the surrounding double quotes. For example, the following
commands are interpreted the same:
sbd --eval "list('alpha', 'beta', 'gamma')"
sbd --eval "list(\"alpha\", \"beta\", \"gamma\")"
Both commands return:
(list(string)) [alpha, beta, gamma]
Note
See Using Quotes in Expressions for further details on using quotes in expressions.
4. For another example of quote escaping, consider the following format_time() function. Both of these
versions work on both Windows and Linux:
sbd --eval "format_time(now(), 'EEEE, MMM d, yyyy HH:mm zzzz')"
Note
29
StreamBase References
sbd --eval "format_time(now(), \"EEEE, MMM d, yyyy HH:mm zzzz\")"
Both versions return the current time, formatted like this example:
(string) Tuesday, Feb 24, 2009 17:17 GMT-05:00
5. You can use sbd --eval to generate the correct CSV tuple format to use as input for sbc enqueue. For
example, when defining a complex tuple that contains nested tuples, use syntax like the following for
sbd --eval. (This command is a single unbroken line, shown on two lines for publication clarity):
sbd --eval "tuple(3.14159 as Math, tuple('IBM' as Stock,
tuple(1 as X, 2 as Y, 3 as Z) as Inner) as Outer)"
This returns:
((double, (string, (int, int, int)))) 3.14159,"IBM,""1,2,3"""
Now use the returned value to enter this tuple for sbc enqueue: 3.14159,"IBM,""1,2,3"""
6. With typing patience and some trial and error, you can test any expression with sbd --eval, however
complex. The following example tests the example shown in this Guide for the zip() function. First,
build the example tuple with the tuple() function. (This command is a single unbroken line, shown on
two lines for publication clarity):
sbd --eval "tuple( list(102.51, 96.82, 36.33) as prices,
list('AAPL', 'IBM', 'HPQ') as symbols )"
This returns:
((list(double), list(string))) "[102.51,96.82,36.33]","[AAPL,IBM,HPQ]"
Once you have the tuple() function returning a valid value, surround it with the zip() function:
sbd --eval "zip(tuple( list(102.51, 96.82, 36.33) as prices,
list('AAPL', 'IBM', 'HPQ') as symbols ) )"
This returns:
(list((double, string))) [102.51,AAPL, 96.82,IBM, 36.33,HPQ]
Back to Top ^
Using Quotes in Expressions
Expressions often need quotes around string values to designate those values as strings. The StreamBase
expression language is agnostic about whether to use double or single quotes in expressions. For example,
StreamBase interprets the following expressions identically when used in an expression in an operator or
adapter in StreamBase Studio or in a StreamSQL statement:
strftime("Traded on %b %d, %Y at %H:%M", now())
strftime('Traded on %b %d, %Y at %H:%M', now())
The only rule is that you must escape any instance of the same quote mark if you need to use it again inside a
pair of quote marks. You can escape a quote mark with a preceding backslash, or you can surround it with the
opposite quote mark. For example, StreamBase interprets the following lines identically in Studio or in
Note
30
StreamBase References
StreamSQL:
strftime('Traded at Miller\'s Crossing on %b %d, %Y at %H:%M', now())
strftime("Traded at Miller's Crossing on %b %d, %Y at %H:%M", now())
Shell Quote Interpretation When Using sbd --eval
The simple rules for using quote marks in StreamBase expressions in Studio are complicated by the shell's
quoting rules when testing expressions at the command prompt with sbd --eval.
On Windows, when using the StreamBase Command Prompt, you must surround the entire expression with
double quotes when using sbd --eval. This is a requirement of the cmd.exe shell, not StreamBase. You can
still use either backslash escaping or single quotes inside the surrounding double quotes. For example,
StreamBase resolves the following example commands identically at the StreamBase Command Prompt:
Works on Windows:
sbd --eval "strftime(\"Traded on %b %d, %Y at %H:%M\", now())"
sbd --eval "strftime('Traded on %b %d, %Y at %H:%M', now())"
The Bash shell is more forgiving, both under Linux and under Cygwin on Windows. Bash accepts either
double or single quotes surrounding the argument to sbd --eval. For example, StreamBase resolves the
following commands identically at the Bash prompt:
Works on Bash under Linux or Cygwin:
sbd --eval "strftime(\"Traded on %b %d, %Y at %H:%M\", now())"
sbd --eval "strftime('Traded on %b %d, %Y at %H:%M', now())"
sbd --eval 'strftime("Traded on %b %d, %Y at %H:%M", now())'
However, Bash does not allow the following version:
Does NOT work on Bash:
sbd --eval 'strftime(\'Traded on %b %d, %Y at %H:%M\', now())'
You may have to experiment with different quoting styles and quote escaping styles to get a complex
command to run with sbd --eval.
Back to Top ^
Data Types
Expressions use the StreamBase static data types:
blob
long
bool
string
double timestamp
int
tuple
list
These data types are described in detail in timestamp Data Type.
Back to Top ^
Using Quotes in Expressions
31
StreamBase References
Casting
To recast data types, use one of the StreamBase type conversion functions. For example, to cast a value to a
double in an expression, use the double() function. To cast a value to a string, use the string()
function, and so on. Casting may not be necessary if type coercion is supported for the data types, as described
in the next section.
Back to Top ^
Data Type Coercion and Conversion
Data type coercion is the implicit conversion of a value from one data type to another. For example, the +
(concatenation) string operator performs coercion from numeric and boolean values to strings, as in:
"This is " + (2 > 1) => (string) â
"1" + 2 + 3 => (string) "123"
This is trueâ
Evaluation proceeds from left to right, so that order matters:
1 + 2 + "3" => (string) "33"
Arithmetic operators coerce values when evaluating expressions with mixed numeric data types, as in:
1 + 2L + 3.0 => (double) 6.0
StreamBase math functions that take arguments and return doubles accept int, long or double input arguments.
For example, the sqrt() function accepts one int, long, or double input and returns a double result (or NaN).
The following are the supported data type coercions and conversions:
Input data type
Converts to
int
long (concatenates to string)
int
double (concatenates to string)
long
double (concatenates to string)
list(int)
list(long)
list(int)
list(double)
list(long)
list(double)
list(tuple) merging with different list(tuple) list(tuple), if a valid supertype of the two tuples can be found
sub-tuple field with unmatched schema
sub-tuple field with unioned schema
string (numerals only)
int, long, double (via int(), long(), double())
The following rules apply to data type coercions:
• For long-to-double coercion where the precision of the long cannot be preserved in the double, Java
rounding rules apply.
• When entering data to a stream whose schema contains a field of type tuple, StreamBase attempts to
coerce the data into the sub-tuple fields using the same rules as for a loose union in the Union
operator.
Casting
32
StreamBase References
• Coercion rules do not apply to output streams with declared, explicit schemas.
Back to Top ^
Case Sensitivity
Expressions are case sensitive. Function names are usually all lowercase, with a few exceptions. If you add
custom functions, follow the lowercase convention.
Back to Top ^
Identifier Naming Rules
StreamBase identifier naming rules apply to the name you assign to any StreamBase component, including
schemas, fields, operators, tables, modules, containers, and data source names. The rules are:
• Use only alphabetic characters, numbers, and underscores.
• The first character must be alphabetic or an underscore.
• Do not use hyphens or other special characters.
Note
StreamBase may create internal identifiers that include colons, but you cannot use colons in your identifiers.
For clarity in your application modules and to make debugging easier, StreamBase Systems recommends
following the rules below when choosing names for your StreamBase components. In some cases, these rules
are enforced by typechecking in StreamBase Studio.
• Do not use the name of a StreamBase data type, EventFlow reserved word, or StreamSQL reserved
word to name your stream fields or other components.
• Do not name a stream field the same as any dynamic variable or constant defined in the same module.
StreamBase resolves unqualified names first against the names of dynamic variables and constants,
and then against the names of fields in currently available streams. See Qualify Field Names to Avoid
Name Conflicts for more information.
• Do not name a stream field the same as any StreamBase expression language function, or the same as
any custom function you have configured for use in the same application. The link in this sentence
provides a list of the expression language function names.
StreamBase supports a syntax for escaping identifier names that contain reserved characters. If you enter a
name that does not follow the above rules, StreamBase automatically stores the name with escaped identifier
syntax. StreamBase Studio shows a warning when it needs to change a name you entered to use the alternate
syntax.
The escaped identifier syntax is #"name", a pound or hash symbol, with the string in double quotes. Escaped
identifiers work throughout StreamBase for the names of all components. You can use this syntax to name a
field the same as a StreamBase reserved word, such as #"AS".
Data Type Coercion and Conversion
33
StreamBase References
Identifier names can include Unicode characters as long as Unicode support is enabled for both Studio and
Server, as described in Unicode Support.
Back to Top ^
Reserved Words
When you name fields, do not use the following words, which are reserved for use in the expression language:
and as
between
else false if
or not null
then true
In EventFlow applications, StreamBase Studio does not prevent you from naming a field with a reserved word
in an input stream's Properties view. However, a schema that contains a reserved word causes one or more
typecheck errors in downstream components. The error message in the Typecheck view identifies the
offending field's name. To correct the typecheck error, rename the field in the input stream's Properties view.
In StreamSQL applications, Studio prevents you from using a reserved word as a field name when defining
schemas, or as a field in an index specification, order-by specification, or gather key.
Although the names of StreamBase data types are not reserved words, StreamBase Systems recommends that
you do not use data type names as field names, for clarity when developing and debugging your applications.
The data type names are listed in Data Types.
The StreamSQL language has an additional list of reserved words, as shown in StreamSQL Reserved Words.
Back to Top ^
Qualifying Field Names
If a name conflict occurs when referencing a field name used in an expression in an operator, you can qualify
the name to clarify the inbound stream you mean.
For example, in the Properties view for a Gather operator, you can qualify the fields as
input[port-number].field-name.
Example: input1.is_alarm, input2.is_alarm, input3.is_alarm.
In the Properties view for a Join operator, you can qualify the fields in the two input streams as
input1.field-name and input2.field-name. The input1.field-name refers to a field in the
stream arriving at the top port (#1). The input2.field-name refers to a field in the stream arriving at the
bottom port (#2).
Examples:
input1.SKU
Note
34
StreamBase References
input2.SKU
In the Properties view for a Query operator, you can qualify the fields in the two input streams as
input.field-name and old.field-name. The input.field-name refers to the current input
tuple, while old.field-name refers to the field's prior value.
Examples:
input.Symbol
old.Symbol
Important
In any expression anywhere in StreamBase, unqualified names are resolved first against the names of any
dynamic variables and constants defined in the current module, and then against the names of fields in
currently available streams. This means that a dynamic variable or constant named foo can mask a field also
named foo, depending on the context.
One consequence of this rule: If you use the same name for a dynamic variable and for its updating expression
field, StreamBase Studio issues a typecheck warning. To distinguish a dynamic variable from the same-named
field in the updating stream, qualify the field name with input.fieldname, or just rename the field.
Back to Top ^
Arithmetic Operators
You can use +, â
, *, /, and %. The ^ expression is not supported.
The following example shows the arithmetic operators in use. (This expression is shown on two lines for
publication clarity.):
((((sector_in_fund_value_t + (shares_traded * price_at_trade)) * 100) /
fund_value_t) > 25)
This expression is designed to execute the 25% sector test, where one sector is not allowed to be more than
25% of the total fund value. is_alarm is set to true if the test fails.
Back to Top ^
Modulus Operator
The modulus operator (%) finds the remainder of a division operation. Division and modulus are always
related such that a/b*b+(a%b) == a, where a/b is an integer division. For example, 15%4 can be
resolved as follows: as:
15 / 4 * 4 + MOD == 15
3 * 4 + MOD = 15
12 + MOD = 15
MOD = 3
Qualifying Field Names
35
StreamBase References
This relationship is preserved with negative divisors. As a result, whenever the quotient is negative, the
modulus is negative. For example:
15 % 4 = 3
15 % -4 = 3
-15 % 4 = -3
-15% -4 = -3
Also note that if you divide a smaller number by a larger number, the modulus is always the smaller number.
For example:
4 % 15 = 4
This behavior may be different than modulus operators in some programming languages.
Tip
The easiest way to understand StreamBase modulus operations is to try out different expressions using the
sbd --eval command as described in Evaluating Expressions with sbd --eval.
Back to Top ^
Between-And Operator
Use the between-and operator in expressions using the following syntax:
test-expr between expr1 and expr2
where expr1 and expr2 resolve to instances of the same data type to which test-expr resolves. That is,
the data type of test-expr, expr1, and expr2 must be the same, or must be coercibly the same, using the
rules described in Data Type Coercion.
This construction returns Boolean true or false, and is thus ideally suited for use in an if-then-else
construction:
if test-value between boundary1 and boundary2 then expr-if-true else expr-if-false
For example, using the current value of fieldname in the incoming tuple:
if fieldname between 100 and 200 then true else false
The between-and operator can be negated with the ! or NOT operator:
if fieldname not between 100 and 200 then true else false
The between-and operator is inclusive, which means if test-value exactly matches either boundary1 or
boundary2, the operator returns true. Use this operator as a more readable version of the following
equivalent expression. Using between-and has the advantage of only specifying test-value once.
if (test-value >= boundary1 and test-value <= boundary2) then expr-if-true
else expr-if-false
Modulus Operator
36
StreamBase References
The between-and operator works with any StreamBase data type, including list and tuple, using the relational
comparison algorithms described for each operator on StreamBase Data Types.
IN Operator
Use the infix operator IN to test for list containment, returning Boolean true or false. For example, the
following expressions each return true:
2 in [1, 2, 3]
2 in list(1, 2, 3)
The IN operator is syntactic sugar for the contains() function.
Notice that IN is not among the reserved words for the expression language, and the string IN can still be used
as an identifier in other contexts. The IN operator only becomes an operator in the context of a list
containment expression as shown above, with the test value on its left and the queried list on its right. The
queried list can be expressed in simple bracket format, or can be any function or expression that resolves to a
list, including the list() and range() functions.
Unary Operators
Unary operators act on only one operand in an expression. â
!a or NOT a is valid for the bool type. +a is not supported.
a is valid for integer, double, and long types.
Back to Top ^
Relational Operators
You can use the following relational operators: <, <=, =, ==, >, >=, !=
The relational operator <> is not supported.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
Back to Top ^
Logical Operators
You can use the following logical operators: &&, AND, ||, OR, !, NOT.
Logical Operator
Meaning
&& or AND
Logical AND
|| or OR
Logical OR
! or NOT
NOT: negates its operand
Between-And Operator
37
StreamBase References
Note
The evaluation of expressions using && and || will short-circuit. This means that after StreamBase encounters
the first term that evaluates as false, no other terms in a statement using && are evaluated. Similarly,
evaluation of a statement using || stops after the first true term.
For related information on Boolean logic and nulls, see Using Nulls.
Back to Top ^
Precedence Order
The precedence order of mathematical operators in expressions, from highest to lowest, is as follows:
1. Unary operators: !, NOT, and â
The logical negation operator, ! or NOT, reverses the meaning of its operand.
The unary negation operator, â , produces the negative of its operand.
2. Multiplicative operators: * and / and %
Multiplication: *
Division: /
Modulus, the remainder from division: %
3. Additive operators: + and â
Addition: +
Subtraction: â
4. Relational operators: < and <= and > and >=
Less than: <
Less than or equal to: <=
Greater than: >
Greater than or equal to: >=
5. Equality operator: == or =
6. Not equal: != or NOT =
7. Logical AND: && or AND
8. Logical OR: || or OR
You can use parentheses in expressions to override the default precedence.
Back to Top ^
Note
38
StreamBase References
White Space
The StreamBase parser ignores any spaces, new lines, and tab characters in expressions.
Back to Top ^
Comments
You can add comments to your expressions using either C-style comments or StreamSQL-style comments:
• StreamSQL comments begin with two hyphens and extend to the end of the same line.
• C-style comments begin with slash-asterisk and end with asterisk-slash. You can insert C-style
comments anywhere in the expression, including the middle of a line, and they can extend over
multiple lines.
The following sample expression illustrates several uses of comments:
/* handle special APPL case */
if (input1.symbol=="APPL.N") then input2.symbol == "APPL"
/* handle special
IBM case */
else if (input1.symbol=="IBM.L") then input2.symbol == "IBM"
else input2.symbol == input1.symbol -- accept the rest as given
Back to Top ^
Specifying Literals in Expressions
This section describes how to specify literals in expressions, for each data type. (For information about the
data types themselves, see StreamBase Data Types.)
blob
Use the StreamBase blob() function, which converts a string to a blob.
Example: blob("abcde") creates a blob containing the bytes representing the string "abcde".
You can use tobson() to convert strings of text, other literals, or any StreamBase value to a BSON
blob. To convert a BSON blob containing a string back to a string literal, use the stringbson()
function.
bool
Use the literals true and false.
int
Enter a number that is in the range of the int data type.
White Space
39
StreamBase References
Examples: 0 and 31337 are both ints
double
Enter a number using a decimal point, or using scientific notation.
Examples: 10.0 and 1e1 are both doubles.
long
Enter a number that is in the range of the long data type, appending L to the number.
Examples: 100L and 3147483650L are both longs.
Note
If the L is omitted, StreamBase interprets your number as an int no matter how large the value is.
list
Enter comma-separated values, surrounded by square brackets.
Examples: [23, 46, 889] is a list of three ints.
["IBM", "AAPL", "ORCL"] is a list of three strings.
string
You can use single quotes ( 'string' ) or double quotes ( "string" ) around strings. Escape
characters are supported, as follows:
Character
\"
\'
\n
\t
\b
\r
\f
\\
\uXXXX
Examples:
Results in
Double quotation mark
Single quotation mark
Newline
Tab
Backspace
Carriage return
Form feed
Backslash
Unicode character with hex code point XXXX
String Literal
"He said, \"Hello.\""
'She said, \'Hello.\' '
"A\tB"
"A\nB"
"C:\\WINDOWS"
"Copyright \u00A9 2050"
timestamp
Results in
He said, "Hello."
She said, 'Hello.'
A<tab>B
A<newline>B
C:\WINDOWS
Copyright © 2050
Specifying Literals in Expressions
40
StreamBase References
You can use timestamp literals only in comparison expressions that use the operators ==, !=, <=, >=,
<, or >, when one side of the comparison is a timestamp and the other side is a string literal that can
be interpreted as a valid timestamp. Otherwise, you cannot enter timestamp literals directly in
expressions. See timestamp in the StreamBase Data Types documentation.
In cases other than the one just described, to use timestamps in expressions, convert a string in a
particular format to a timestamp using a function such as the StreamBase timestamp() function. The
string argument must be in the form of a time format pattern as defined in the
java.text.SimpleDateFormat class described in the Sun Java Platform SE reference
documentation. See timestamp() for examples.
Also see the format_time(), parse_time() and format() functions. The maximum precision for
timestamps is milliseconds.
tuple
In expressions, define a single tuple using this syntax:
tuple (value AS fieldname[,...]) [AS tuplename]
The tuple schema, delimited by parentheses, consists of one or more field specifications separated by
commas. Each field name resolves to an instance of a StreamBase data type (including another tuple).
Use the AS keyword to specify field names in the result. Omit the outermost AS tuplename in
EventFlow expressions, where the tuple field's name is specified in StreamBase Studio. The
outermost AS is required in StreamSQL.
To cast a set of values as a tuple that conforms to an existing named schema, use the tuple() function.
Back to Top ^
Null Literals
You can use nulls in the StreamBase expression language, one for each of the simple data types:
blob(null)
bool(null)
double(null)
int(null)
long(null)
string(null)
timestamp(null)
The data type of a null is never implicit. You must specify the data type of any null you are using in the
expression.
In general, when you apply any arithmetic operator or function with data-type(null) as one of the
arguments, the result is null. Three exceptions are the isnull() and notnull() functions, which test
whether an expression evaluates to null, and the coalesce() and coalesce_tuples() functions,
which select a non-null value from a set of potentially null arguments.
Note
41
StreamBase References
Expression Example
Result
3 + int(null)
A null int
int(null) + int(null)
A null int
int(null) + bool(null)
A typecheck error. You cannot add an int and a bool.
if bool(null) then 3 else 4 A null int
int(null) == int(null)
A null bool, because null is not equal to itself
int(null) != int(null)
A null bool, because null is not equal to itself
isnull(int(null))
A bool that evaluates to true
notnull(int(null))
A bool that evaluates to false
To specify a null list, use the nulllist() function. See Null Lists for a discussion of null lists compared to
empty lists.
To specify a null tuple that uses a named schema, specify the name of the schema with empty parentheses. For
example, for the schema named nyse_data, the expression nyse_data() creates a null tuple. See Null
Tuples for a discussion of null tuples compared to empty tuples.
For more detailed information, see Using Nulls.
Back to Top ^
Conditional Expressions
In an expression such as: if p then e1 else e2, p must be a valid boolean expression, and both e1
and e2 must be expressions that have the same type. If p is true, then e1 is evaluated and the result returned.
If p is false, e2 is evaluated and the result returned. In either case, the other sub-expression is not evaluated.
Note
In the StreamBase expression language, each if clause must have a pair of explicit then and else clauses.
Should you create compound if clauses, to avoid ambiguity, remember to specify the then and else
clauses for each if clause. For an example, see the next section.
Back to Top ^
Compound Conditional Expressions
You can use combinations of if-then and else-if-then statements to form compound conditional
expressions. For example:
if i==0 then "Buy" else if i==1 then "Sell" else if i==2 then "Hold" else
"None of the above"
Here is a second example, indented for clarity, where we nest an if then else in a then clause:
if p1
then
Null Literals
42
StreamBase References
if p2
then A
else B
else
if p3
then C
else D
Notice how each if clause contains a then clause and an else clause.
Back to Top ^
Concatenation in Expressions
You can enter an expression that performs concatenation. For a string variable, the concatenation expression
is
stringvar1 + stringvar2
For a numeric variable with a static string, the concatenation expression is
"staticstring" + numvar
For example: "foo" + a.
For two variables, the concatenation expression is
stringvar + numvar
For example: b+a.
Back to Top ^
Timestamp Expressions
When used with comparison operators ( == != > < <= >= ) you must compare time fields interval-to-interval,
or timestamp-to-timestamp. You cannot use the comparison operators to forma an interval-to-timestamp
comparison.
To express constant intervals, you can use the seconds() and minutes() functions. For example, if you
want to add 60 seconds to a timestamp, enter expressions such as:
t + seconds(60)
t + minutes(1)
For more on comparing timestamp expressions, see timestamp Data Type.
Back to Top ^
Compound Conditional Expressions
43
StreamBase References
Parameters in Expressions
You can declare global parameters in the StreamBase Server configuration file, usually named
sbd.sbconf, and can define module parameters in the Parameters tab of the EventFlow Editor. You can
reference either parameter type in StreamBase expressions. See Constants, Variables, and Parameters for more
on the difference between global and module parameters.
To reference a parameter in an expression, wrap the parameter name in braces and prefix the open brace with
a dollar sign: ${parameter}. If you are referencing a parameter that is defined as a string, use quotes
around the entire reference: "${parameter}"
StreamBase Server Configuration File XML Reference explains how to declare global parameters. For
example, consider a server configuration file that defines the following two global parameters:
<operator-parameters>
<operator-parameter name="MyInt" value="2"/>
<operator-parameter name="MyString" value="somestring"/>
</operator-parameters>
You could reference the first parameter (for example, in an output field) using an expression like 35 *
${myInt}. The expression would evaluate at run time to 70. The following StreamSQL statement
references the second parameter:
SELECT * FROM InputStream1 "${MyString}" AS source
Notice the quotation marks, which are needed so that the expression is resolved as a string.
Note
Expression parameters can be referenced in both EventFlow and StreamSQL applications. However, if you
convert an EventFlow application file to a StreamSQL file, any expression parameters in the EventFlow
module are resolved during the conversion, and the value of the parameter is copied to the StreamSQL file.
The parameter itself is not preserved.
Back to Top ^
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
Parameters in Expressions
44
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Expression Language Functions
StreamBase Expression Language Functions
This topic describes the syntax and use of each function in the StreamBase expression language. See
StreamBase Expression Language Features for information on using the expression language in general. See
StreamBase Data Types for usage information on StreamBase data types.
This page is organized into the following sections:
Alphabetical Index of StreamBase
Functions
Simple Functions: Math
Simple Functions Overview
Simple Functions: NaN
Simple Functions: BSON
Simple Functions: Runtime
Simple Functions: Errors
Simple Functions: Strings
Simple Functions: External Functions
Simple Functions: System
Simple Functions: Financial
Simple Functions: Internet
Simple Functions: Lists
Simple Functions: Timestamp
Overview
Timestamp Functions: Absolute
Timestamps
Timestamp Functions: Interval
Timestamps
Timestamp Functions:
Timestamp Fields
Simple Functions: Type
Conversions
Simple Functions: Utilities
Aggregate Functions
Overview
Aggregate Functions:
Aggregate to List
Aggregate Functions:
External Functions
Aggregate Functions:
Statistical Calculations
Aggregate Functions:
Windowing
Alphabetical Index of StreamBase Functions
The following table is a complete, alphabetized index into the functions provided in the StreamBase
expression language, with links to the description for each function.
Function Name and Link to Section
abs
acos
addbson
Category
Math
Math
BSON
StreamBase Expression Language Functions
Simple or Aggregate
Function
Simple function
Simple function
Simple function
45
StreamBase References
aggregatelist
alpha
andall (simple)
andall (aggregate)
append
asin
atan
atan2
avg (simple)
avg (aggregate)
beta
bitand
bitnot
bitor
bitxor
black_scholes
blob
bool
bsontojson
callcpp (simple)
callcpp (aggregate)
calljava (simple)
calljava (aggregate)
catchexception
cbrt
ceil
closeval
coalesce
coalesce_tuples
compound_interest
concat (simple)
concat (aggregate)
contains (list item)
contains (strings)
correlation_coefficient
correlation_coefficientp
cos
cosh
count
count_distinct
count_distinct_elements
covariance
Aggregate to List
Statistical calculations
Math
Statistical calculations
Lists
Math
Math
Math
Lists
Statistical calculations
Statistical calculations
Math
Math
Math
Math
Financial
Type conversions
Type conversions
BSON
External Functions (simple)
External Functions (aggregate)
External Functions (simple)
External Functions (aggregate)
Errors
Math
Math
Windowing
Utilities
Utilities
Financial
Lists
Aggregate to List
Lists
Strings
Statistical calculations
Statistical calculations
Math
Math
Statistical calculations
Statistical calculations
Lists
Statistical calculations
Alphabetical Index of StreamBase Functions
Aggregate function
Aggregate function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Aggregate function
Aggregate function
Simple function
Simple function
Aggregate function
Aggregate function
Simple function
Aggregate function
46
StreamBase References
covariancep
date
days
dotproduct
double
emptylist
endswith
epoch
error
eval
exp
exp_moving_avg
expm1
filternull
findbson
firstelement
firstn
firstnonnullval
firstval
floor
format
format_time
from_gmtime
from_localtime
frombson
getAllHostIPs
get_boolean_conf_param
get_conf_param
get_double_conf_param
get_int_conf_param
get_long_conf_param
get_conf_param
get_day_of_month
get_day_of_week
get_hour
get_millisecond
get_minute
get_month
get_second
get_year
getClientIP
getContainer
Statistical calculations
Timestamps
Timestamps
Lists
Type conversions
Lists
Strings
Timestamps
Errors
Utilities
Math
Statistical calculations
Math
Lists
BSON
Lists
Windowing
Windowing
Windowing
Math
Strings
Timestamps
Timestamps
Timestamps
BSON
Runtime
Runtime
Runtime
Runtime
Runtime
Runtime
Runtime
Timestamps
Timestamps
Timestamps
Timestamps
Timestamps
Timestamps
Timestamps
Timestamps
Runtime
Runtime
Alphabetical Index of StreamBase Functions
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Aggregate function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
47
StreamBase References
getHostName
getLeadershipStatus
getNodeName
getParallelRoot
getPath
getServerURI
hash
hours
indexof (for lists)
indexof (for strings)
inet_aton
inet_ntoa
insertelement
int
intercept
interval
isempty
isinterval
isnan
isnull
join
joinbson
jsontobson
lag
lastelement
lastindexof (for lists)
lastindexof (for strings)
lastn
lastnonnullval
lastval
length
lenbson
length (for lists)
length (for strings)
list
listbson
ln
log10
log1p
long
lower
lshift
Runtime
Runtime
Runtime
Runtime
Runtime
Runtime
Utilities
Timestamps
Lists
Strings
Internet
Internet
Lists
Type conversions
Statistical calculations
Timestamps
Strings
Timestamps
NaN (not a number)
Utilities
Lists
BSON
BSON
Windowing
Lists
Lists
Strings
Windowing
Windowing
Windowing
Utilities
BSON
Lists
Strings
Type conversions
BSON
Math
Math
Math
Type conversions
Strings
Math
Alphabetical Index of StreamBase Functions
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Aggregate function
Aggregate function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
48
StreamBase References
ltrim
max (simple)
max (aggregate)
maxn (aggregate)
maxdouble
maxelement
maxint
maxlong
median (simple)
median (aggregate)
milliseconds
min (simple)
min (aggregate)
minn (aggregate)
mindouble
minelement
minint
minlong
minutes
namebson
named schema constructor function
nanotime
new_tuple
new_tuple_subset
new_tuple_subset_loose
notnan
notnull
now
nullif
nulllist
openval
orall (simple)
orall (aggregate)
parsejson
parse_time
pow
prepend
product (simple)
product (aggregate)
putbson
random
random_tuple
Strings
Math
Statistical calculations
Statistical calculations
Math
Lists
Math
Math
Lists
Statistical calculations
Timestamps
Math
Statistical calculations
Statistical calculations
Math
Lists
Math
Math
Timestamps
BSON
Type conversions
System
Utilities
Utilities
Utilities
NaN (not a number)
Utilities
Timestamps
Utilities
Lists
Windowing
Math
Statistical calculations
Utilities
Timestamps
Math
Lists
Lists
Statistical calculations
BSON
Math
Utilities
Alphabetical Index of StreamBase Functions
Simple function
Simple function
Aggregate function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Aggregate function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Simple function
49
StreamBase References
range
regexmatch
regexmatch_ignorecase
regexreplace
regexsplit
removebson
removeelement
replace
replaceelement
reverse
round
rshift
rtrim
seconds
securerandom
set_day_of_month
set_day_of_week
set_hour
set_minute
set_month
set_second
set_year
sign
sin
sinh
sleep
slope
sort
split
splitbson
sqrt
startswith
stdev (simple)
stdev (aggregate)
stdevp (simple)
stdevp (aggregate)
strftime
string
stringbson
strlen
strpinterval
strptime
Lists
Strings
Strings
Strings
Strings
BSON
Lists
Strings
Lists
Lists
Math
Math
Strings
Timestamps
Math
Timestamps
Timestamps
Timestamps
Timestamps
Timestamps
Timestamps
Timestamps
Math
Math
Math
System
Statistical calculations
Lists
Strings
BSON
Math
Strings
Lists
Statistical calculations
Lists
Statistical calculations
Timestamps
Type conversions
BSON
Strings
Timestamps
Timestamps
Alphabetical Index of StreamBase Functions
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
50
StreamBase References
strresize
strresizetrunc
sublist
substr
sum (simple)
sum (aggregate)
systemenv
systemproperty
tan
tanh
throw
time
timezoneoffset
timestamp
tobson
today
today_utc
tojson
to_degrees
to_milliseconds
to_radians
to_seconds
trim
tuplebson
tuple
unique
unsignedrshift
unzip
upper
variance (simple)
variance (aggregate)
variancep (simple)
variancep (aggregate)
vwap
weeks
withmax
withmin
zip
Back to Top ^
Strings
Strings
Lists
Strings
Lists
Statistical calculations
System
System
Math
Math
Errors
Timestamps
Timestamps
Type conversions
BSON
Timestamps
Timestamps
Utilities
Math
Timestamps
Math
Timestamps
Strings
BSON
Type conversions
Lists
Math
Lists
Strings
Lists
Statistical calculations
Lists
Statistical calculations
Statistical calculations
Timestamps
Statistical calculations
Statistical calculations
Lists
Alphabetical Index of StreamBase Functions
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Simple function
Aggregate function
Simple function
Aggregate function
Aggregate function
Simple function
Aggregate function
Aggregate function
Simple function
51
StreamBase References
Simple Functions Overview
The majority of functions in the StreamBase expression language are simple functions, which operate on a
single tuple field at a time. You can use simple functions in expressions for any StreamBase operator (except
the Heartbeat, Metronome, and Union operators, which do not accept expressions).
The expression language also supports aggregate functions, which are described in Aggregate Functions
Overview.
Simple functions are organized into the following categories:
Simple Functions: BSON
Simple Functions: Errors
Simple Functions: External Functions
Simple Functions: Financial
Simple Functions: Internet
Simple Functions: Lists
Simple Functions: Math
Back to Top ^
Simple Functions: NaN
Simple Functions: Runtime
Simple Functions: Strings
Simple Functions: System
Simple Functions: Timestamp Overview
Simple Functions: Type Conversions
Simple Functions: Utilities
Simple Functions: BSON
This category includes the following functions:
addbson()
bsontojson() findbson()
frombson() joinbson()
jsontobson()
lenbson()
listbson()
namebson()
putbson()
removebson() splitbson()
stringbson() tobson()
tuplebson()
These functions create, manipulate and extract contents of BSON blobs. BSON blobs, as defined by
bsonspec.org, are maintained in a binary format in which zero or more values, arrays, and objects with fields
(key/value pairs) are stored as a single entity. A variety of implementations exist.
BSON is short for Binary JSON. BSON blobs serialize data in the manner of JSON, and like JSON, BSON
data may include nested objects. JSON, as defined on http://www.json.org is text consisting of
colon-separated name-value pairs (with field name quoted), and each pair separated by a comma. A
BSON-encoded blob is sometimes referred to as a document.
The following table indicates how StreamBase types correspond to BSON types.
StreamBase Type
int
long
double
bool
string
BSON Type
int32
int64
double
Boolean
UTF-8 string
Simple Functions Overview
52
StreamBase References
null
null
timestamp
timestamp*
blob
binary
list
array
tuple
object
*The StreamBase BSON Java implementation for timestamps differs from the official BSON specification.
They are both int64 but the StreamBase format is used internally rather than the bsonspec.org format.
addbson()
Function syntax:
blob addbson(blob bsonblob-array, T element)
Adds a new field at the end of a BSON array. Accepts a BSON blob that contains an array and an element to
be appended to it. element can be of any type compatible with the contents of the array
bsonblob-array. Returns a BSON object for the expanded array.
Back to Top ^
bsontojson()
Function syntax:
string bsontojson(blob bsonblob)
Converts BSON blob to JSON-formatted string. Accepts one BSON blob and returns its contents as a JSON
object of key-value pairs.
Back to Top ^
findbson()
Function syntax:
blob findbson(blob bsonblob, int index)
blob findbson(blob bsonblob, string fieldname)
Searches a BSON object for a specified array index or field name. Accepts a BSON blob assumed to contain
either a BSON array or a BSON object and an index into the array or a string that should match a field name.
Returns a blob containing the found field or throws an error if not found or index is out of bounds. index
is a zero-based index. fieldname is a string, interpreted as a field name.
Back to Top ^
Simple Functions: BSON
53
StreamBase References
frombson()
Function syntax:
T frombson(blob bsonblob, T type)
Converts a BSON blob to the requested StreamBase type. Accepts one BSON blob and returns its contents as
the requested StreamBase type. The second argument provides an example of the return type and is not
evaluated. If the type does not match, throws an error.
Back to Top ^
joinbson()
Function syntax:
blob joinbson(list(blob) L)
Concatenates a list of BSON fields into a BSON object. Accepts a list of BSON blobs containing fields and
concatenates them. If the list argument is empty, returns an empty blob. If the list is null, returns null. To test
for null blobs, use the isnull function. You can use splitbson to create a list of BSON fields.
Back to Top ^
jsontobson()
Function syntax:
blob jsontobson(string jsonstring)
Converts a JSON string to a BSON blob. Accepts one JSON string and returns its contents as a BSON blob.
The argument jsonstring is any JSON string. For example:
jsontobson('{"symbol":"IBM","price":75.91,"quantity":150,
"date":"2013-04-28 16:00:00.000-0400"}')
Back to Top ^
lenbson()
Function syntax:
int lenbson(blob bsonblob)
Returns the length of a BSON object or array.
If bsonblob contains an array, returns the number of elements in it.
If bsonblob is an object, returns the number of fields in it.
frombson()
54
StreamBase References
If bsonblob is any other scalar type, throws an error.
Back to Top ^
listbson()
Function syntax:
blob listbson(T1 value1, T2 value2, ... Tn valuen)
Accelerator for constructing a (possibly heterogeneous) BSON array, similar to a StreamBase list. Accepts
any number of arguments and returns a BSON array containing them. Values are individually interpreted by
tobson and can be of any type.
Back to Top ^
namebson()
Function syntax:
string namebson(blob bsonblob)
Returns the name of a BSON field
If bsonblob is a BSON field, returns the field name, otherwise returns an empty string.
Back to Top ^
putbson()
Function syntax:
blob putbson(blob bsonblob-object, string name, T value)
Adds a new field to a BSON object. Returns the blob bsonblob-object with added field name having
value value. If field name already exists, its current value is replaced with value.
Back to Top ^
removebson()
Function syntax:
blob removebson(blob bson-list,
int element-index1, ... int element-indexN)
blob removebson(blob bson-tuple,
int element-index1|string fieldname1, ...
int element-index2|string fieldnameN)
Removes fields or list elements from BSON blobs. The BSON blob can contain an array or an object. A blob
is returned with fields or elements that match the specified element-index or fieldname arguments removed.
lenbson()
55
StreamBase References
Fields can be removed from objects by index or field name.
The order of indexes and names in arguments does not matter. Any out-of-bounds indexes and non-matching
field names are ignored.
Back to Top ^
splitbson()
Function syntax:
list splitbson(blob bsonblob-containing-list)
list splitbson(blob bsonblob-containing-object)
Returns a list of BSON fields from a BSON object or a list of BSON values from a BSON array. Use
frombson to convert individual returned values to StreamBase types.
Back to Top ^
stringbson()
Function syntax:
string stringbson(blob bsonblob-string)
Converts a BSON blob to a string. The BSON blob must contain one string. Unlike the string function, no
type conversion is performed.
Back to Top ^
tobson()
Function syntax:
blob tobson(T arg)
Converts StreamBase values to a BSON blob. Each StreamBase int, long, double, string, timestamp, and blob
maps to a respective BSON type, nulls map to nulls, lists map to BSON arrays, and tuples map to BSON
objects.
Back to Top ^
tuplebson()
Function syntax:
blob tuplebson(AS-expr1, AS-expr2, ... AS-exprN)
Accelerator for constructing a BSON object from comma-separated AS expressions (comma-separated value
expressions, each field named with the AS keyword). The resulting blob contains an object having the
specified fields and values.
removebson()
56
StreamBase References
The following example creates a BSON object with three fields:
tuplebson("IBM" AS symbol, 87.3875 AS price, 47 AS quantity)
Back to Top ^
Simple Functions: Errors
This category includes the following functions:
catchexception()
error()
throw()
catchexception()
Function syntax:
T catchexception(T arg1 [, ... [, T argn]])
Attempts to evaluate all arguments in order, returning the first one that evaluates without an error, or null if all
arguments evaluate to an error. Accepts all data types, but all arguments must have the same type. The
returned value has the same data type, T, as the arguments.
For example, the following example attempts to parse str as an interval, but returns a null timestamp if
parsing fails:
catchexception(interval(str))
The following example attempts to divide a by b, but returns -1 if the division fails:
catchexception(a/b, -1)
Back to Top ^
error()
Function syntax:
bool error(string message)
Throws an error with message text message that can be caught using the StreamBase error streams
mechanism. In the default configuration, this produces an error message on the console, and the server
continues processing.
Because error() returns bool, it works well as a predicate expression in operators. For example, use
error("Error condition") as the last predicate expression for a Filter operator to produce an error
message when no earlier predicate expression was matched.
Back to Top ^
tuplebson()
57
StreamBase References
throw()
Function syntax:
T throw(string message)
Throws an error with message text message that can be caught using the error streams mechanism. In the
default configuration, this produces an error message on the console, and the server continues processing.
Because throw() returns an untyped null by default, it works well in if statements. For example: if
(test-expr) then (5) else throw("Failed the test")
For the purposes of typechecking, cast the return of this function with one of the casting functions. For
example, use bool(throw("Unmatched filter option")) as the last predicate expression of a
Filter operator to produce an error message when no earlier predicate expression was matched.
Back to Top ^
Simple Functions: External Functions
This category includes the following functions:
callcpp()
calljava()
callcpp()
Function syntax:
T callcpp(string class [, arg1 , ... [, argn]])
As an alternative to using callcpp(), you can define an alias for your custom functions. See Using
Function Aliases.
Use an alias or callcpp() to run a custom C++ function directly from a operator that uses an expression.
The return type, T, of callcpp() is the same as the return type of the called function. Custom C++
functions are functions you build with the C++ Client API. You can use the simple form of callcpp() in
any expression except aggregate expressions. (To use callcpp() in aggregate expressions, refer to the
aggregate callcpp().)
For callcpp() to locate the function being called, you must specify the location of the containing DLL or
.so file, and must register the function with a custom-function element in the StreamBase Server
configuration file. See C++ Function Overview for details.
To learn about coding custom C++ functions, refer to Creating Custom C++ Functions in the API Guide.
Back to Top ^
throw()
58
StreamBase References
calljava()
Function syntax:
T calljava(string class, string method [, arg1 , ..., argn])
As an alternative to using calljava, you can define an alias for your custom functions. See Using Function
Aliases.
Use an alias or calljava() to run a custom Java function directly from a StreamBase operator that uses an
expression. The return type, T, of calljava() is the same as the return type of the called function. Custom
Java functions are functions you build with the StreamBase Java Client library. You can use the simple form
of calljava() in any expression except aggregate expressions. (To use calljava() in aggregate
expressions, refer to the aggregate calljava().)
You can also use calljava() (or an alias) to run any public function in any class on StreamBase Server's
classpath, including standard library functions.
The calljava() function distinguishes simple from aggregate functions by the number of arguments. For
custom simple functions, you must specify both class and method names. For custom aggregate functions, you
specify only the class name.
To learn about coding custom Java functions, refer to Using the StreamBase Java Function Wizard in the API
Guide. For information on the classpath requirements for custom Java functions, see Java Function Overview.
Return Types and Argument Types
The function you write to be called with calljava() can have any number of arguments, including none.
Each calljava() argument arg1 through argn associates a StreamBase data type with one of the
following primitive or Java object types:
StreamBase Data Type
Java
Primitive
Java Object
blob
â
com.streambase.sb.ByteArrayView
bool
boolean
java.lang.Boolean
double
double
java.lang.Double
int
int
java.lang.Integer
long
long
java.lang.Long
list
â
java.util.List
string
byte[]
java.lang.String
timestamp
â
com.streambase.sb.Timestamp
tuple
â
com.streambase.sb.Tuple
In writing your Java function, use the Java primitive if the execution speed of your function is paramount.
However, if you pass a null for any argument that resolves in your function to a Java primitive, calljava()
returns an error and does not call your function. Only use Java primitives if your application otherwise insures
that null values cannot be passed to your function through calljava().
Use the Java object when your application might pass null to your function through calljava(), and when
calljava()
59
StreamBase References
no Java primitive is available.
Back to Top ^
Simple Functions: Financial
This category includes the following functions:
black_scholes()
compound_interest()
black_scholes()
Function syntax:
double black_scholes(string type, double underlying, double strike,
double dividendYield, double riskFreeInterestRate,
double Volatility, timestamp exerciseDate [, timestamp dealDate])
The black_scholes function calculates fair-value and risk statistics (delta, gamma, vega) for European
style options on securities with continuous dividend yields. This is known as the Black-Scholes Generalized
model. It also calculates implied volatility.
The black_scholes function takes eight input arguments; the first seven arguments are required, while the
eighth argument, dealDate, is optional.
The arguments are:
1. type: Required. Should be set to one of the following string values:
• Call (The price of an option.)
• Put (The price of an option.)
• DeltaCall (The sensitivity of the price of an option to changes in the price of the stock.)
• DeltaPut (The sensitivity of the price of an option to changes in the price of the stock.)
• ThetaCall (Theta measures how the price of an option changes with time.)
• ThetaPut (Theta measures how the price of an option changes with time.)
• Gamma (The sensitivity of a stock's delta to the stock price.)
• Vega (The rate of change of the value of an option with respect to the volatility of the stock's
price.)
• RhoCall (The sensitivity of the price of an option with respect to the risk-free interest rate.)
• RhoPut (The sensitivity of the price of an option with respect to the risk-free interest rate.)
• ImpliedVolatilityCall (Implied volatility of the underlying stock for a given price.)
• ImpliedVolatilityPut (Implied volatility of the underlying stock for a given price.)
2. underlying: Required. A double. The price of the underlying stock.
3. strike: Required. A double. The strike price of the stock on the exercise date.
4. dividendYield: Required. A double. For example, 0.03 for 3.0%.
5. riskFreeInterestRate: Required. A double. For example, 0.05 for 5.0%.
6. Volatility (or value): Required. A double. This input argument is overloaded. When computing
anything except the implied volatility for a given call or put price this argument is the volatility of the
stock. For example, 0.2 for 20%. When computing implied volatility this argument is the option price.
Return Types and Argument Types
60
StreamBase References
7. exerciseDate: Required. An absolute or interval timestamp. An absolute timestamp represents
the option exercise date, while an interval timestamp represents the number of days to exercise.
8. dealDate: Optional. A timestamp representing the option deal date. If not provided, the current date
is the default.
Back to Top ^
compound_interest()
Function syntax:
double compound_interest(double principalValue, double matureValue,
double numberOfPeriods [, double guess])
Returns the compound interest given the principal value, mature value, and number of periods. An optional
fourth argument, guess, can be used to set the initial compound interest used by the function. The
compound_interest function uses the Newton-Raphson algorithm to compute compound interest rate.
This algorithm performs the same calculations repetitively. Each iteration results in a compound interest that
is closer to the final result. The number of iterations required to get the results within an acceptable inaccuracy
(1.0e-4) depends on the number of periods and the initial compound interest used to start the calculation.
If the guess argument is not provided, the default initial value is 0.01 (1%). If the function returns a NaN
(not a number), you can provide the initial compound interest in this fourth argument. If the initial value is
closer to the actual rate of the computation, it can be sped up significantly.
Back to Top ^
Simple Functions: Internet
This category includes the following functions:
inet_aton()
inet_ntoa()
inet_aton()
Function syntax:
long inet_aton(string address)
Takes a string containing an IPv4 address in dotted-quad notation ("nnn.nnn.nnn.nnn") and returns a long
containing that address encoded in network byte order.
Back to Top ^
inet_ntoa()
Function syntax:
string inet_ntoa(int address)
string inet_ntoa(long address)
black_scholes()
61
StreamBase References
Takes an int or long containing an IPv4 address encoded in network byte order and returns a string containing
that address in dotted-quad notation ("nnn.nnn.nnn.nnn").
Back to Top ^
Simple Functions: Lists
A list is an ordered collection of values (called elements), each of which is of the same StreamBase data type,
called the list's element type. The element type can be any StreamBase data type, such as an int, a tuple, or
even a list (thus allowing for constructions such as a list of list of int).
Individual elements in a list can be accessed using their zero-based integer position (their index) in the list. In
any expression in an EventFlow or StreamSQL program, use brackets to address individual elements of a list.
Thus, for a list field named L, use L[0] to address the first element in the list, L[1] for the second element,
and L[length(L)-1] to address the last element.
In most list-related functions that take an index, you can also use a negative index to count backward from the
end of the list. Thus, for a list L, L[-1] is equivalent to L[length(L)-1].
The number of elements in a list is determined at application run-time. A null list is not the same as a list with
zero elements (an empty list), which is not null.
append()
dotproduct()
insertelement()
list()
prepend()
replaceelement()
stdev()
variance()
avg()
emptylist()
join()
maxelement()
product()
reverse()
stdevp()
variancep()
concat()
filternull()
lastelement()
median()
range()
sort()
sum()
zip()
contains()
firstelement()
lastindexof() (for lists)
minelement()
regexsplit()
split()
unique()
.
count_distinct_elements()
indexof() (for lists)
length() (for lists)
nulllist()
removeelement()
sublist()
unzip()
append()
Function syntax:
list(T) append(list(T) L, T e1, T e2, ..., T en)
Returns its argument list, L, with elements e1 through en added to the end of the list in the order specified.
The data types of the appended elements e and the element type of list L must be the same, except that
element types int and long can be coerced to long and double following the rules in Data Type Coercion and
Conversion. The element type of the returned list is the same as the element type of the argument list and of
the appended elements.
The function takes any number of element arguments, including zero. That is, append(L) returns list L
unchanged. If any list element is null, a null element is appended to the list in the position specified.
Back to Top ^
inet_ntoa()
62
StreamBase References
avg()
Function syntax:
double
int
long
timestamp
avg(list(double) L)
avg(list(int) L)
avg(list(long) L)
avg(list(timestamp) L)
Given a list, L, of doubles, ints, longs, or timestamps, returns the average of all members of the list. For a
returned average of timestamp values to make sense, the list should contain all interval timestamps or all
absolute timestamps, but not both. The data type of the returned value is the same as the element type of the
argument list.
See also the aggregate version of avg().
Back to Top ^
concat()
Function syntax:
list(T) concat(list(T) L1, list(T) L2 [, ..., list(T) Ln])
Returns a list produced by concatenating the elements of its argument lists in the order specified. Takes two or
more list arguments, which must have the same element type. The element type, T, of the returned list is the
same as the element types of the argument lists.
See also the aggregate version of concat().
Back to Top ^
contains()
Function syntax:
bool contains(list(T) L, T item)
Takes two arguments: a list with element type T, and a value, item, of the same type. Returns true if item
is a member of the specified list, or false if not.
If the entire list is null, returns null. If a member of the list is null, and item is null, returns true. If no
member of the list is null, and item is null, returns false.
Back to Top ^
count_distinct_elements()
Function syntax:
int count_distinct_elements(list(T) L)
avg()
63
StreamBase References
Returns the number of unique elements in the argument list, L, with any element type, T.
For example,
count_distinct_elements(list(1, 2, 3, 3, 4, 4, 5, 6, 6, 7))
returns 7.
See also the related function, unique() and the aggregate function count_distinct().
Back to Top ^
dotproduct()
Function syntax:
T dotproduct(list(T) L1, list(T) L2, ...)
Returns the sum of the element-wise product of its argument lists, whose element types must be int, double, or
long. Accepts any number of lists, but is typically used with two list arguments. The data type of the returned
value is the same as the element type of the argument lists. If the element type of the argument lists do not
match, they are promoted using the rules in Data Type Coercion and Conversion.
This function produces the dot product, also known as the scalar product, of two or more numeric lists. The
function multiplies the elements of each list in element order, L1.first times L2.first, then L1.second times
L2.second, and so on. The resulting list of element products is summed and returned. If an argument list is
null, the result is null. If any element in any argument list is null, the result is null. If an argument list is
shorter than another argument list, the extra positions are filled in with 1 (or 1.0 or 1L), which preserves the
extra position elements of the longer list unchanged.
Back to Top ^
emptylist()
Function syntax:
list(T) emptylist(T x)
Returns an empty list with the same element type as the argument. The argument x's value is ignored, and
only its type is considered. This function is typically used like these examples:
emptylist(int())
emptylist(string())
You can also use an argument with a value, or an expression that resolves to a value, like the following
examples. Only the type of the argument is considered:
emptylist(17)
emptylist("IBM")
count_distinct_elements()
64
StreamBase References
Back to Top ^
filternull()
Function syntax:
list(T) filternull(list(T) L)
Returns a list composed of the elements of the argument list, L, with any null elements removed. The element
type, T, of the returned list is the same as the element type of the argument list.
Back to Top ^
firstelement()
Function syntax:
T firstelement(list(T) L)
Returns the first element of argument list L. The data type, T, of the returned value is the same as the element
type of the argument list.
The usage firstelement(L) is the equivalent of L[0].
Back to Top ^
indexof()
Function syntax:
int indexof(list(T) L, T e [, int start])
Returns the index of the first element of the list L whose value is e, starting at index start. The argument
list can have any element type, T. The element e must have the same element type as the argument list. For
list arguments, if e is not found, the function returns a value of null.
If the search is successful, the value returned is always greater than or equal to start. If start is
unspecified, it is taken to be 0, which designates the first character of the string or the first element of the list.
See also the indexof() function that operates on strings.
insertelement()
Function syntax:
list(T) insertelement(list(T) L, int index, T e)
Returns a list composed of the elements of the argument list, L, with element e inserted before index position
index in the argument list. The element type, T, of the returned list is the same as the element type of the
emptylist()
65
StreamBase References
argument list and of the inserted element, e.
The usage insertelement(L, length(L), e) is the equivalent of append(). The usage
insertelement(L, 0, e) is the equivalent of prepend().
Back to Top ^
join()
Function syntax:
string join(string separator, list(T) L)
Returns a string composed of the elements of list L, having any element type, with the separator character
between each element. If the list argument is empty, join() returns an empty string. If the list is null, join()
returns null. If the separator string is null, join() returns null.
Back to Top ^
lastelement()
Function syntax:
T lastelement(list(T) L)
Returns the last element of argument list L. The data type of the returned value is the same as the element type
of the argument list.
The usage lastelement(L) is the equivalent of L[-1].
Back to Top ^
lastindexof()
Function syntax:
int lastindexof(list(T) L, T e [, int lastStart])
Returns the index of the last element of the list L whose value is e, for which the index is less than or equal to
lastStart. The argument list can have any element type, T. The element e must have the same element
type as the argument list. For list arguments, if e is not found, the function returns a value of null.
If the search is successful, the value returned is always less than or equal to lastStart. If lastStart is
unspecified, it is taken to be the index of the last grapheme of the string or the last element of the list.
See also the lastindexof() function that operates on strings.
insertelement()
66
StreamBase References
length()
Function syntax:
int length(list L)
Returns the number of elements in a list, including any null elements. If the argument is a null list, the
returned value is null.
See also the length() functions that operate on lists and blobs.
list()
Returns a list containing its arguments as elements. See list() in the Simple Functions: Type Conversions
section.
maxelement()
Function syntax:
T maxelement(list(T) L)
This function returns the maximum non-null element value using the greater-than relational operator across all
elements in the argument list, L. The data type of the returned value is the same as the element type of the
argument list.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
See also the simple version of max(), the aggregate version of max(), and the aggregate maxn() function. Use
the simple function max(list, , list) to determine the larger of two or more lists. In an aggregate
context, max(list) returns the maximum list in the aggregate window. By contrast, use maxelement()
to compare the element values of a single list.
Back to Top ^
median()
Function syntax:
double median(list(double) L)
double median(list(int) L)
double median(list(long) L)
Given a list, L, of doubles, ints, or longs, returns a double, the median of the elements of L. If the list has an
even number of elements, returns the average of the middle two.
See also the aggregate version of median().
Back to Top ^
length()
67
StreamBase References
minelement()
Function syntax:
T minelement(list(T) L)
This function returns the minimum non-null value using the less-than relational operator across all elements in
the argument list, L. The data type of the returned value is the same as the element type of the argument list.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
See also the simple version of min(), the aggregate version of min(), and the aggregate minn() function. Use
the simple function min(list, , list) to determine the smaller of two lists. In an aggregate context,
min(list) returns the minimum list in the aggregate window. By contrast, use minelement() to
compare the element values of a single list.
Back to Top ^
nulllist()
Function syntax:
list(T) nulllist(T x)
Notice that the name of the function has three lowercase letter L's. Returns a null list with the same element
type as the argument. The argument x's value is ignored, and only its type is considered. This function is
typically used like these examples:
nulllist(double())
nulllist(timestamp())
You can also use an argument with a value, or an expression that resolves to a value, like the following
examples. Only the type of the argument is considered:
nulllist(17)
nulllist("IBM")
Back to Top ^
prepend()
Function syntax:
list(T) prepend(list(T) L, T e)
Returns a list containing element e at the start, then all of list L. The data type of element e and the element
type of list L must be the same, except that argument types int and long can be coerced to long and double
minelement()
68
StreamBase References
following the rules in Data Type Coercion and Conversion. The element type of the returned list is the same
as the element type of the argument list and of the prepended element, e.
Back to Top ^
product()
Function syntax:
double product(list(double) L)
int
product(list(int) L)
long
product(list(long) L)
Given a list, L, of doubles, ints, or longs, returns the product of each member of the list. The data type of the
returned value is the same as the element type of the argument list.
See also the aggregate version of product().
Back to Top ^
range()
Function syntax:
list(int) range(int start, int end [, int step])
Returns a list of ints from value start up to (or down to) but not including value end. That is, the range
includes the first item in the list and excludes the last item. Thus, range(1, 10) returns a list with nine
elements, not ten:
list(int) [1, 2, 3, 4, 5, 6, 7, 8, 9]
The default value for step is 1. step cannot be 0, but you can specify a step value greater than 1 to
produce a list with skipped elements. For example, a step of 2 returns every other number:
range(0, 8, 2)
returns
list(int) [0, 2, 4, 6]
If you specify a negative value for step, the list generates in reverse. For example:
range(3, 0, -1)
returns
list(int) [3, 2, 1]
while
prepend()
69
StreamBase References
range(6, 1, -2)
returns
list(int) [6, 4, 2]
When step is negative and end is greater than start, the result is an empty list. Likewise, an empty list
also results when start is greater than end and step is positive.
Back to Top ^
regexsplit()
Parses a string into tokens delimited by a character matching a regular expression, and returns a list of strings
with the tokens as elements. See regexsplit() in the Simple Functions: Strings section.
removeelement()
Function syntax:
list(T) removeelement(list(T) L, int index)
Returns a list composed of the elements of the argument list, L, with the element at index position index
removed. The element type, T, of the returned list is the same as the element type of the argument list.
Back to Top ^
replaceelement()
Function syntax:
list(T) replaceelement(list(T) L, int index, T e)
Returns a list composed of the elements of the argument list, L, with the element at index position index
replaced by element e. The element type of the returned list is the same as the element type of the argument
list.
Back to Top ^
reverse()
Function syntax:
list(T) reverse(list(T) L)
Returns its argument list, L, in reverse order. The element type, T, of the returned list is the same as the
element type of the argument list.
Back to Top ^
range()
70
StreamBase References
sort()
Function syntax:
list(T) sort(list(T) L [, bool ascending])
Returns its argument list, L, sorted. Sorting occurs in ascending order if the optional ascending argument is
true or omitted, or in descending order if ascending is false. The element type, T, of the returned list is the
same as the element type of the argument list.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types. Null values sort as the lowest possible values for the element type
of the list. For doubles, NaN sorts as the highest possible value, which yields the following: Null <
â Infinity < 0 < +Infinity < NaN.
Back to Top ^
split()
Parses a string into tokens delimited by a specified character and returns a list of strings with the tokens as
elements. See split() in the Simple Functions: Strings section.
stdev()
Function syntax:
double
double
double
timestamp
stdev(list(double) L)
stdev(list(int) L)
stdev(list(long) L)
stdev(list(timestamp) L)
Given a list, L, of doubles, ints, longs, or timestamps, returns the standard deviation for all members of the
list. If the argument list is a list of doubles, ints, or longs, returns a double. If the argument list is a list of
timestamps, returns an interval timestamp. For timestamp values, the list should contain all interval
timestamps or all absolute timestamps, but not both.
See also the aggregate version of stdev().
Back to Top ^
stdevp()
Function syntax:
double
double
double
timestamp
stdevp(list(double) L)
stdevp(list(int) L)
stdevp(list(long) L)
stdevp(list(timestamp) L)
Given a list, L, of doubles, ints, longs, or timestamps, returns the standard deviation for all members of the
list. If the argument list is a list of doubles, ints, or longs, returns a double. If the argument list is a list of
sort()
71
StreamBase References
timestamps, returns an interval timestamp. For timestamp values, the list should contain all interval
timestamps or all absolute timestamps, but not both.
With stdevp() the data provided is the entire population, while with stdev(), the data provided is treated
as a random sample. The stdevp() function is calculated using the biased (or n) method. The stdev()
function is calculated using the unbiased (or n-1) method.
See also the aggregate version of stdevp().
Back to Top ^
sublist()
Function syntax:
list(T) sublist(list(T) L, int start [, int end [, int step]])
Returns a list composed of a section of the argument list, L, starting with index start, which is included in
the result list. If end is specified, it is not included in the result list. The default value for step is 1. You can
supply an alternate step value to skip elements in the argument list. For example, a step of 2 returns every
other value in the list. You must specify an end value in order to specify a step value. The element type, T,
of the returned list is the same as the element type of the argument list.
In contrast with the range() function, step cannot be negative.
Back to Top ^
sum()
Function syntax:
double
int
long
timestamp
sum(list(double) L)
sum(list(int) L)
sum(list(long) L)
sum(list(timestamp) L)
Given a list, L, of doubles, ints, longs, or timestamps, returns the sum of all members of the list. The element
type of the returned list is the same as the element type of the argument list.
When the list element type is timestamp, summing elements of the list follows the rules for adding timestamps
as shown in the table in timestamp Data Type. That is, you cannot sum a list of two or more absolute
timestamps. However, you can sum a list composed of all interval timestamps, or one composed of exactly
one absolute timestamp plus one or more interval timestamps.
See also the aggregate version of sum().
Back to Top ^
stdevp()
72
StreamBase References
unique()
Function syntax:
list(T) unique(list(T) L)
Returns a list composed of the unique elements in the argument list, L. The returned list is not reordered in
any sequence: the function only removes duplicates of existing elements, and returns the list in the order of
the argument list. The element type, T, of the returned list is the same as the element type of the argument list.
For example:
unique(list(1, 2, 3, 3, 4, 4, 5, 6, 6, 7))
returns:
list(int) [1, 2, 3, 4, 5, 6, 7]
See also the related function, count_distinct_elements().
Back to Top ^
unzip()
Function syntax:
tuple unzip(list(tuple) listOfTuples)
Takes a list of tuples and returns a tuple of lists.
An example will clarify the function. Let's say your application extracts a list of symbol and price tuples from
a stream. One list might contain the following:
[ {prices: 102.51, symbols: AAPL},
{prices: 96.52, symbols: IBM},
{prices: 36.33, symbols: HPQ} ]
You can run this list through unzip(), using an expression like the following:
unzip(list(tuple(102.51 as prices,'AAPL' as symbols),
tuple(96.82 as prices,'IBM' as symbols),
tuple(36.33 as prices,'HPQ' as symbols)))
The returned value is a single tuple whose fields are lists, as follows:
((prices list(double), symbols list(string))) "[102.51,96.82,36.33]","[AAPL,IBM,HPQ]"
Back to Top ^
unique()
73
StreamBase References
variance()
Function syntax:
double variance(list(double) L)
double variance(list(int) L)
double variance(list(long) L)
Given a list, L, of doubles, ints, or longs, returns a double, the variance for all members of the list. Variance
is a measure of the dispersion of a set of data points around their mean value.
See the aggregate version of variance() for more on variance.
Back to Top ^
variancep()
Function syntax:
double variancep(list(double) L)
double variancep(list(int) L)
double variancep(list(long) L)
Given a list, L, of doubles, ints, or longs, returns a double, the variance for all members of the list. Variance
is a measure of the dispersion of a set of data points around their mean value.
The variancep() function is similar to the variance() function: with variancep() the data
provided is the entire population, while with variance(), the data provided is treated as a random sample.
The variancep() function is calculated using the biased (or n) method. The variance() function is
calculated using the unbiased (or n-1) method.
See also the aggregate version of variancep().
Back to Top ^
zip()
Function syntax:
list(tuple) zip(tuple(list(T1), ..., list(Tn)) tupleOfLists)
In the spirit of the zip function in Python, zip() takes a tuple of lists, collates it, and returns it as a list of
tuples, where the nth tuple contains the nth element from each of the argument lists. The element types of the
lists in the argument tuple can be of any type, and do not need to be the same.
An example will clarify the function. Let's say you have a stream whose schema accepts lists of securities
price data: { prices list(double), symbols list(string) }. One tuple might contain the
following:
{
prices: [102.51, 96.82, 36.33],
symbols: [AAPL, IBM, HPQ]
variance()
74
StreamBase References
}
You can run this tuple through zip(), using an expression like the following:
zip(tuple(list(102.51, 96.82, 36.33) as prices, list('AAPL', 'IBM', 'HPQ') as sy
The returned value is a list of tuples:
(list((prices double, symbols string))) [102.51,AAPL, 96.82,IBM, 36.33,HPQ]
Back to Top ^
Simple Functions: Math
This category includes the following functions:
abs()
acos()
andall()
asin()
atan()
atan2() cbrt()
ceil()
cos()
cosh()
exp()
expm1() floor()
ln()
log10()
log1p() max()
min()
orall()
pow() random() round()
securerandom()
sign() sin()
sinh()
sqrt()
tan()
tanh()
to_degrees() to_radians()
The following functions provide bitwise operations:
bitand() bitor() lshift() unsignedrshift()
bitnot() bitxor() rshift()
The following functions return the maximum and minimum values for numeric data types:
maxint() maxlong() maxdouble()
minint() minlong() mindouble()
abs()
Function syntax:
int
abs(int e)
double abs(double e)
long
abs(long e)
Returns the absolute value of an int, double, or long expression e. The return type is the same as the
expression's type.
Back to Top ^
zip()
75
StreamBase References
acos()
Function syntax:
double acos(int x)
double acos(double x)
double acos(long x)
Returns in radians the arc cosine of x, which is the value whose cosine is x. Undefined outside of the range
â 1 to 1.
Back to Top ^
andall()
Function syntax:
bool andall(bool b1, bool b2, ...)
Takes two or more values of type boolean, or expressions that resolve to type boolean, and returns the results
of a logical AND operation on all arguments. For example, andall(true, true, false, true,
false) returns false. Use andall() as a truth detector function.
Null arguments have special handling. A null argument does not change the result of the evaluation if a
false value is among the arguments: andall(null, true, false, null, true) still returns
false. However, if one or more arguments is null while all other arguments are true, the function returns
null: andall(null, true, true, null, true) returns null.
The andall() function follows the logic expressed in this statement:
if any argument is false, return false
else if any argument is null, return null
else return true
See also the orall() simple function and the aggregate versions of andall() and orall().
Back to Top ^
asin()
Function syntax:
double asin(int x)
double asin(double x)
double asin(long x)
Returns in radians the arc sine of x, which is the value whose sine is x. Undefined outside of the range â
to 1.
1
Back to Top ^
acos()
76
StreamBase References
atan()
Function syntax:
double atan(int x)
double atan(double x)
double atan(long x)
Returns in radians the arc tangent of x, which is the value whose tangent is x.
Back to Top ^
atan2()
Function syntax:
double atan2(int x, int y)
double atan2(double x, double y)
double atan2(long x, long y)
Returns in radians the arc tangent of two numeric variables, x and y, either of which can be int, long, or
double. This is similar to calculating the arc tangent of (y/x), except that the signs of both arguments are used
to determine the quadrant of the result tangent is x.
Back to Top ^
bitand()
int bitand(int x, int y)
long bitand(long x, long y)
Returns the result of a bitwise AND operation on values x and y. Compares each bit in x to the corresponding
bit in y. If both bits are 1, sets the corresponding result bit to 1. Thus, bitand(3,6) returns 2. (0011 AND
0110 returns 0010)
Back to Top ^
bitnot()
int bitnot(int x)
long bitnot(long x)
Returns the result of a bitwise NOT operation on value x. Compares each bit in x and sets its bitwise
complement in the corresponding result bit, switching 0 for 1 and 1 for 0. Thus, bitnot(5) returns -6.
(0...0101 returns 1...1010)
Back to Top ^
atan()
77
StreamBase References
bitor()
int bitor(int x, int y)
long bitor(long x, long y)
Returns the result of a bitwise inclusive OR operation on values x and y. Compares each bit in x to the
corresponding bit in y. If either bit is 1 or both bits are 1, sets the corresponding result bit to 1; otherwise, sets
the corresponding result bit to 0. Thus, bitor(12,7) returns 15. (1100 OR 0111 returns 1111)
Back to Top ^
bitxor()
int bitxor(int x, int y)
long bitxor(long x, long y)
Returns the result of a bitwise XOR (exclusive OR) operation on values x and y. Compares each bit in x to
the corresponding bit in y. If either bit is 1 but not both bits, sets the corresponding result bit to 1; otherwise,
sets the corresponding result bit to 0. Thus, bitxor(12,7) returns 11. (1100 OR 0111 returns 1011)
Back to Top ^
cbrt()
Function syntax:
double cbrt(int x)
double cbrt(double x)
double cbrt(long x)
Returns the (real) cube root of x.
Back to Top ^
ceil()
Function syntax:
double ceil(int x)
double ceil(double x)
double ceil(long x)
Returns the smallest double value that is greater than or equal to the argument and is equal to a mathematical
integer. The function name, ceil, is shorthand for ceiling. The argument can be an int, double or long.
Examples:
• ceil(7.01) returns 8.0.
• ceil(8.0) returns 8.0.
• ceil(8) returns 8.0.
• ceil(8L) returns 8.0.
bitor()
78
StreamBase References
See also the related function, floor().
Back to Top ^
cos()
Function syntax:
double cos(int x)
double cos(double x)
double cos(long x)
Returns the cosine of x, where x is given in radians.
Back to Top ^
cosh()
Function syntax:
double cosh(int x)
double cosh(double x)
double cosh(long x)
Returns the hyperbolic cosine of its argument.
Back to Top ^
exp()
Function syntax:
double exp(int x)
double exp(double x)
double exp(long x)
Returns the value of e (the base of natural logarithms) raised to the power of x. The argument x is a small
value of type int, double, or long.
Back to Top ^
expm1()
Function syntax:
double expm1(int x)
double expm1(double x)
double expm1(long x)
Returns (e^x) -1. The argument x is a small value of type int, double, or long.
Back to Top ^
ceil()
79
StreamBase References
floor()
Function syntax:
double floor(int x)
double floor(double x)
double floor(long x)
Returns the largest double value that is less than or equal to the argument x, and equal to a mathematical
integer. The argument can be an int, double, or long. Examples:
• floor(7.01) returns 7.0.
• floor(8.0) returns 8.0.
• floor(8) returns 8.0.
• floor(8L) returns 8.0.
See also the related function, ceil().
Back to Top ^
ln()
Function syntax:
double ln(int x)
double ln(double x)
double ln(long x)
Returns the natural logarithm of x.
Back to Top ^
log10()
Function syntax:
double log10(int x)
double log10(double x)
double log10(long x)
Returns the base-10 logarithm of x.
Back to Top ^
log1p()
Function syntax:
double log1p(int x)
double log1p(double x)
double log1p(long x)
floor()
80
StreamBase References
Returns the natural logarithm of the sum of the argument and 1.
Back to Top ^
lshift()
int lshift(int x, int y)
long lshift(long x, long y)
Returns the result of a bitwise left shift of the bits in x by the number of bit positions y. Thus,
lshift(5,1) returns 10. (0101 returns 1010)
Back to Top ^
max()
Function syntax:
T max(T e1, ..., T en)
This function returns the maximum non-null value using the greater-than relational operator across all its
arguments e1 through en, which must all be expressions resolving to the same data type. The data type, T, of
the returned value is the same as the arguments.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
See also the aggregate version of max(), the maxelement() function for lists, and the aggregate maxn()
function. Use this simple function max(list, , list) to determine the larger of two or more lists. In an
aggregate context, max(list) returns the maximum list in the aggregate window. By contrast, use
maxelement() to compare the element values of a single list.
Back to Top ^
maxdouble()
Function syntax:
double maxdouble()
This function returns the maximum value for the double data type.
Back to Top ^
maxint()
Function syntax:
int maxint()
This function returns the maximum value for the int data type.
log1p()
81
StreamBase References
Back to Top ^
maxlong()
Function syntax:
long maxlong()
This function returns the maximum value for the long data type.
Back to Top ^
min()
Function syntax:
T min(T e1, ..., T en)
This function returns the minimum non-null value using the less-than relational operator across all its
arguments e1 through en, which must all be expressions resolving to the same data type. The data type of the
returned value is the same as the arguments.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
See also the aggregate version of min(), the minelement() function for lists, and the aggregate minn() function.
Use this simple function min(list, , list) to determine the smaller of two or more lists. In an
aggregate context, min(list) returns the minimum list in the aggregate window. By contrast, use
minelement() to compare the element values of a single list.
Back to Top ^
mindouble()
Function syntax:
double mindouble()
This function returns the minimum value for the double data type.
Back to Top ^
minint()
Function syntax:
int minint()
This function returns the minimum value for the int data type.
maxint()
82
StreamBase References
Back to Top ^
minlong()
Function syntax:
long minlong()
This function returns the minimum value for the long data type.
Back to Top ^
orall()
Function syntax:
bool orall(bool b1, bool b2, ...)
Takes two or more values of type boolean, or expressions that resolve to type boolean, and returns the results
of a logical OR operation on all arguments. For example, orall(true, true, false, true,
false) returns true. Use orall() as a falsity detector function.
Null arguments have special handling. A null argument does not change the result of the evaluation if a true
value is among the arguments: orall(null, false, true, null, false) still returns true.
However, if one or more arguments is null while all other arguments are false, the function returns null:
orall(null, false, false, null, false) returns null.
The orall() function follows the logic expressed in this statement:
if any argument is true, return true
else if any argument is null, return null
else return false
See also the andall() simple function and the aggregate versions of andall() and orall().
Back to Top ^
pow()
Function syntax:
double pow(int x, int y)
double pow(double x, double y)
double pow(long x, long y)
Returns the value of x raised to the power of y. Accepts an int, double, or long, and returns a double.
Back to Top ^
minint()
83
StreamBase References
random()
Function syntax:
double random()
Returns a random double value with a positive sign, greater than or equal to 0.0 and less than 1.0.
Back to Top ^
round()
Function syntax:
long
long
long
long
round(double e)
round(int e, int n)
round(double e, int n)
round(long e, int n)
With one argument, a double, returns the closest long to the argument. Floating-point numbers are NOT
supported.
With two arguments, round() is similar to the round() found in Microsoft Excel, but not identical to it. Specify
a double, long, or int in the first argument. Specify an int in the second argument to designate the number of
digits to round the first argument to. Use 0 to specify rounding to an integer, a positive integer to round the
digits after the decimal point, or a negative number to specify rounding digits before the decimal point. If the
first argument is an int or long, the second argument must be negative to actually perform rounding; otherwise
the first argument is returned unchanged.
Back to Top ^
rshift()
int rshift(int x, int y)
long rshift(long x, long y)
Returns the result of a logical bitwise right shift of the bits in x by the number of bit positions y. This is the
equivalent of the Java >> operator. Thus, rshift(5,1) returns 2. (0101 returns 0010)
Back to Top ^
securerandom()
Function syntax:
double securerandom()
A more secure form of random() that generates random bytes, converted to return a double.
Back to Top ^
random()
84
StreamBase References
sign()
Function syntax:
int sign(int x)
int sign(double x)
int sign(long x)
Returns the sign of its argument: â
1 if less than zero, 0 if equal to zero, and 1 if greater than zero.
Back to Top ^
sin()
Function syntax:
double sin(int x)
double sin(double x)
double sin(long x)
Returns the sine of x, where x is given in radians.
Back to Top ^
sinh()
Function syntax:
double sinh(int x)
double sinh(double x)
double sinh(long x)
Returns the hyperbolic sine of its argument.
Back to Top ^
sqrt()
Function syntax:
double sqrt(int x)
double sqrt(double x)
double sqrt(long x)
Returns the nonnegative square root of x.
Back to Top ^
sign()
85
StreamBase References
tan()
Function syntax:
double tan(int x)
double tan(double x)
double tan(long x)
Returns the tangent of x, where x is given in radians.
Back to Top ^double
tanh()
Function syntax:
double tanh(int x)
double tanh(double x)
double tanh(long x)
Returns the hyperbolic tangent of a double value.
Back to Top ^
to_degrees()
Function syntax:
double to_degrees(double x)
Converts an angle measured in radians to an approximately equivalent angle measured in degrees.
Back to Top ^
to_radians()
Function syntax:
double to_radians(double x)
Converts an angle measured in degrees to an approximately equivalent angle measured in radians.
Back to Top ^
unsignedrshift()
int unsignedrshift(int x, int y)
long unsignedrshift(long x, long y)
Returns the result of a bitwise right shift of the bits in x by the number of bit positions y, filling the leftmost
bit position with 0. This is the equivalent of the Java >>> operator. Thus, rshift(-1,1) returns -1
tan()
86
StreamBase References
(1111 1111 1111 1111), but unsignedrshift(-1,1) returns 2147483647 (0111 1111 1111 1111).
Back to Top ^
Simple Functions: NaN
This category includes the following functions:
isnan()
notnan()
The functions in this group detect NaN (not a number) values.
isnan()
Function syntax:
bool
bool
bool
bool
isnan(double value)
isnan(int value)
isnan(long value)
isnan(timestamp value)
Returns true if the argument is NaN (not a number), or returns null if the argument is null. Returns
false otherwise.
Back to Top ^
notnan()
Function syntax:
bool
bool
bool
bool
notnan(double value)
notnan(int value)
notnan(long value)
notnan(timestamp value)
Returns false if the argument is NaN (not a number), or returns null if the argument is null. Returns
true otherwise.
Notice that notnan() returns the opposite of isnan(), except if the argument is null, in which case they
both return null.
Back to Top ^
Simple Functions: Runtime
This category includes the following functions:
getAllHostIPs()
getClientIP()
unsignedrshift()
getLeadershipStatus()
getNodeName()
87
StreamBase References
get_conf_param(), get_datatype_conf_param()
getContainer()
getHostName()
getParallelRoot()
getPath()
getServerURI()
getAllHostIPs()
Function syntax:
list(string) getAllHostIPs()
Returns as a list(string) all the non-loopback IP addresses assigned to the machine on which StreamBase
Server is running.
Back to Top ^
get_conf_param()
Function syntax:
string
boolean
int
long
double
get_conf_param(default-value, path1, path2, path3, ...)
get_boolean_conf_param(default-value, path1, path2, path3, ...)
get_int_conf_param(default-value, path1, path2, path3, ...)
get_long_conf_param(default-value, path1, path2, path3, ...)
get_double_conf_param(default-value, path1, path2, path3, ...)
Returns the value portion of a name-value pair specified with a param element in the currently active server
configuration file, usually named sbd.sbconf. Use the typed versions of the function to convert the
returned value to the specified data type.
These functions only return values from param elements. Other configuration file elements cannot be
accessed with these functions.
The first argument, default-value, specifies a value to return if parsing the configuration file returns
nothing. The arguments path1, path2 ... pathn specify element and attribute names in the XML path to
the value of interest (without counting the streambase-configuration top-level element).
For example, the value of the TCP port might be set in the configuration file with an entry like the following:
<server>
<param name="tcp-port" value="9900" />
</server>
To extract the TCP port value from the configuration file, use the int version of the get_conf_param()
function as follows:
get_int_conf_param(10000, "server", "tcp-port")
In another example, some of the values set in the configuration file's security element are nested deeper:
<security>
<ssl-authentication>
<param name="keystore" value="../security/signed.keystore"/>
Simple Functions: Runtime
88
StreamBase References
<param name="keystore-password" value="secret"/>
</ssl-authentication>
</security>
To extract the keystore-password value, use the following function:
get_conf_param("verysecret", "security", "ssl-authentication",
"keystore-password")
These functions are not expected to work at the command prompt with sbd --eval.
Back to Top ^
getClientIP()
Function syntax:
string getClientIP(string connectionID)
Returns as a string the IP address associated with the specified connectionID. Obtain the
connectionID string from the first field returned by an sbadmin listConnections command, or from the
connection stream in the system container.
Use this function to determine by IP address the actual computer connecting to, or recently disconnected from,
a running instance of StreamBase Server.
This function is not expected to work at the command prompt with sbd --eval.
Back to Top ^
getContainer()
Function syntax:
string getContainer()
Returns as a string the name of the container in which the current application is loaded. Can be used in
expressions like this example:
if getContainer() == "default" ...
This function is not expected to work at the command prompt with sbd --eval.
Back to Top ^
getHostName()
Function syntax:
string getHostName()
get_conf_param()
89
StreamBase References
Returns as a string the machine name of the host on which StreamBase Server is running. Can be used in
expressions like this example:
if getHostName() == "fasthost" ...
Back to Top ^
getLeadershipStatus()
Function syntax:
string getLeadershipStatus()
Returns the string LEADER or NON_LEADER, which represent the current StreamBase Server's leadership
status as a member of a high availability cluster. Servers have LEADER status by default on startup, which
can be changed with the sbadmin setLeadershipStatus command.
This function is not expected to work at the command prompt with sbd --eval.
Back to Top ^
getNodeName()
Function syntax:
string getNodeName()
Returns as a string the name of the node in which the current application is loaded. Can be used in expressions
like this example:
if getNodeName() == "primaryserver" ...
This function is not expected to work at the command prompt with sbd --eval.
Back to Top ^
getParallelRoot()
Function syntax:
string getParallelRoot()
Returns the qualified path name of the top-level container or Module Reference that is the root of the current
parallel region. See Parallel Region Defined.
If this function is called in a simple module without concurrency settings, it returns the path name of the
container that holds the operator that calls this function. If this function is called in a module whose Module
Reference has a concurrency setting of Run in a parallel region, it returns the qualified path to that Module
Reference. If the Module Reference also has a Multiplicity setting of multiple, and the number of instances is
set to 2 or more, the returned path is appended with a colon and a zero-based integer representing the instance
getHostName()
90
StreamBase References
number of the calling module.
Thus:
• When called in a simple module in the default container, this function returns default.
• When called in a module, B, that has a Module Reference named B_ref in the top-level module, A,
this function returns default.B_ref if the Module Reference is marked with the Run in a parallel
region concurrency option.
• In addition to the parallel region setting, if B_ref is also configured with a Multiplicity setting of 2,
this function returns either default.B_ref:0 or default.B_ref:1.
See StreamBase Path Notation for details on the qualified path names that can be returned.
This function is not expected to work at the command prompt with sbd --eval.
Back to Top ^
getPath()
Function syntax:
string getPath(string componentname)
Returns the qualified path of the specified component of a StreamBase application. Can be used for verifying
the container name for the specified component at run time, in expressions like this example:
if getPath("Symbol") == "default.Symbol" ...
See StreamBase Path Notation for details on the qualified path names that can be returned.
This function is not expected to work at the command prompt with sbd --eval.
Back to Top ^
getServerURI()
Function syntax:
string getServerURI()
Returns the StreamBase URI of the currently running StreamBase Server. The value returned is from the point
of view of the server, and thus always returns the hostname localhost. Use this function to obtain the port
number and any authentication parameters appended to the URI.
Use this function instead of systemproperty("streambase.uri") to obtain the same information.
This function is not expected to work at the command prompt with sbd --eval.
Back to Top ^
getParallelRoot()
91
StreamBase References
Simple Functions: Strings
This category includes the following functions:
contains()
endswith()
format()
indexof() (for strings)
isempty() (for strings) lastindexof() (for strings) length() (for strings)
lower()
ltrim()
regexmatch()
regexmatch_ignorecase() regexreplace()
regexsplit()
rtrim()
split()
startswith()
string()
strlen()
strresize()
strresizetrunc()
substr()
trim()
upper()
The behavior of functions that deal with strings changes when Unicode support is enabled for StreamBase
Server as described in Unicode Support. These cases are noted for each function in this section.
contains()
Function syntax:
bool contains(string haystack, string needle)
Takes two arguments: a string and a search string. Returns true if needle is a substring of haystack, or
false if not.
If either argument is null, returns null.
Back to Top ^
endswith()
Function syntax:
bool endswith(String biggerString, String smallerString)
Takes two arguments: a string to search within and a (sub)string to search for. Returns true if biggerString
ends with smallerString, or false if not.
If either argument is null, returns null.
Back to Top ^
format()
Function syntax:
string format(string format-string, arg0, arg1, ..., argn)
Returns a formatted string for arguments arg0 through argn, each formatted according to a specification in
format-string.
Simple Functions: Strings
92
StreamBase References
Format specifications are patterns specified in the manner of class java.text.MessageFormat in the
Sun Java Platform SE reference documentation.
For example, an incoming stream containing NYSE stock ticks might have a field named symbol containing
four-character stock symbols. Let's say a downstream operator expects symbols to be prefixed with a string
identifying their source stock exchange. In this case, use an expression like the following in a Map operator:
format("NYSE:{0}", symbol)
An incoming stream might have a price field specified to four decimal places. When the flow of tuples
reaches an output stream that must be formatted for human readability, you can use an expression like the
following to round the price field to two decimal places. This example assumes that the price field
contains values of type double, which matches the format specifier ###.##.
format("{0,number,###.##}", price)
The format for argument arg0 is specified with the portion of the format-string that defines {0}. The
format for arg1 is in the format-string portion that defines {1}, and so on. The data type of arg0
must match the type expected by the format-string specifier for {0}, and so on for each argument.
If you use format() to modify a tuple, use {0}, {1}, {2} and so on to specify the format for each field.
See the documentation for java.text.MessageFormat for further details and more examples.
Back to Top ^
indexof()
Function syntax:
int indexof(string haystack, string needle [, int start])
Returns the index of the first instance of the string needle within the string haystack, for which the index
is greater than or equal to start. For all supported Unicode character sets, this function returns the index in
number of graphemes, not bytes. For string arguments, if needle is not found, the function returns a value of
-1.
If the search is successful, the value returned is always greater than or equal to start. If start is
unspecified, it is taken to be 0, which designates the first character of the string or the first element of the list.
See also the indexof() function that operates on lists.
Back to Top ^
isempty()
Function syntax:
bool isempty(String str)
Takes one string argument, str. Returns true if str is null or "" (empty), or false if not.
format()
93
StreamBase References
Back to Top ^
lastindexof()
Function syntax:
int lastindexof(string haystack, string needle [, int lastStart])
Returns the index within string haystack of the rightmost instance of string needle, for which the index
is less than or equal to lastStart. For all supported Unicode character sets, this function returns the index
in number of graphemes, not bytes. For string arguments, if needle is not found, the function returns a value
of -1.
If the search is successful, the value returned is always less than or equal to lastStart. If lastStart is
unspecified, it is taken to be the index of the last grapheme of the string or the last element of the list.
See also the lastindexof() function that operates on lists.
Back to Top ^
length()
Function syntax:
int length(string x)
Returns the number of graphemes in the string, for ASCII and all supported Unicode character sets. If the
argument is a null string, the returned value is null.
See also the length() functions that operate on lists and blobs.
Back to Top ^
lower()
Function syntax:
string lower(string str)
Returns its argument in lowercase letters.
Back to Top ^
ltrim()
Function syntax:
string ltrim(string str)
string ltrim(string s1, string s2)
The same as trim(), except that the first argument is trimmed on the left side only.
isempty()
94
StreamBase References
Back to Top ^
regexmatch()
Function syntax:
bool regexmatch(string regex, string str)
Attempts to match the specified regular expression in regex against the entire specified string in str. To
match any substring of the specified string, use wildcards before and after your regular expression. For
example, the regex IBM matches only when the entire string is "IBM", while the regex .*IBM.* matches if
"IBM" is anywhere in the supplied string str.
Back to Top ^
regexmatch_ignorecase()
Function syntax:
bool regexmatch_ignorecase(string regex, string str)
Same as regexmatch(), but the supplied regex matches str without regard to case.
Back to Top ^
regexreplace()
Function syntax:
string regexreplace(string input_str, string regex_str, string replace_str [, int limit])
Accepts an input string, a regular expression pattern, a replacement string, and an optional integer, limit.
Returns input_str modified by replacing occurrences of regex_str in input_str with
replace_str up to limit times. If limit is negative or omitted, all occurrences in input_str are
replaced.
See Sun's Pattern class documentation for the supported regular expression syntax. The replace_str
argument can contain references to fields in a regular expression capture group, in the same way as
java.util.regex.Matcher.appendReplacement().
Usage note: the similar replace() command operates on string literals, and substitutes a string literal for a
literal search string. The regexreplace() command operates on string literals, but substitutes its string literal for
a regular expression search, and has support for capture groups. It would appear at first glance that
regexreplace() without the optional limit argument is the same as replace(), but the difference in the second
argument means the two commands have different semantics. For example, consider the following commands
and their results:
replace("this.string", ".", ",") returns this,string
regexreplace("this.string", ".", ",") returns ,,,,,,,,,,,
ltrim()
95
StreamBase References
regexreplace("this.string", "\\.", ",") returns this,string
Back to Top ^
regexsplit()
Function syntax:
list(string) regexsplit(string input_str, string regex_delimiter [, int limit])
Use the regexsplit() function in the same ways as the split() function, except that you can specify a regular
expression as the field delimiter. See Sun's Pattern class documentation for the supported regular expression
syntax.
The following example parses input_str into list elements using either colon, semicolon, or a space as the
field delimiter:
regexsplit("aaa:bbb;ccc:ddd;eee fff", "[:; ]")
returns
list(string) [aaa, bbb, ccc, ddd, eee, fff]
See split() for further details and for instructions on using the optional limit argument.
Back to Top ^
replace()
Function syntax:
string replace(string main_str, string search_str, string replace_str)
Returns main_str after locating all instances of search_str and replacing them with replace_str.
The search_str and replace_str arguments are read as case-sensitive, literal strings. Any wildcard
character is read as the literal character, not a wildcard.
Examples:
For a string field named UStext in the incoming stream: replace(UStext, "honor", "honour")
replace('Open the pod bay doors, IBM.', 'IBM' , 'HAL')
replace('1,2,3,4,5', ',' , '-')
See also the regexreplace() command and the usage note there comparing with replace() syntax.
Back to Top ^
regexreplace()
96
StreamBase References
rtrim()
Function syntax:
string rtrim(string str)
string rtrim(string s1, string s2)
The same as trim(), except that the first argument is trimmed on the right side only.
Back to Top ^
split()
Function syntax:
list(string) split(string input_str, string delimiter [, int limit])
Returns a list of strings parsed from input_str, splitting the input string into pieces delimited by the
character or phrase specified as delimiter. The delimiter character or phrase itself is not preserved in
the resulting list when a match is found. For example:
split("aaa:bbb:ccc:ddd:eee", ":")
returns
list(string) [aaa, bbb, ccc, ddd, eee]
If the delimiter character or phrase is not found in input_str, then input_str is returned verbatim as
the only element of the resulting list. If the delimiter character or phrase occurs adjacent to another instance of
the delimiter, the result is an empty list element. For example, split("aaa::bbb", ":") results in the
following three-element list: [aaa, ,bbb].
You can specify an optional third argument, limit, an integer specifying the number of list elements in the
result list. Use the limit argument in the following ways:
• If limit is any negative number, input_str is split into as many list elements as necessary, with
no limit on the length of the list. All empty list elements are preserved, including any trailing empty
elements. For example, split("aaa::bbb::", ":", -1) results in a five-element list:
[aaa, ,bbb, , ].
• If limit is zero or unspecified, input_str is split into as many list elements as necessary, but any
trailing empty elements are discarded. For example, split("aaa::bbb::", ":", 0) and
split("aaa:bbb::", ":") both result in a three-element list: [aaa, ,bbb].
• If limit is positive, input_str is split into at most limit-1 elements, plus one more element
containing the remainder of input_str. For example, split("aaa:bbb:ccc:ddd:eee",
":", 3) results in a three-element list: [aaa, bbb, ccc:ddd:eee].
Use this feature to split a string into the components you want to process, followed by a single
catch-all element containing the remainder.
See also the regexsplit() function, a variation of split() that allows you to use a regular expression to specify
the delimiter.
rtrim()
97
StreamBase References
Back to Top ^
startswith()
Function syntax:
bool startswith(String biggerString, String smallerString)
Takes two arguments: a string to search within and a (sub)string to search for. Returns true if biggerString
begins with smallerString, or false if not.
If either argument is null, returns null.
Back to Top ^
string()
Converts its argument into a string. See string() in the Simple Functions: Type Conversions section.
strlen()
Function syntax:
int strlen(string str)
Returns the length of the string str. This function returns the number of graphemes, not bytes, for all
supported Unicode character sets.
Back to Top ^
strresize()
Function syntax:
string strresize(string str, int length)
The strresize() function performs no action: it simply returns its str argument and ignores the
length argument. The function is preserved for compatibility with previous StreamBase releases, in which
the StreamBase string data type had a fixed maximum size. To perform string truncation, use substr() or
strresizetrunc().
Back to Top ^
strresizetrunc()
Function syntax:
string strresizetrunc(string str, int length)
Returns its argument str, truncated to the number of bytes specified in length.
split()
98
StreamBase References
Note
When using strresizetrunc() with Unicode multibyte character sets, count the length argument in
bytes, not graphemes.
Back to Top ^
substr()
Function syntax:
string substr(string str, int begin, int length)
Returns a substring of the string str, starting at the zero-indexed character begin with a size of length
characters.
For all supported Unicode character sets, specify length in number of graphemes, not bytes.
Back to Top ^
trim()
Function syntax:
string trim(string str)
string trim(string s1, string s2)
With one argument, returns the specified string with leading and trailing spaces removed.
With two arguments, the second argument contains the characters to be removed from the string specified in
the first argument.
Back to Top ^
upper()
Function syntax:
string upper(string str)
Returns its argument in uppercase letters.
Back to Top ^
Simple Functions: System
This category includes the following functions:
nanotime()
Note
99
StreamBase References
sleep()
systemenv()
systemproperty()
nanotime()
Function syntax:
long nanotime()
Returns the current value of the system timer as a long value in nanoseconds. This function does not guarantee
to return an accurate measurement of the system clock to the nanosecond level of precision, but does provide
an accurate counter at nanosecond precision. Therefore, use this function only to measure elapsed time
between two invocations, like the following example:
long startcount = nanotime()
// process tuple data
long elapsedtime = nanotime() - startcount
Differences in two calls to nanotime() are not accurate for a span greater than 263 (about 292 years). Do not
compare nanotime() values between different machines or even across machine restart boundaries on the same
machine, since the hardware time counters are reset on reboot.
Back to Top ^
sleep()
Function syntax:
timestamp sleep(timestamp t)
Pauses execution of the current thread for the specified time period. The argument must be an interval
timestamp, and the return value is the argument. This function can be useful in conjunction with operators that
run in a separate thread, and is provided for debugging or for rare uses. The sleep() function blocks the
concurrent portion of an application, if concurrency is enabled, or blocks the container holding the
application, if concurrency is not enabled. Therefore, use sleep() with care in production applications. To
learn about threading in StreamBase applications, refer to Execution Order and Concurrency.
Back to Top ^
systemenv()
Function syntax:
string systemenv(string key)
Calls the standard Java method java.lang.System.getenv(). Returns the string value of the
environment variable specified by the key argument.
Back to Top ^
Simple Functions: System
100
StreamBase References
systemproperty()
Function syntax:
string systemproperty(string key [, string defaultstring])
Calls the standard java.lang.System.getProperty() method. Returns the string value of the
system property specified by the key argument. Use the standard set of system property keys described in
Java documentation for java.lang.System.getProperties() (for example, os.name,
java.home, and user.name), or specify a StreamBase-specific Java property.
If the optional defaultstring argument is used, and there is no system property for the specified key, the
function returns the string specified in the defaultstring argument. If no default string is provided, null
is returned.
Back to Top ^
Simple Functions: Timestamp Overview
The timestamp data type can hold either an absolute timestamp or an interval timestamp.
An absolute timestamp represents a date and time. Its value is the number of seconds between the epoch and
that date and time, with a maximum precision of milliseconds. The epoch is defined as midnight of January 1,
1970 UTC.
An interval timestamp represents a duration. Its value is the number of seconds in the interval, with a
maximum precision of milliseconds.
Absolute timestamps are expressed in the time format patterns of the java.text.SimpleDateFormat
class described in the Sun Java Platform SE reference documentation and in the description of the
format_time() function below. Examples on this page are taken from the results of running sbd --eval
commands.
See timestamp Data Type for information on the range of timestamp values, on adding and subtracting
timestamp values, and on comparing timestamps with relational operators.
Timestamp functions are organized into the following categories, described in the next three sections:
Timestamp Functions: Absolute Timestamps
Timestamp Functions: Interval Timestamps
Timestamp Functions: Timestamp Fields
Timestamp Functions: Absolute Timestamps
This category includes the following functions, which return an absolute timestamp or a string converted from
an absolute timestamp:
date()
epoch()
format_time()
from_gmtime() from_localtime() now()
systemproperty()
101
StreamBase References
parse_time()
strftime()
strptime()
today()
today_utc()
See also the nanotime() function in the System category.
Usage Note
StreamBase offers two similar functions to convert a StreamBase timestamp to a string: format_time() and
strftime(). These functions use different libraries, Java and C++ respectively, to provide support for their time
format strings.
Be aware that these libraries make opposite use of the z and Z format strings, as shown in this table:
function
Meaning of lowercase z or %z
format_time() Time zone abbreviation (BST, EST, PDT)
Meaning of uppercase Z or %Z
Time zone signed number (+0100, -0500,
-0800)
Time zone signed number (+0100, -0500,
Time zone abbreviation (BST, EST, PDT)
-0800)
StreamBase also provides two similar functions for parsing a time format string in any format and converting
it to a StreamBase absolute timestamp: parse_time() and strptime(). These are based on the same Java and
C++ libraries, respectively.
strftime()
The parse_time() function interprets the z and Z format strings equally. The input timestring can be in
either text, abbreviation, or signed number format, and either case of Z interprets them as time zone specifiers.
The strptime() function interprets the %z and %Z format strings as separate identifiers. When using strptime(),
specify lowercase z in the formatstring if the incoming timestring expresses the time zone as a
signed number, such as +0100, -0500, or -0800. Specify uppercase Z in the formatstring in the
incoming timestring expresses the time zone as text or a standard abbreviation: BST, EST, PDT, or
America/New York.
date()
Function syntax:
timestamp date(timestamp ts)
Accepts a timestamp ts and returns an absolute timestamp for the year, month, and day portion of ts, with
all time values set to zero. This, in effect, extracts and returns the timestamp for midnight local time for the
date in the argument ts.
For example, the function now(), run on 12 Feb 2009 in the EST time zone, returns a full timestamp like this
one:
(timestamp) 2009-02-12 15:48:45.679-0500
But the same function used as an argument for date():
date(now())
Timestamp Functions: Absolute Timestamps
102
StreamBase References
returns the following. Notice that all time information was changed to zero to designate midnight:
(timestamp) 2009-02-12 00:00:00.000-0500
Back to Top ^ Back to Timestamp Overview ^
epoch()
Function syntax:
timestamp epoch()
Returns an absolute timestamp representing the zero point of counted time. For both Windows and UNIX, the
epoch is midnight, January 1st, 1970. The value returned is adjusted for the current time zone. To see the
absolute epoch, use:
epoch() - timezoneoffset()
Because the epoch occurred during standard time in the northern hemisphere, you may need to add a one-hour
offset if you are retrieving the absolute epoch during daylight savings time:
epoch() - timezoneoffset() + hours(1)
Incoming tuples from a market data provider or an exchange might include a timestamp field in the form of a
long value (or integer value) representing the number of milliseconds (or number of seconds) since the epoch.
Use epoch() to convert such field values to an absolute timestamp.
Many functions, including java.util.Date.getTime(), return a long value representing the number
of milliseconds since the epoch. The timestamp value in market data from many exchanges use this format.
To convert such long values, TSms, to an absolute timestamp, use an expression like the following:
milliseconds(TSms) + epoch()
Functions that return UNIX time, including the UNIX date +%s command, generally return an integer
number of seconds. To convert such integer values, TSsec, to an absolute timestamp, use an expression like
the following:
seconds(TSsec) + epoch()
Use seconds() as above, for double values that include a fractional milliseconds component, such as the value
returned from the Python time.time() function.
Use to_seconds() or to_milliseconds() to take a formatted timestamp string and return the number of seconds
or milliseconds since the epoch, respectively.
Back to Top ^ Back to Timestamp Overview ^
date()
103
StreamBase References
format_time()
Function syntax:
string format_time(timestamp ts, string formatstring)
Converts the specified timestamp field, ts, to a string, using the specified formatstring pattern. The
timestamp field can then be manipulated as a string instead of a timestamp. This function uses the time format
patterns from the SimpleDateFormat class described in the Sun Java Platform SE reference
documentation and summarized below.
For example, the function now(), run on 12 Feb 2009 in the EST time zone, returns a timestamp like this one:
(timestamp) 2009-02-12 15:48:45.679-0500
The same function used as an argument for format_time():
format_time(now(), "EEEE, MMM d, yyyy HH:mm zzzz")
returns the following:
(string) Thursday, Feb 12, 2009 15:48 Eastern Standard Time
You can use any combination of time format designators from the SimpleDateFormat class. For example:
format_time(now(), "yyyy-MM-dd G, HH:mm a")
returns:
(string) 2009-02-12 AD, 15:48 PM
This function performs the same task as strftime(), but uses a different library source for its format
pattern strings. The strftime() function is faster than format_time(), and should be used when
performance is critical in your application. The format pattern strings used by format_time() are easier to
use. See the Usage Note about the different ways this function and strftime() interpret the z and Z
formatstring specifiers.
The following table shows the format strings supported by format_time(). See the
SimpleDateFormat documentation for further details.
formatstring
Component
a
d
D
E
Meaning
AM or PM
Day in the month
Day in the year
Day of the week. Use EEEE for the full day spelling, EEE or fewer
for the abbreviation.
F
Number of the day of the week.
G
The era.
format_time()
Examples
AM
11, 31
234
Friday, Fri
2 for
Tuesday
AD, BC
104
StreamBase References
h
H
k
K
m
The one-based hour on a 12-hour clock, 1 to 12.
The zero-based hour on a 24-hour clock, 0 to 23.
The one-based hour on a 24-hour clock, 1 to 24.
The zero-based hour on a 12-hour clock, 0 to 11.
The minute in the hour.
The month of the year. Use MM for a two-digit month, MMM for an
abbreviated month name, MMMM for the full month name.
The second in the minute.
The millisecond fraction of the second
The number of the week in the year.
The number of the week in the month.
The year. Use yy for a two-digit year, interpreted as belonging to the
century 80 years prior to or 20 years ahead of the use of this function.
Use more than two y's to interpret the year literally.
12
23
24
11
25
11, Nov,
M
November
s
23
S
456
w
27
W
3
In 2011, yy =
y
11, yyyy =
2011.
EST, Eastern
The time zone shown as text. Use three or fewer z's for the time zone
Standard
z
abbreviation, four z's for the full time zone name.
Time
The time zone offset from UTC, shown as a positive or negative
-0500
Z
number as in RFC 822.
Back to Top ^ Back to Timestamp Overview ^
from_gmtime()
Function syntax:
timestamp from_gmtime(int year, int month,
int dayOfMonth, int hour, int minute, double seconds)
Creates an absolute timestamp in the UTC (GMT) time zone from the specified integer components of a date
and time. All six arguments are required. You can express the seconds argument as a double with precision
down to milliseconds, or you can use an integer, which is promoted automatically to a double by the rules of
StreamBase Data Type Coercion and Conversion.
You might use this function on a stream that has the date and time broken into integer fields to concatenate
and translate those fields into a single timestamp value.
Notice that the returned timestamp shows a moment in the UTC time zone, but that moment is translated and
displayed in the local time zone. For example, compare the same arguments given to from_gmtime() and
from_localtime() when run in the EST time zone:
from_gmtime(2009, 3, 17, 18, 30, 05)
returns:
(timestamp) 2009-03-17 14:30:05.000-0400
while
from_gmtime()
105
StreamBase References
from_localtime(2009, 3, 17, 18, 30, 05)
returns:
(timestamp) 2009-03-17 18:30:05.000-0400
Back to Top ^ Back to Timestamp Overview ^
from_localtime()
Function syntax:
timestamp from_localtime(int year, int month,
int dayOfMonth, int hour, int minute, double second)
Creates an absolute timestamp in the local time zone from the specified integer components of a date and
time. All six arguments are required. You can express the seconds argument as a double with precision
down to milliseconds, or you can use an integer, which is promoted automatically to a double by the rules of
StreamBase Data Type Coercion and Conversion.
You might use this function on a stream that has the date and time broken into integer fields to concatenate
and translate those fields into a single timestamp value.
For example:
from_localtime(2009, 3, 17, 18, 30, 05)
returns:
(timestamp) 2009-03-17 18:30:05.000-0400
Back to Top ^ Back to Timestamp Overview ^
now()
Function syntax:
timestamp now()
Returns an absolute timestamp value representing the current time in the local time zone.
You can specify an alternate now() implementation in the StreamBase Server configuration file. The value is
set in the runtime section:
<param name="now-implementation" value="system" />
Specify one of these values, as appropriate for your StreamBase application:
Value
Meaning
system Directs the now() function to use Java's System.currentTimeMillis(). This is the default.
thread
from_localtime()
106
StreamBase References
Directs the now() function to use a background thread that checks the time approximately every
millisecond. This option results in decreased accuracy, but may be more efficient than system if
you call now() more frequently than 1000 times per second.
Back to Top ^ Back to Timestamp Overview ^
parse_time()
Function syntax:
timestamp parse_time(string timestring, string formatstring)
Parses a string of time and date information and returns an absolute timestamp value. The timestring
argument can be any string representation of date and time, as long as its components are individually
parsable.
You must also specify a formatstring argument to specify how the timestring argument is to be
interpreted. The format string must specify a time format pattern as defined in the SimpleDateFormat
class, described in the Sun Java Platform SE reference documentation. See the format_time() function for a
summary of the time format pattern strings.
Use this function to read a time and date string in any format in an incoming stream, and still interpret that
string as an absolute timestamp. For example, an incoming field, TradeTime, might contain the time and
date in the following string format:
TradeTime = "11:17 Fri Feb 13, 09"
In this case, interpret the field TradeTime as a StreamBase timestamp with an expression like the following:
parse_time(TradeTime, "HH:mm EE MMM dd, yy")
which returns:
(timestamp) 2009-02-13 11:17:00.000-0500
If the timestring argument includes a time zone specifier, this function interprets the zone and returns the
timestamp converted to local time. The time zone specifier can be in standard text or signed number format,
such as EST, PDT, -0500, -0800, +0100. You can specify either z or Z to match the time zone specifier.
This function interprets the z and Z format strings equally. The input timestring can be in either text,
abbreviation, or signed number format, and either case of Z interprets them as time zone specifiers.
For example, we can add Central European Time to the TradeTime field using its signed number
designation:
TradeTime = "11:17 Fri Feb 13, 09 +0100"
In this case, add a z or Z to the formatstring argument:
parse_time(TradeTime, "HH:mm EE MMM dd, yy Z")
now()
107
StreamBase References
When run in the EST zone, this function returns the following. You can use the timezoneoffset() function to
force the interpretation for a different time zone.
(timestamp) 2009-02-13 05:17:00.000-0500
Notice that it is inconsistent for a time string to contain an hours field based on a 24 hour clock and at the
same time to specify AM or PM in the same string. Thus, it is inconsistent to specify both HH for the hours
field and a for AM/PM in the same format string. If your time string contains AM or PM, use lowercase hh to
interpret the hours field. StreamBase does not flag an error if you specify HH and a in the same format string,
but the hours interpretation will be 12 hours offset for afternoon hours.
This function performs the same task as strptime(), but uses a different library source for its format
pattern strings. The strptime() function is faster than parse_time(), and should be used when
performance is critical in your application. The format pattern strings used by parse_time() are easier to
use. See the Usage Note about the different ways this function and strptime() interpret the z and Z
formatstring specifiers.
See also the timestamp() function.
Back to Top ^ Back to Timestamp Overview ^
strftime()
Function syntax:
string strftime(string formatstring, timestamp ts)
Converts the specified timestamp field, ts, to a string, formatted according to the specified formatstring
pattern. The timestamp field can then be displayed and manipulated as a string instead of a timestamp.
This function uses time format patterns described in the table below, which are based on the strftime library,
part of the Open Group's Single UNIX Specification.
As an example of using strftime(), consider that the function now(), when run on 18 Feb 2010 in the EST time
zone, returns a timestamp like this one:
(timestamp) 2010-02-18 15:42:35.461-0500
Here is the same function used as an argument for strftime():
strftime("Traded at %H:%M and %S.%f seconds on %b %d, %Y", now())
which returns the following:
(string) Traded at 15:42 and 35.461 seconds on Feb 18, 2010
This function performs the same task as format_time(), but uses a different library source for its format
pattern strings. This strftime() function is faster than format_time(), and should be used when
performance is critical in your application. The format pattern strings used by format_time() are easier to
use. See the Usage Note about the different ways this function and format_time() interpret the z and Z
formatstring specifiers.
parse_time()
108
StreamBase References
The following table shows the format strings supported by strftime(). See the strftime library
documentation for further details.
formatstring
Component
%a
%A
%b
%B
%c
%C
%d
%D
%e
%f *
%F
%g
%G
%h
%H
%I
%j
%k
%l
%m
%M
%n
%p
%r
%R
%s *
%S
%t
%T
%u
%U
%V
%w
strftime()
Meaning
The locale's abbreviated weekday name: Mon, Wed.
The locale's full weekday name: Monday, Wednesday.
The locale's abbreviated month name: Jan, Nov.
The locale's full month name: January, November.
The locale's default time and date string.
The year divided by 100 and truncated to an integer: 99, 00, 02, 11
The two-digit day of the month, from 01 to 31.
The month, day, and year with slash separator. Equivalent to specifying %m/%d/%y.
The one- or two-digit day of the month, from 1 to 31. Like %d, except single digit days
are preceded by a space.
The milliseconds portion of timestamp.
The month, day, and year with hyphen separator. Equivalent to specifying %m-%d-%y.
The last two digits of the year.
The four-digit year.
Same as %b.
The two-digit hour on a 24-hour clock, 00 to 23.
The two-digit hour on a 12-hour clock, 01 through 12.
The three-digit day of the year, 1 through 366.
The one or two digit hour on a 24-hour clock, with leading space if < 10.
The one or two digit hour on a 12-hour clock, with leading space if < 10.
The two-digit number of the month, 01 to 12.
The two-digit minute, from 00 to 59.
Replaced with a new line character.
The locale's equivalent of AM or PM.
The time in AM or PM notation. For the POSIX locale, the same as %I:%M:%S %p
(Not supported by the StreamBase strftime() function.)
The time value of timestamp ts in milliseconds divided by 1000.
The two-digit second, from 00 to 60. (60 is available in case of leap seconds)
Replaced with a tab character.
The time, equivalent to %H:%M:%S
The numeric day of the week, 1 through 7, with Monday = 1.
The two-digit number of the week of the year, from 00 through 53. The first January
Sunday begins week 1; days in the new year before that Sunday are in week 0.
The two-digit number of the week of the year, from 01 through 53, with Monday as the
first day. If the first week has four or more January days, it is week 1; otherwise it is the
last week of the previous year. That is, January 4th and the first Thursday of January are
always in week 1.
The numeric day of the week, 0 through 6, with Sunday = 0.
109
StreamBase References
%W
%x
%X
%y
%Y
%z
%Z
%%
%+
*
The two-digit number of the week of the year, from 00 through 53. The first January
Monday begins week 1; days in the new year before that Monday are in week 0.
The date, using the locale's default date format.
The time, using the locale's default time format.
The year in two digits, from 00 through 99.
The year in four digits.
The time zone offset from UTC in ISO 8601:2000 standard format, such as +hhmm or
-hhmm, or empty if no time zone can be determined.
The time zone name or abbreviation, or empty if no zone information is in the
timestamp being converted.
Replaced by a literal %.
Returns the current time formatted as if you had specified "%a %b %d %H:%M:%S
%Z %Y". For example, strftime("%+", now()) returns a string like the
following:
Thu Feb 18 15:42:35 EST 2010
* These format patterns are StreamBase extensions not found in the Open Group's strftime() function, or used
differently.
Some format strings can be modified with E or O between the percent sign and the format character. See the
strftime library documentation for further details.
Back to Top ^ Back to Timestamp Overview ^
strptime()
Function syntax:
timestamp strptime(string timestring, string formatstring)
Parses a string of time and date information and returns an absolute timestamp value. The timestring
argument can be any string representation of date and time, as long as its components are individually
parsable.
You must also specify a formatstring argument to specify how the timestring argument is to be
interpreted. The format string must specify a time format pattern using a subset of the patterns defined for the
strptime library (part of the Open Group's Single UNIX Specification), as listed in the table below.
This function interprets the %z and %Z format strings as separate identifiers. Specify lowercase z in the
formatstring if the incoming timestring expresses the time zone as a signed number, such as
+0100, -0500, or -0800. Specify uppercase Z in the formatstring in the incoming timestring
expresses the time zone as text or a standard abbreviation: BST, EST, PDT, or America/New York.
Use this function to read a time and date string in any format in an incoming stream, and still interpret that
string as an absolute timestamp. For example, an incoming field, TradeTime, might contain the time and
date in the following string format:
TradeTime = "15-51-26.984 May 12, 09"
In this case, interpret the field TradeTime as a StreamBase timestamp with an expression like the following:
strptime()
110
StreamBase References
strptime(TradeTime, "%H-%M-%S.%f %b %d, %y")
which returns:
(timestamp) 2009-05-12 15:51:26.984-0400
This function performs the same task as parse_time(), but uses a different library source for its format
pattern strings. This strptime() function is faster than parse_time(), and should be used when
performance is critical in your application. The format pattern strings used by parse_time() are easier to
use. See the Usage Note about the different ways this function and parse_time() interpret the z and Z
formatstring specifiers.
See also the timestamp() function, and strpinterval(), a function similar to strptime(), but for interval
timestamps.
The following table shows the format strings supported by strptime(). See the strptime library
documentation for further details.
formatstring Component
Meaning
The month, using the current locale's month names. Abbreviated and
%b
full month names are recognized.
%B
Same as %b.
%d
The day of the month, from 1 to 31.
The month, day, and year with slash separator. Equivalent to specifying
%D
%m/%d/%y.
%f *
The milliseconds portion of the seconds field.
The hour, using a 12-hour clock, 0 to 11, or a 24-hour clock, 0 to 23. If
the incoming string expresses hours on a 12-hour clock, be sure to
%H
include the %p format string. If an incoming string's hours value is from
12 to 23 and the format string includes %p, the %p is ignored.
%m
The number of the month, 1 to 12.
%M
The minute, from 0 to 59.
%p
The strings AM or PM.
%S
The second, from 0 to 59.
%x
The date, using the locale's default date format.
The year in two digits. Values in the range 69 to 99, inclusive, are
%y
interpreted as 1969 through 1999. Values in the range 00 through 68,
inclusive, are interpreted as 2000 through 2068.
%Y
The year in four digits.
A time zone designator in the form +hhmm, -hhmm, +hh:mm, or
%z *
-hh:mm. Examples: -0500, +1430, -08:00
A standard time zone string or abbreviation, such as EST, GMT-05:00,
%Z *
America/Los_Angeles.
Use an exclamation point in the format string to indicate that the
!
remainder of the input string is optional.
For %d, %H, %m, %M, and %S, leading zeros are recognized but not required.
strptime()
111
StreamBase References
* These format patterns are StreamBase extensions not found in the Open Group's strptime() function, or are
used differently.
Back to Top ^ Back to Timestamp Overview ^
today()
Function syntax:
timestamp today()
Returns an absolute timestamp value for the beginning of the current day (midnight) in the local time zone.
Back to Top ^ Back to Timestamp Overview ^
today_utc()
Function syntax:
timestamp today_utc()
Returns an absolute timestamp value for the beginning of the current day (midnight) in the UTC (GMT) time
zone, translated for the local time zone.
Thus, when today() and today_utc() are run in sequence in the US Eastern time zone during standard
time, they return:
2009-02-13 00:00:00.000-0500
2009-02-12 19:00:00.000-0500
The expressions today() and today_utc() - timezoneoffset() return the same value:
2009-02-13 00:00:00.000-0500
2009-02-13 00:00:00.000-0500
On UNIX, today_utc() requires the TZ environment variable to be set in order to translate correctly to the
local time zone. On Windows, the TZ environment variable is ignored if set.
Back to Top ^ Back to Timestamp Overview ^
Timestamp Functions: Interval Timestamps
This category includes the following functions, which return an interval timestamp:
days()
isinterval()
seconds()
timezoneoffset()
today()
hours()
interval()
milliseconds() minutes()
strpinterval() time()
weeks()
112
StreamBase References
days()
Function syntax:
timestamp days(int x)
timestamp days(double x)
Returns an interval timestamp representing an interval of x days.
Back to Top ^ Back to Timestamp Overview ^
hours()
Function syntax:
timestamp hours(int x)
timestamp hours(double x)
Returns an interval timestamp representing an interval of x hours.
Back to Top ^ Back to Timestamp Overview ^
interval()
Function syntax:
timestamp interval(string formatstring)
Parses the argument formatstring as a time format string and returns an interval timestamp. This function
uses the time format patterns from strftime library, described in the Open Group's Single UNIX Specification.
See the table of format patterns listed for the strftime() function.
The time format string is in the form %H:%M:%S!.!%f. The exclamation points show where the remainder
of the string is optional. Thus, you can enter strings in any of the following formats, where hh = hours, mm =
minutes, ss = seconds, and ff = a fractional second value in milliseconds:
• hh:mm:ss
• hh:mm:ss.
• hh:mm:ss.ff
For example:
interval("2:00:01")
interval("2:00:01.")
both return (timestamp) 7201.0, the number of seconds in the specification of two hours plus one
second.
interval("2:00:01.333")
days()
113
StreamBase References
returns (timestamp) 7201.333, the number of seconds in the specification of two hours plus one and a
third seconds.
Back to Top ^ Back to Timestamp Overview ^
isinterval()
Function syntax:
bool isinterval(timestamp ts)
Returns true if the argument ts is an interval timestamp. See Simple Functions: Timestamp Overview for a
discussion of interval versus absolute timestamp types.
Back to Top ^ Back to Timestamp Overview ^
milliseconds()
Function syntax:
timestamp milliseconds(int x)
timestamp milliseconds(double x)
Returns an interval timestamp representing an interval of x milliseconds.
Use this function in conjunction with epoch() to convert a tuple field value representing the number of
milliseconds since the epoch to an absolute timestamp. See epoch().
Back to Top ^ Back to Timestamp Overview ^
minutes()
Function syntax:
timestamp minutes(int x)
timestamp minutes(double x)
Returns an interval timestamp representing an interval of x minutes.
Back to Top ^ Back to Timestamp Overview ^
seconds()
Function syntax:
timestamp seconds(int x)
timestamp seconds(double x)
Returns an interval timestamp representing an interval of x seconds.
interval()
114
StreamBase References
Use this function in conjunction with epoch() to convert a tuple field value representing the number of
seconds since the epoch to an absolute timestamp. See epoch().
Back to Top ^ Back to Timestamp Overview ^
strpinterval()
Function syntax:
timestamp strpinterval(string timestring, string formatstring)
Parses a string of time interval information and returns an interval timestamp value. The timestring
argument can be any string representation of a time interval, as long as its components are individually
parsable.
You must also specify a formatstring argument to specify how the timestring argument is to be
interpreted. The format string must specify a time format pattern using the following subset of the patterns
defined for the strptime library (part of the Open Group's Single UNIX Specification):
formatstring
Component
Meaning
The milliseconds portion of the seconds field. (This is a StreamBase extension
not found in the strptime library.)
%H
The hour, using a 24-hour clock, 0 to 23.
%M
The minute, from 0 to 59.
%S
The second, from 0 to 59.
Use an exclamation point in the format string to indicate that the remainder of the
!
input string is optional.
For %H, %M, and %S, leading zeros are recognized but not required.
Use this function to read a string representing a time interval in an incoming stream, and still interpret that
string as an interval timestamp. For example, an incoming field, ElapsedTime, might contain a time
interval expressed in following string format:
%f
ElapsedTime = "1, 7, 5.250"
which you know from the data vendor's documentation means one hour and 7 minutes, plus five and a quarter
seconds. In this case, interpret the field ElapsedTime as a StreamBase interval timestamp with an
expression like the following:
strptime(ElapsedTime, "%H, %M, %S.%f")
which returns:
(timestamp) 4025.25
If the ElapsedTime field in the incoming stream intermittently includes the seconds, use an exclamation
point to show that everything after the minutes pattern is optional:
strptime(ElapsedTime, "%H, %M!, %S.%f")
seconds()
115
StreamBase References
Then when a new ElapsedTime value comes through set to "2, 4", it is still interpreted and converted to
an interval timestamp:
(timestamp) 7440.0
See also the strptime(), which performs for absolute timestamps what this function does for interval
timestamps.
Back to Top ^ Back to Timestamp Overview ^
time()
Function syntax:
timestamp time(timestamp ts)
Returns as an interval timestamp the time of day expressed in the argument, ts â that is, the number of
seconds between the start of the day expressed by ts and the moment expressed by ts. Thus, if run at the
same instant, the following expressions return the same result: time(now()) and now() - today().
Back to Top ^ Back to Timestamp Overview ^
timezoneoffset()
timestamp timezoneoffset()
timestamp timezoneoffset(timestamp ts)
Without an argument, returns a signed interval timestamp that expresses in seconds the offset of the local time
zone from UTC. Thus, timezoneoffset() returns as an interval the same value that
format_time(now(), "Z") returns as a string. Because interval timestamps are expressed in seconds,
you can divide the results by 3600 to obtain for display purposes the number of hours in the offset.
The returned time zone offset value is calculated relative to the system time for Windows, and relative to the
system time or to the time zone specified in the TZ environment variable for UNIX. On UNIX, make sure that
the environment from which the sbd process is launched either does not have a TZ variable or that it is
correctly set for the local system's time zone. The TZ environment variable is ignored on Windows.
You can subtract the return of timezoneoffset() from any absolute timestamp value to generate a new
absolute timestamp that represents the same moment in the UTC time zone. For example, now() timezoneoffset() returns the present moment in the UTC time zone, and returns the same result when
run from any time zone.
Because the value returned from timezoneoffset() is signed, you do not need to consider whether to
add or subtract a positive or negative offset value from the timestamp of interest. Always use a subtraction
operation, which insures that negative timezoneoffset() values (that is, those from time zones west of
UTC) are effectively added, while positive values (from time zones east of UTC) are subtracted.
Once you have a timestamp value representing UTC time, you can convert it to a timestamp for another time
zone by adding or subtracting a fixed value representing the offset of the time zone of interest. For example,
the following expression returns the current time for Sydney, Australia for April to October, when Sydney is
on standard time:
strpinterval()
116
StreamBase References
(now() - timezoneoffset()) - hours(10.0)
(For October to April, when Sydney is on daylight savings time, use hours(11.0).)
If you provide an absolute timestamp as an argument, timezoneoffset() returns the UTC offset of the
system's current time zone at the date and time of the specified timestamp. The offset is calculated based only
on the date and time information in the specified timestamp, relative to the system's current time zone (or, on
UNIX, to the zone in TZ). You can use the argument form of timezoneoffset() to determine the UTC
offset for future or historical dates.
For example, the following commands show that on the US East Coast, the UTC offset changed at 2:00 AM
on March 8, 2009, when daylight savings time began.
sbd --eval "timezoneoffset(timestamp('2009-03-08 01:59:59'))/3600"
timestamp (-5.0)
sbd --eval "timezoneoffset(timestamp('2009-03-08 02:00:00'))/3600"
timestamp (-4.0)
sbd --eval "timezoneoffset(timestamp('2009-03-08 03:00:00'))/3600"
timestamp (-4.0)
(Actually, at 2:00 AM clocks were turned ahead one hour to 3:00 AM, but timezoneoffset() correctly
calculates the UTC offset for both 2:00 and 3:00 AM.)
Back to Top ^ Back to Timestamp Overview ^
weeks()
Function syntax:
timestamp weeks(int x)
timestamp weeks(double x)
Returns an interval timestamp representing an interval of x weeks.
Back to Top ^ Back to Timestamp Overview ^
Timestamp Functions: Timestamp Fields
This category includes the following functions, used to get and set individual fields in absolute timestamps:
get_millisecond()
get_second()
get_minute()
get_hour()
get_day_of_week()
get_day_of_month()
get_month()
get_year()
timezoneoffset()
â
to_milliseconds()
set_second()
to_seconds()
set_minute()
set_hour()
set_day_of_week()
set_day_of_month()
set_month()
set_year()
117
StreamBase References
get_millisecond()
Function syntax:
double get_millisecond(timestamp ts)
Returns the milliseconds portion of the absolute timestamp ts. The returned value is a double, and includes
only the fractional value of the milliseconds of the current second.
Back to Top ^ Back to Timestamp Overview ^
get_second()
Function syntax:
double get_second(timestamp ts)
Returns the seconds portion of the absolute timestamp ts. The returned value is a double, and includes a
fractional value in milliseconds.
Back to Top ^ Back to Timestamp Overview ^
get_minute()
Function syntax:
int get_minute(timestamp ts)
Returns the minutes portion of the absolute timestamp ts.
Back to Top ^ Back to Timestamp Overview ^
get_hour()
Function syntax:
int get_hour(timestamp ts)
Returns the hours portion of the absolute timestamp ts.
Back to Top ^ Back to Timestamp Overview ^
get_day_of_week()
Function syntax:
int get_day_of_week(timestamp ts)
Returns an integer representing the day of the week in the absolute timestamp ts. The returned value is
between 0 (Sunday) and 6 (Saturday).
get_millisecond()
118
StreamBase References
Back to Top ^ Back to Timestamp Overview ^
get_day_of_month()
Function syntax:
int get_day_of_month(timestamp ts)
Returns an integer representing the day of the month in the absolute timestamp ts. The returned value is
between 1 and 31.
Back to Top ^ Back to Timestamp Overview ^
get_month()
Function syntax:
int get_month(timestamp ts)
Returns an integer representing the month in the absolute timestamp ts. The returned value is between 1
(January) and 12 (December).
Back to Top ^ Back to Timestamp Overview ^
get_year()
Function syntax:
int get_year(timestamp ts)
Returns the year portion of the absolute timestamp x.
Back to Top ^ Back to Timestamp Overview ^
set_second()
Function syntax:
timestamp set_second(timestamp ts, int x)
timestamp set_second(timestamp ts, long x)
timestamp set_second(timestamp ts, double x)
Returns a modified version of the absolute timestamp ts, with the seconds component replaced with x. If you
supply an int or long value for x, the milliseconds portion of x is set to 000. If you supply a double value, you
can replace the seconds component down to the millisecond.
Back to Top ^ Back to Timestamp Overview ^
get_day_of_week()
119
StreamBase References
set_minute()
Function syntax:
timestamp set_minute(timestamp ts, int x)
Returns a modified version of the absolute timestamp ts, with the minutes component replaced with x.
Back to Top ^ Back to Timestamp Overview ^
set_hour()
Function syntax:
timestamp set_hour(timestamp ts, int x)
Returns a modified version of the absolute timestamp ts, with the hours component replaced with x.
Back to Top ^ Back to Timestamp Overview ^
set_day_of_week()
Function syntax:
timestamp set_day_of_week(timestamp ts, int x)
Returns a new timestamp that has the same value as absolute timestamp ts, but with the day of the week
component replaced with the value of x. Days of the week are numbered from 0 to 6, Sunday through
Saturday. Day 7 is also considered to be Sunday.
Back to Top ^ Back to Timestamp Overview ^
set_day_of_month()
Function syntax:
timestamp set_day_of_month(timestamp ts, int x)
Returns a modified version of the absolute timestamp ts, with the day of month component replaced with x.
Back to Top ^ Back to Timestamp Overview ^
set_month()
Function syntax:
timestamp set_month(timestamp ts, int x)
Returns a modified version of the absolute timestamp ts, with the month component replaced with x.
set_minute()
120
StreamBase References
Back to Top ^ Back to Timestamp Overview ^
set_year()
Function syntax:
timestamp set_year(timestamp ts, int x)
Returns a modified version of the absolute timestamp ts, with the year component replaced with x.
Back to Top ^ Back to Timestamp Overview ^
to_milliseconds()
Function syntax:
long to_milliseconds(timestamp ts)
Converts an interval or absolute timestamp to a long value representing milliseconds. This function is similar
to to_seconds(), but is more precise and faster. If the argument ts is an interval, returns the number of
milliseconds in the interval. For example, to_milliseconds(now() - today()) returns the number
of milliseconds since midnight.
If the argument ts is an absolute time, returns the number of milliseconds since the epoch, Jan 1, 1970. For
example, to_milliseconds(timestamp("2007-11-29 17:32")) returns 1196375520000.
Back to Top ^ Back to Timestamp Overview ^
to_seconds()
Function syntax:
double to_seconds(timestamp ts)
Converts an interval or absolute timestamp to a double in seconds. If the argument ts is an interval, returns
the number of seconds in the interval. For example, to_seconds(now() - today()) returns the
number of seconds since midnight.
If the argument ts is an absolute time, returns the number of seconds since the epoch, Jan 1, 1970. For
example, to_seconds(timestamp("2007-11-29 17:32")) returns 1.19637552E9.
Back to Top ^ Back to Timestamp Overview ^
Simple Functions: Type Conversions
This category includes the following functions:
blob()
set_month()
bool()
double()
121
StreamBase References
int()
list()
long()
named schema constructor function string() timestamp()
tuple()
blob()
Function syntax:
blob blob(string arg)
blob blob()
Converts arg to a value of type blob where arg is a string. Returns a blob representation of the string. With
no argument, returns a null blob as if you had used blob(null).
Back to Top ^
For additional conversion functions involving blobs, see Simple Functions: BSON.
bool()
Function syntax:
bool
bool
bool
bool
bool
bool
bool
bool(bool arg)
bool(double arg)
bool(int arg)
bool(long arg)
bool(string arg)
bool(blob arg)
bool()
Converts arg to a value of type bool where arg is a bool, double, int, long, or string.
• An int argument of 0 returns the Boolean false. All other int values, positive or negative, return
true.
• A double argument of 0 returns the Boolean false. All other double values, positive or negative,
return true.
• A string argument false returns a Boolean false and the string true returns Boolean true. The
string is compared in a case-insensitive manner. For example, bool("FALSE") and
bool("false") are equivalent. Any string other than false or true is an error.
• A blob argument returns the content of a BSON blob containing a bool
• A bool value returns itself.
• With no argument, returns a null bool as if you had used bool(null).
Back to Top ^
double()
Function syntax:
double
double
double
double
double(bool arg)
double(double arg)
double(int arg)
double(long arg)
Simple Functions: Type Conversions
122
StreamBase References
double double(string arg)
double double(blob arg)
double double()
Converts arg to a value of type double where arg is a bool, double, int, long, or string.
• A bool argument returns 1.0 if true, or 0.0 if false.
• A double argument returns itself.
• An int argument returns the same value converted to type double. For example, double(3) returns
3.0.
• A long argument returns the same value converted to type double. For example, double(15L) returns
15.0.
• A string argument is parsed as a decimal number. For example, double("123.456") returns
123.456, but double("7abc") returns an error. Scientific notation is supported, so
double("1.2E4") returns 12000.0.
• A blob argument returns the content of a BSON blob containing a double
• With no argument, returns a null double as if you had used double(null).
Also See: The to_seconds() function, used to convert timestamps to double.
Back to Top ^
int()
Function syntax:
int
int
int
int
int
int
int
int(bool arg)
int(double arg)
int(int arg)
int(long arg)
int(string arg)
int(blob arg)
int()
Converts arg to a value of type int where arg is a bool, double, int, long, or string.
• A bool argument returns 1 if true, or 0 if false.
• A double argument has its fractional part truncated. For example, int(3.4) returns 3.
• An int argument returns itself.
• A long argument returns the int same as a long value. For example, int(150L) returns 150.
• A string argument is parsed as a decimal number. For example, int("123") returns 123, but
int("7abc") is an error.
• A blob argument returns the content of a BSON blob containing an int
• With no argument, returns a null int as if you had used int(null).
Back to Top ^
list()
Function syntax:
list list(e1, e2, e3, ...)
double()
123
StreamBase References
Returns a list containing each of the specified elements e1, e2, and so on, where each specified element is of
the same data type. The specified elements can be literals or expressions, as long as each resolves to (or can be
coerced to) the same data type. You can create a list of any StreamBase data type.
Use emptylist() to return an empty list, and use nulllist() to return a null list. (See Null Lists for a discussion of
null lists compared to empty lists.)
Back to Top ^
long()
Function syntax:
long
long
long
long
long
long
long(bool arg)
long(double arg)
long(int arg)
long(long arg)
long(blob arg)
long()
Converts expression arg to a value of type long where arg evaluates to a bool, double, int, or long.
• An int argument returns the same value, but with type long.
• A double argument has its fractional part truncated, and the remainder returned with type long.
• A bool argument returns 1 if true, or 0 if false.
• A blob argument returns the content of a BSON blob containing a long
• A long value returns itself.
• With no argument, returns a null long as if you had used long(null).
Back to Top ^
Named Schema Constructor Function
Function syntax:
tuple schema_name(fieldspec [, fieldspec2...]) [as tuplename]
For every named schema you define or import into a module, StreamBase automatically generates a new
function in the StreamBase expression language that allows you to construct tuples with that schema. The
generated function's name is the name of the named schema, and it takes one or more comma-separated
expressions as value arguments. The result is a single tuple with the same schema as the named schema.
For example, for the named schema point, whose schema is (x double, y double), you can use a
function named point() anywhere in the module that defines the named schema:
point(32.0, 44.5)
point(32.0 as x, 44.5 as y)
In StreamSQL, a final AS keyword is required to name the resulting tuple:
list()
124
StreamBase References
point(32.0, 44.5) AS p2
point(32.0 as x, 44.5 as y) AS p2
You can specify the list of fieldspec field specifications in two ways:
• By position
• By name
The following examples presume a named schema with the name Quotes, having the following schema:
(Symbol string, Price double, NumShares int)
When specifying by position, you do not need to specify AS keywords and field names, but you must specify
all fields in schema order. For example:
Quotes("IBM", 132.42, 5000)
When specifying by name, you must use the AS keyword to specify field names, which must exactly match
the spelling of the named schema's fields. Any fields you do not specify are automatically filled with nulls:
Quotes("IBM" as Symbol, 132.42 as Price)
When specifying by name, you can specify fields in any order:
Quotes(132.42 as Price, "IBM" as Symbol)
You cannot mix field specifications with and without the AS keyword.
Specifying fields by name provides flexibility when you use the same named schema in several places in a
large application. If you later edit the named schema itself to add a new field, you do not need to add the new
field everywhere the schema is used. If the fields are specified by name in all locations, the new field does not
cause an error condition, and is automatically filled with null.
Use the name of a named schema with no arguments to construct a null tuple (which is not the same as a tuple
whose fields are all null). For example: point(), Quotes()
Avoid naming a schema the same as an existing expression language function. If you do, the generated
constructor function would mask and prevent the use of the same-named built-in function. See Named
Schema Name Collisions.
Use the * AS * syntax for tuples defined with a named schema to copy the entire tuple into a single field of
type tuple.
For example, let's say the tuple arriving at the input port of a Map operator was defined upstream with the
NYSE_FeedSchema named schema. To preserve the input tuple unmodified for separate processing, the
Map operator could add a field of type tuple using settings like the following in the Additional Expressions
grid. When using the * AS * syntax in the Expression column, the name of the tuple field in the Field Name
column has an implied asterisk for all of its fields.
Named Schema Constructor Function
125
StreamBase References
Action Field Name
Expression
Add
OriginalOrder NYSE_FeedSchema(input1.* as *)
Because the Map operator has only one input port, the port does not need to be named:
Action Field Name
Expression
Add
OriginalOrder NYSE_FeedSchema(* as *)
string()
Function syntax:
string
string
string
string
string
string
string
string
string(blob arg)
string(bool arg)
string(double arg)
string(int arg)
string(long arg)
string(string arg)
string(timestamp arg)
string()
Converts arg to a value of type string where arg is a blob, bool, double, int, long, string, or timestamp.
• An int, double or long argument returns the string representation of arg.
• A string argument returns itself.
• A bool argument returns the string true if true, or false if false.
• A timestamp argument, if represented as a date and time, returns a string that includes the explicit
time zone. A timestamp represented as a numeric value returns the string representation of that value.
• A blob argument returns the string representation of the blob.
• With no argument, returns a null string as if you had used string(null).
Back to Top ^
timestamp()
Function syntax:
timestamp timestamp(string timestring)
timestamp timestamp()
Returns an absolute timestamp parsed from the argument timestring, a string representation of a date with
optional time. With no argument, returns a null timestamp as if you had used timestamp(null).
The timestring argument must be in the form of a time format pattern as defined in the
java.text.SimpleDateFormat class described in the Sun Java Platform SE reference documentation.
See the format_time() function for a summary of the time format pattern strings.
You can specify only the date portion:
timestamp("2009-02-12")
If you specify any part of the time value, you must specify at least the hours and minutes:
string()
126
StreamBase References
timestamp("2009-02-12 14:28") or timestamp("2009-02-12 14:28:05.250")
You can also specify the entire SimpleDateFormat string, including time zone specification:
timestamp("2009-02-12 14:28:05.250-0800")
See also the strptime() and parse_time() functions, used to convert strings to timestamps.
Back to Top ^
tuple()
Function syntax:
tuple tuple(value as fieldname [, value2 as fieldname2 [,...]]) [as tuplename]
tuple tuple()
Takes one or more comma-separated value expressions as arguments, each field named with the AS keyword.
The result is a single tuple with the specified contents. For example:
tuple(126.50 as price, "IBM" as symbol)
In StreamSQL, you must specify a name for the resulting tuple with a final AS keyword:
tuple(126.50 as price, "IBM" as symbol) as tick1;
When using tuple() to create individual tuples, to be compliant with a particular schema, you must specify all
fields in the schema's field order. The tuple() function has no knowledge of the schema you are trying to
match. For these reasons, StreamBase Systems recommends using named schemas and the named schema
constructor function.
You can duplicate any tuple field into another field of type tuple without using wildcards. For example, a Map
operator might have an entry like the following in its Additional Expressions grid, where both
IncomingTuple and CopyOfIncomingTuple are the names of tuple fields:
Action
Field Name
Expression
Add
CopyOfIncomingTuple IncomingTuple
Use the .* syntax to flatten a tuple field into the top level of a stream.
For example, a Map operator might define an entry like the following in its Additional Expressions grid.
When using this syntax, you must have an asterisk in both Field Name and Expression columns.
Action Field Name
Expression
Add
*
IncomingTuple.*
Back to Top ^
timestamp()
127
StreamBase References
Simple Functions: Utilities
This category includes the following functions:
coalesce()
hash()
new_tuple()
notnull()
random_tuple()
coalesce_tuples()
isnull()
new_tuple_subset()
nullif()
tojson()
eval()
length()
new_tuple_subset_loose()
parsejson()
coalesce()
Function syntax:
T coalesce(T arg1, ..., T argn)
Returns the first non-null argument, or a null value if all arguments are null. Accepts all data types, but all
arguments must have the same type. The returned value has the same data type as the arguments. For tuple
arguments, returns the first tuple that is non-null. This function stops evaluating arguments after the first
non-null argument is detected.
Since literal values are never null, you can specify a literal value as the last argument to provide an effective
default value for the list. In this way, coalesce() can be used to emulate the NVL() function provided by
Oracle PL/SQL and the two-argument ISNULL() function provided by Microsoft T/SQL. For example, the
following expression returns the value of fieldA if it is non-null, or 0 if it is null:
coalesce(fieldA, 0)
The following example returns the first non-null field among fieldA, fieldB, and fieldC in that order,
or returns -99999 if all three fields are null:
coalesce(fieldA, fieldB, fieldC, -99999)
Back to Top ^
coalesce_tuples()
Function syntax:
T coalesce_tuples(T arg1, ..., T argn)
For non-hierarchical data types, coalesce_tuples() acts the same as the coalesce() function. For hierarchical
types, this function coalesces each sub-field, recursing into further nested fields as necessary.
For example, the following function:
coalesce_tuples(
tuple(double() AS x, 1.2 AS y, double() AS z),
tuple(1.0 AS x, 1.3 AS y, double() AS z),
tuple(double() AS x, double() AS y, 1.4 AS z)
Simple Functions: Utilities
128
StreamBase References
)
returns the following tuple:
((x double, y double, z double)) 1.0, 1.2, 1.4
Remember that double() evaluates to double(null). Thus, the coalesce_tuples function in this example
selected:
• The first non-null value for x, 1.0, which was found in the second input tuple.
• The first non-null value for y, 1.2, which was found in the first input tuple.
• The first non-null value for z, 1.4, which was found in the third input tuple.
Back to Top ^
eval()
Function syntax:
T eval(string expr, T typespec)
T eval(string expr, tuple varfields, T typespec [, int cachesize])
Evaluates the expression provided as the first argument and returns the result, whose data type is provided in
the typespec argument. The expression must resolve to the data type specified as typespec; the function
does not coerce the return's type.
The typespec argument is evaluated only for its data type, and its value is ignored. You can specify literal
values, as long as their data type is unambiguous (1, 1L, 1.0, "string", and so on), or specify the null value
function for the expected data type (int(), long(), double(), string(), and so on), or provide an expression that
unambiguously resolves to a value with the expected data type.
For the two-argument form, the expr argument is a simple StreamBase expression that does not depend on
any variables for its resolution. For the three-argument form, the expr argument can reference fields in the
second argument's tuple.
The function returns an evaluation exception under the following circumstances:
• If you provide a typespec argument with a different data type than actually returned from the first
argument's evaluation.
• The expression in the expr argument fails to pass typechecking or resolves to null.
• In the three-argument form, you provide a null tuple for the second argument.
In any expression field, you can, of course, enter any expression to be evaluated without using eval(). The
eval() function provides a way for you to build an expression string dynamically or have it based on input:
eval(input.exprfield, int())
The three-argument form can be used to pass an entire input tuple or table row for evaluation against an
expression:
eval("price > 200.00", input, bool())
coalesce_tuples()
129
StreamBase References
eval("remainingQuantity == 0", current, bool())
The expression in the expr argument is evaluated in a self-contained environment. Anything the expression
needs for its evaluation must be passed in by means of the varfields argument. For example, to reference
a constant or dynamic variable in the expr argument, make sure that constant or dynamic variable is included
in the input tuple. Let's say a module defines the constant discount, and has a dynamic variable named
curr_rate. You want to multiply field price in the input tuple by both values. Use the tuple() function to
create a tuple consisting of the entire input tuple, plus the constant and variable:
eval("input.price * discount * curr_rate", tuple(input.* as *, discount,
curr_rate), double())
The optional fourth argument is an advanced setting that specifies the size of the evaluation cache in number
of unique, saved, compiled evaluations. In the absence of this argument, the evaluation cache is unlimited.
This argument must be in the fourth position; to use it with the two-argument form of this function, add an
empty tuple second argument.
This function is not expected to work at the command prompt with sbd --eval.
Back to Top ^
hash()
Function syntax:
int hash(T arg)
Returns a hashed integer value derived from the argument, which can be any StreamBase data type.
Back to Top ^
isnull()
Function syntax:
bool isnull(T value)
Returns true if the argument is a null value. Accepts all data types.
For list and tuple arguments, isnull() returns true if and only if the top-level list or tuple is null. If a list
contains any elements at all, even if all their values are null, it is not a null list. If a tuple contains any fields at
all, it is not null even if all field values are null.
Back to Top ^
length()
Function syntax:
int length(blob x)
int length(list L)
eval()
130
StreamBase References
int length(string x)
Returns the length of its argument for argument types blob, list, and string. For a blob, returns a count of
bytes. For a non-null list, returns the number of elements in the list, including any null elements. For a string,
returns the number of graphemes in the string, for ASCII and all supported Unicode character sets.
If the argument is a null blob, null list, or null string, the returned value is null.
Back to Top ^
new_tuple()
Function syntax:
tuple new_tuple(tuple t [, updated_value1 AS field1_name [,
updated_value2 AS field2_name [, ... [,
updated_valueN AS fieldN_name]]]])
Use the new_tuple() function to modify the values of a small number of fields in a tuple, leaving the other
fields unchanged.
The required first argument t is a tuple value such as a named schema or the name of a tuple field in the
incoming stream. Use one or more field update arguments of the form value AS field_name. You can
use input.* AS * to fill in the fields in t with input stream fields that have matching field names.
You do not need to specify all fields in t, but you cannot specify fields not in t.
The following example both defines a tuple and immediately replaces the value of its x field. This example is
impractical but can illustrate new_tuple() using sbd --eval:
new_tuple(tuple(1.0 AS x, 2.0 AS y, 3.0 AS z), 5 AS x)
For a more practical example, an input stream may have a schema defined as (Symbol string, Price
double, NumSh double). The following expression in a Map operator's Additional Expressions grid
inflates the incoming value of the Price field by 10%:
Action Field Name
Expression
Add
InflatedInput new_tuple(input, input.Price*1.10 as Price)
Back to Top ^
new_tuple_subset()
Function syntax:
tuple new_tuple_subset(tuple t, value1 AS field1_name[,
value2 AS field2_name[, ... [,
valueN AS fieldN_name]]])
This function returns a tuple with the schema of the tuple argument t, and with the specified new field values
substituted.
length()
131
StreamBase References
The required first argument t is a tuple value such as a named schema or the name of a tuple field in the
incoming stream. Use one or more field update arguments of the form value AS field_name. You can
use input.* AS * to fill in the fields in t with input stream fields that have matching field names.
Unlike new_tuple(), this function allows but ignores any update field names not in tuple t.
Unlike new_tuple(), this function requires all field names in t to be specified.
Let's say an input stream has a schema defined as (Symbol string, Price double, NumSh
double, CustID int), while the named schema Trade has a subset of that schema: (Symbol
string, Price double, NumSh double). The following expression in a Map operator's Additional
Expressions grid accepts the four-field input tuple and extracts only the three-field trade basics into a new
field named TradeOnly.
Action
Add
Field Name
TradeOnly
Expression
new_tuple_subset(Trade(),
input.* AS *)
Back to Top ^
new_tuple_subset_loose()
Function syntax:
tuple new_tuple_subset_loose(tuple t, updated_value1 AS field1_name[,
updated_value2 AS field2_name[, ... [,
updated_valueN AS fieldN_name]]])
This function returns a tuple with the schema of the tuple argument t, and with the specified new field values
substituted.
The required first argument t is a tuple value such as a named schema or the name of a tuple field in the
incoming stream. Use one or more field update arguments of the form value AS field_name. You can
use input.* AS * to fill in the fields in t with input stream fields that have matching field names.
Unlike new_tuple(), this function allows but ignores any update field names not in tuple t.
Like new_tuple(), this function does not require all field names in t to be specified.
This function is especially useful when using a named schema to specify a declared output stream schema. In
a Map operator immediately upstream of the output stream, use this function to reconcile a varying set of
input fields to the output stream's declared schema. If the output stream's declared schema is named
TargetSchema, use an Additional Expressions grid like the following:
Action Field Name
Expression
Add
TempTuple new_tuple_subset_loose(TargetSchema(), input.* AS *)
Then add a second Map to expand TempTuple's fields back to the top level:
Action Field Name Expression
Add
*
TempTuple.*
As an alternative, you can collapse both Map operators into one that uses the following:
new_tuple_subset()
132
StreamBase References
Action Field Name
Expression
Add
*
new_tuple_subset_loose(TargetSchema(), input.* AS *).*
This setup allows you to change the definition of TargetSchema elsewhere in a large application without
having to also change the preceding Map operator.
Back to Top ^
notnull()
Function syntax:
bool notnull(T value)
Returns true if the argument is not a null value. Accepts all data types.
This function always returns the opposite of isnull().
Back to Top ^
nullif()
Function syntax:
T nullif(T arg1, T arg2)
Takes two arguments of any type (the same type for both). If the resolved value of both arguments is the
same, returns null. If the resolved value of the two arguments differs, returns the value of the first argument.
This function can be used to evaluate fields before and after an event, and to send a field upstream only if it
has changed, otherwise null.
Back to Top ^
parsejson()
Function syntax:
tuple parsejson(tuple tuplespec, string json-string)
Accepts a JSON-formatted string, in either JSON object or JSON array format (as defined on
http://www.json.org) and returns a tuple. The first argument, tuplespec, is a specification for the returned
tuple's schema, in the form of a named schema constructor function, or the tuple() function, or an expression
that resolves to a schema definition.
For example, for the named schema point(), defined as (int x, int y), the following expressions both
return the tuple (x: 88, y: 99).
parsejson(point(), "[88, 99]")
parsejson(point(), "{x:88, y:99}")
Back to Top ^
new_tuple_subset_loose()
133
StreamBase References
random_tuple()
Function syntax:
tuple random_tuple(schema-definition)
Given a schema definition, usually in the form of a named schema constructor function, returns a tuple with
each field filled with random data of the correct data type for each field. For example, for the named schema,
point, with schema (double x, double y, double z), the named schema constructor function
point() creates a single tuple with that schema. Use point() as the schema definition argument for
random_tuple():
random_tuple(point())
This returns three double values selected at random, any of which might be null. Numeric values returned can
be fractional or negative. Each time this function is run, another three random values are returned.
You can also use random_tuple() using tuple() to define a schema. In this case, you must provide value
arguments and field names, as in the following example:
random_tuple(tuple(132.34 as price, "IBM" as symb, now() as tdate))
This at first appears to be a contradiction, because you provide values to fields that you then ask
random_tuple() to replace with new, random values. However, in this context, the values you provide to
tuple() are evaluated by random_tuple() only to determine the data type for each field. For this example,
random_tuple() returns three random fields of type double, string, and timestamp.
Back to Top ^
tojson()
Function syntax:
string tojson(tuple fieldname [, bool verbosity])
Accepts a tuple argument and returns the tuple's field values as a JSON object of key-value pairs, or
optionally as a JSON array of field values. The argument fieldname is likely to be a field of type tuple in
the incoming stream, but can be any expression that resolves to a single tuple.
By default, or with the optional verbosity argument expressed as true, the input tuple's field and value
pairs are returned as a string formatted as a JSON object, as defined on http://www.json.org: a left brace
followed by colon-separated name-value pairs (with field name quoted), and each pair separated by a comma,
followed by a closing right brace.
Set the second argument to false to return a JSON array of field values instead: a left bracket following by
comma-separated field values, followed by a closing right bracket.
For example, let's say an incoming tuple field named trade has the following schema and values:
Field
Data Type
random_tuple()
Value
134
StreamBase References
A
B
C
double
int
string
2.0
333
"IBM"
range(0, 8, 2) = [0, 2,
D
list(int)
4, 6]
In this case, the expressions tojson(trade) and tojson(trade, true) return the following string:
{"A":2.0,"B":333,"C":"IBM","D":[0,2,4,6]}
To test this function at the command prompt with sbd --eval, use a construction like the following:
sbd --eval "tojson(tuple(2.0 as A, 333 as B, 'IBM' as C, range(0, 8, 2) as D))"
The expression tojson(trade, false) returns the following string:
[2.0,333,"IBM",[0,2,4,6]]
Back to Top ^
Aggregate Functions Overview
Aggregate functions are used on sets of data to return a single result. Aggregate functions evaluate columns of
data from windows or tables. In EventFlow applications, aggregate functions can only be used:
• In Aggregate operators, in aggregate expressions that apply to an aggregate window.
• In Query operators that perform Read or Delete operations, in expressions that apply to all rows read.
• In Query operators that perform Read or Delete operations, in aggregate expressions used in
conjunction with a Group-By field.
In StreamSQL applications, aggregate functions can be used in SELECT statements related to aggregate or
query read operations.
Expressions in aggregate contexts can contain a single aggregate function, or they can combine multiple
aggregate functions together with constants and fields from an input stream or an associated Query Table.
Aggregate expressions can include simple functions if the value of the simple function does not change over
the lifetime of the Aggregate window.
Aggregate functions are organized into the following categories:
Aggregate Functions: Aggregate to List
Aggregate Functions: External Functions
Aggregate Functions: Statistical Calculations
Aggregate Functions: Windowing
Aggregate Functions: Aggregate to List
This category includes the following functions:
tojson()
135
StreamBase References
aggregatelist()
concat()
aggregatelist()
Function syntax:
list(T) aggregatelist(T e)
Returns a list containing one element for each expression, e, in the Aggregate's window. The list element
type, T, of the returned list is the same as the data type of e.
Back to Top ^ Back to Aggregate Overview ^
concat()
Function syntax:
list(T) concat(list(T) L)
Returns a list containing the elements of each list, L, in the Aggregate's window. The list element type, T, of
the returned list is the same as the element type of the argument list.
See also the concat() function for list elements.
Back to Top ^ Back to Aggregate Overview ^
Aggregate Functions: External Functions
This category includes the following functions:
callcpp()
calljava()
callcpp()
Function syntax:
T callcpp(string class [, arg1, ..., argn])
As an alternative to using callcpp(), you can define an alias for your custom functions. See Using
Function Aliases.
Use an alias or callcpp() to run a custom C++ aggregate function directly from a StreamBase operator
that uses an expression. The return type, T, of callcpp() is the same as the return type of the called
function. Custom C++ aggregate functions are functions you build with the StreamBase C++ Client API,
specifically those that inherit from the sb::PluginAggregate class. You can use the aggregate form of
callcpp() in any aggregate expression. (To use callcpp() in simple expressions, refer to the simple
callcpp().)
Aggregate Functions: Aggregate to List
136
StreamBase References
For callcpp() to locate the function being called, you must specify the location of the containing DLL or
.so file, and must register the function with a custom-function element in the StreamBase Server
configuration file. You specify the function as an aggregate function by means of the type attribute of
custom-function. See C++ Function Overview for details.
To learn about coding custom C++ functions, refer to Creating Custom C++ Functions in the API Guide.
Back to Top ^ Back to Aggregate Overview ^
calljava()
Function syntax:
T calljava(string class [, arg1, ..., argn])
As an alternative to using calljava(), you can define an alias for your custom functions. See Using
Function Aliases.
Use an alias or calljava() to run a custom Java aggregate function directly from a StreamBase operator
that uses an expression. The return type, T, of calljava() is the same as the return type of the called
function. Custom Java aggregate functions are functions you build with the StreamBase Java Client library,
specifically those that extend the AggregateWindow class. You can use the aggregate form of
calljava() in any aggregate expression. (To use calljava() in simple expressions, refer to the simple
calljava().)
The calljava() function distinguishes simple from aggregate functions by the number of arguments. For
custom simple functions, you must specify both class and method names. For custom aggregate functions, you
specify only the class name, because these functions must inherit from AggregateWindow, which has an
init() method that is automatically run.
To learn about coding custom Java functions, refer to Using the StreamBase Java Function Wizard in the API
Guide. For information on the classpath requirements for custom Java functions, see Java Function Overview.
See Return Types and Argument Types for a discussion of using Java primitives or Java objects in the
function you write to be called with calljava().
Back to Top ^ Back to Aggregate Overview ^
Aggregate Functions: Statistical Calculations
This category includes the following functions:
alpha()
correlation_coefficientp()
exp_moving_avg()
min()
stdev()
vwap()
callcpp()
andall()
count_distinct()
intercept()
minn()
stdevp()
withmax()
avg()
count()
max()
orall()
sum()
withmin()
beta()
covariance()
maxn()
product()
variance()
correlation_coefficient()
covariancep()
median()
slope()
variancep()
137
StreamBase References
alpha()
Function syntax:
double alpha(double index, double price, double dividend)
Returns a double that may indicate the part of a stock's movement that is independent of the index's
movement.
Examples of stocks increasing in alpha could be those with takeover rumors, under strong syndicate
manipulation, or having strong expectations of good results; that is, factors that make them increasingly move
independently of the index.
The beta of a stock is defined as the slope of a regression line in a scatter graph of paired data points
representing percentage changes of an index (return of an index) and the corresponding change (return of
stock) in the price of a stock. The StreamBase beta() function also includes the stock dividend in the
calculation of the stock return.
The alpha is the point where this regression line cuts the Y axis. To reiterate, a stock's beta can be described as
that part of a stock's movement that is influenced by the index, while a stock's alpha can be regarded as that
part of a stock's movement that is independent of the index's movement.
The alpha function's arguments are:
1. index: the end-of-period market index (double)
2. price: the end-of-period stock price (double)
3. dividend: the stock dividend of the period (double)
The stock price must have already figured in any stock split (or reverse split). The alpha is usually calculated
over a period of 61 months. This aggregate function assumes that the input data is already normalized. That is,
index, price, and dividend are of the same period. If they are of different periods, the yield (return) should be
normalized first and then the intercept function used to calculate alpha.
Back to Top ^ Back to Aggregate Overview ^
avg()
Function syntax:
double
int
long
timestamp
avg(double field)
avg(int field)
avg(long field)
avg(timestamp field)
Returns the average value of a numeric field, computed for the argument field for all tuples in the
Aggregate's window. The field can be an double, int, long, or timestamp. For a returned average of timestamp
values to make sense, the aggregate field should contain all interval timestamps or all absolute timestamps,
but not both.
See also the avg() function for lists.
alpha()
138
StreamBase References
Back to Top ^ Back to Aggregate Overview ^
andall()
Function syntax:
bool andall(bool f)
The argument f represents a field of type boolean in an Aggregate's window, a Query Table column, or an
expression that depends on one or more fields in an Aggregate's window or Query Table.
This function evaluates the values in the specified field, and returns the results of a logical AND operation on
all values. For example, suppose field BoolField contains the following values in successive rows of an
Aggregate window or Query Table column: true, true, false, true, false. In that case,
andall(BoolField) returns false. Use andall() as an aggregate truth detector function.
Null arguments have special handling. A null argument does not change the result of the evaluation if a
false value is among the arguments. Thus, if BoolField contains null, true, false, null,
true, then andall(BoolField) still returns false. However, if one or more arguments is null while
all other arguments are true, the function returns null. So if BoolField contains null, true,
true, null, true, then andall(BoolField) returns null.
The andall() function follows the logic expressed in this statement:
if any argument is false, return false
else if any argument is null, return null
else return true
See also the orall() aggregate function and the simple versions of andall() and orall().
Back to Top ^
beta()
Function syntax:
double beta(double index, double price, double dividend)
Returns a double that may indicate the tendency of a security's returns to respond to swings in the market. A
beta of 1 indicates that the security's price will move with the market. A beta of less than 1 means that the
security will be less volatile than the market. A beta value that is greater than 1 indicates that the security's
price will be more volatile than the market.
For related information, see the description of the alpha function.
Beta is a measure of a security's or portfolio's volatility, or systematic risk, in comparison to the market as a
whole. For example, if a stock's beta is 1.2, it is theoretically 20% more volatile than the market.
The function's arguments are:
1. index: the end-of-period market index (double)
avg()
139
StreamBase References
2. price: the end-of-period stock price (double)
3. dividend: the stock dividend of the period (double)
The stock price must have already figured in any stock split (or reverse split). The beta is usually calculated
over a period of 61 months. This aggregate function assumes that the input data is already normalized. That is,
index, price, and dividend are of the same period. If they are of different periods, the yield should be
normalized first and then use the slope function to calculate beta.
Back to Top ^ Back to Aggregate Overview ^
correlation_coefficient()
Function syntax:
double correlation_coefficient(double price, double index)
double correlation_coefficient(int price, int index)
Returns the correlation coefficient for two fields, price and index, for all tuples in the Aggregate's
window. This function takes two input arguments (both can be an int or a double) and returns a double. The
correlations coefficient is a measure that determines the degree to which two variable's movements are
associated. The correlation coefficient will vary from -1.0 to 1.0. The value -1.0 indicates perfect
negative correlation, and 1.0 indicates perfect positive correlation. 0 means no correlation.
Notes
• The correlation_coefficient of 0 items is null.
• The correlation_coefficient of 1 item is 1.0.
• The correlation_coefficient of N identical items is 1.0.
Back to Top ^ Back to Aggregate Overview ^
correlation_coefficientp()
Function syntax:
double correlation_coefficientp(double price, double index)
double correlation_coefficientp(int price, int index)
Returns the correlation coefficient for two fields, price and index, for all tuples in the Aggregate's
window. The correlation_coefficientp function is similar to the correlation_coefficient
function, but use correlation_coefficientp when the data provided is the entire population, while
the correlation_coefficient function is used for a random sample. The
correlation_coefficientp function is calculated using the biased (or n) method. The
correlation_coefficient function is calculated using the unbiased (or n-1) method.
This function takes two input arguments (both can be an int or a double) and returns a double. The
correlations coefficient is a measure that determines the degree to which two variable's movements are
associated. The correlation coefficient will vary from -1.0 to 1.0. The value -1.0 indicates perfect
negative correlation, and 1.0 indicates perfect positive correlation. 0 means no correlation.
beta()
140
StreamBase References
Notes
• The correlation_coefficientp of 0 items is null.
• The correlation_coefficientp of 1 item is 1.0.
• The correlation_coefficientp of N identical items is 1.0.
Back to Top ^ Back to Aggregate Overview ^
count()
Function syntax:
int count([T expr])
Returns the number of tuples in the Aggregate's window. If this function is called with an argument, then
tuples for which the argument evaluates to null do not contribute to the count. The argument can be of any
data type, T, but its actual value is ignored, other than the fact that it is non-null. If no argument is specified,
then all tuples are included in the count.
To clarify the operation of count(), consider the following sequence of values for x:
x {1,2,3,4,5,6,7,8,9,10}
Calling count(x) returns 10. There are ten items in the list.
Calling count(x > 5) also returns 10. This is because it is counting the sequence {f,f,f,f,f,t,t,t,t,t} (five
false, five true). All elements in this sequence are non-null, so all are counted.
Calling count(if x > 5 then 0 else null) returns 5, because it is counting the sequence {null,
null, null, null, null, 0, 0, 0, 0, 0} (five nulls, five zeros). The five non-null elements are counted. Any
non-null value other than 0 would also count in this expression.
The following example clarifies the count() function's behavior with query tables.
Let's say we have a table named flattop with the following schema and contents:
Contents of Three
Rows
alpha
int
2, 4, 6
beta
long
3.0, 5.0
The expression select count(flattop.*) from in, tablet ... returns
Field Name
Data Type
3, 2
which is the number of non-null values in the alpha field, plus the number of non-null values in the beta
field.
If you want a count of the number of items in the window, use an expression like the following: select
count() as c from in, flattop ...
Notes
141
StreamBase References
Back to Top ^ Back to Aggregate Overview ^
count_distinct()
Function syntax:
int count_distinct(T arg1 [, T arg2 ...]])
Returns the number of tuples in the Aggregate's window with specified values for the parameters. This
function must be called with at least one argument of any data type. Multiple arguments can be of different
types. Use commas to separate subsequent arguments. For the purpose of this function, null values of a field
are considered equivalent to each other.
See also the count_distinct_elements() function for lists.
Back to Top ^ Back to Aggregate Overview ^
covariance()
Function syntax:
double covariance(double price, double index)
double covariance(int price, int index)
double covariance(long price, long index)
Returns the covariance for two fields, price and index, for all tuples in the Aggregate's window. This
function takes two input arguments (both can be a double, int, or long) and returns a double. In financial
applications, covariance can be used to measure the degree to which returns on two risky assets move in
tandem. A positive covariance means that asset returns move together. A negative covariance means returns
vary inversely.
In the arguments, the price field is a stock price, and the index is the industry segment index.
One method of calculating covariance is to look at return deviations from the expected return in each scenario.
Another method is to multiply correlation between the two variables by the standard deviation of each
variable.
For example, if you owned one asset that had a high covariance with another asset that you did not own, then
you would receive very little increased diversification by adding the second asset. Of course, the opposite is
true as well, adding assets with low covariance to your portfolio would lower the overall portfolio risk.
Back to Top ^ Back to Aggregate Overview ^
covariancep()
Function syntax:
double covariancep(double price, double index)
double covariancep(int price, int index)
double covariancep(long price, long index)
count()
142
StreamBase References
Returns the covariance for two fields, price and index, for all tuples in the Aggregate's window. The
covariancep function is similar to the covariance function, but use covariancep when the data
provided is the entire population, while the covariance function is used for a random sample. The
covariancep function is calculated using the biased (or n) method. The covariance function is
calculated using the unbiased (or n-1) method.
This function takes two input arguments (both can be a double, int, or long) and returns a double. In financial
applications, covariance can be used to measure the degree to which returns on two risky assets move in
tandem. A positive covariance means that asset returns move together. A negative covariance means returns
vary inversely.
In the arguments, the price field is a stock price, and the index is the industry segment index.
One method of calculating covariance is by looking at return deviations from the expected return in each
scenario. Another method is to multiply correlation between the two variables by the standard deviation of
each variable.
For example, if you owned one asset that had a high covariance with another asset that you did not own, then
you would receive very little increased diversification by adding the second asset. Of course, the opposite is
true as well, adding assets with low covariance to your portfolio would lower the overall portfolio risk.
Back to Top ^ Back to Aggregate Overview ^
exp_moving_avg()
Function syntax:
double exp_moving_avg(double value, int count [, double weight])
double exp_moving_avg(int value, int count [, double weight])
double exp_moving_avg(long value, int count [, double weight])
Returns a weighted average where a percentage of each successive value is used with a percentage of the
existing average to construct the new average. The effect of any one value on the average diminishes
exponentially as new values are added.
The function takes these arguments:
value
The value (double, int, or long) to be averaged.
count
The integer number of periods over which a simple average is used prior to starting the EMA.
weight
An optional weighting value (a double between 0 and 1) that will be applied to both the current
period's value (CPV) and prior period's average (PPA) when the Exponential Moving Average (EMA)
is calculated.
If the weight is not between 0 and 1 or is not specified, it is calculated from the following formula:
weight = 2 / (count + 1)
covariancep()
143
StreamBase References
This function returns a double. It is most commonly used with an infinite aggregate window size (although it
does not have to be). When configuring an Aggregate operator for an infinite window, do not configure the
Advance and Size fields in StreamBase Studio, which results in infinite window size. Instead, set the Emit
field to 1 so that the aggregate emits for every tuple.
The exp_moving_avg function is calculated using the following formula:
EMA = (CPV * weight) + (PPA * (1 - weight))
• EMA: exponential moving average so far
• PPA: exponential moving average after the previous tuple
• CPV: value of current tuple
Initially there is no PPA. A simple moving average (SMA) is computed instead over as many tuples as
specified by the second parameter. When the SMA is computed, a Null value is emitted for each input tuple
until the Aggregate operator receives enough tuples to compute the SMA. Following this, the EMA is
calculated.
Back to Top ^ Back to Aggregate Overview ^
intercept()
Function syntax:
double intercept(double x, double y)
double intercept(int x, int y)
For the data set of fields x and y for all tuples in the Aggregate's window, a best-fit linear regression line is
calculated, then the function returns the value where the line intersects the y axis. The method used to find the
line that best fits a group of points is called least squares (or linear least squares). This function takes two
input arguments (both can be an int or a double) and returns a double.
Back to Top ^ Back to Aggregate Overview ^
max()
Function syntax:
T max(T f)
The argument f represents a field in an Aggregate's window, a Query Table column, or an expression that
depends on one or more fields in an Aggregate's window or Query Table.
This function returns the maximum non-null value using the greater-than relational operation appropriate for
the data type of f. The data type, T, of the returned value is the same as the argument.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
See also the simple version of max(), the aggregate function maxn() below, and the maxelement() function for
lists. In an aggregate context, this aggregate function max(list) returns the maximum list in the aggregate
exp_moving_avg()
144
StreamBase References
window. Use the simple function max(list, , list) to determine the larger of two or more lists. By
contrast, use maxelement() to compare the element values of a single list.
Back to Top ^ Back to Aggregate Overview ^
maxn()
Function syntax:
list(T) maxn(int count, T f)
The argument f represents a field in an Aggregate's window, a Query Table column, or an expression that
depends on one or more fields in an Aggregate's window or Query Table column.
Returns a list with count elements containing the count number of maximum non-null values for field f in
the Aggregate's window or Query Table column. Accepts fields of all data types and returns a list whose
elements are the same as the type of field f. The value of count must be nonnegative, cannot be null, and
must remain the same for the duration of the Aggregate window. For count=0, an empty Aggregate window,
or an empty Query Table column, an empty list is returned.
Maximum values are determined with the greater-than relational operation appropriate for the data type of f.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
See also the simple version of max(), the aggregate version of max(), and the maxelement() function for lists.
Back to Top ^ Back to Aggregate Overview ^
median()
Function syntax:
double median(double x)
double median(int x)
double median(long x)
Returns the median value of x for this Aggregate's window. If the window has an even number of elements,
returns the average of the middle two.
See also the median() function for lists.
Back to Top ^ Back to Aggregate Overview ^
min()
Function syntax:
T min(T f)
The argument f represents a field in an Aggregate's window, a Query Table column, or an expression that
depends on one or more fields in an Aggregate's window or Query Table.
max()
145
StreamBase References
This function returns the minimum non-null value using the less-than relational operation appropriate for the
data type of f. The data type, T, of the returned value is the same as the argument.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
See also the simple version of min(), the aggregate function minn() below, and the minelement() function for
lists. In an aggregate context, this aggregate function min(list) returns the minimum list in the aggregate
window. Use the simple function min(list, , list) to determine the smaller of two or more lists. By
contrast, use minelement() to compare the element values of a single list.
Back to Top ^ Back to Aggregate Overview ^
minn()
Function syntax:
list(T) minn(int count, T f)
The argument f represents a field in an Aggregate's window, a Query Table column, or an expression that
depends on one or more fields in an Aggregate's window or Query Table column.
Returns a list with count elements containing the count number of minimum non-null values for field f in
the Aggregate's window or Query Table column. Accepts fields of all data types and returns a list whose
elements are the same as the type of field f. The value of count must be nonnegative, cannot be null, and
must remain the same for the duration of the Aggregate window. For count=0, an empty Aggregate window,
or an empty Query Table column, an empty list is returned.
Minimum values are determined with the less-than relational operation appropriate for the data type of f.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
See also the simple version of min(), the aggregate version of min(), and the minelement() function for lists.
Back to Top ^ Back to Aggregate Overview ^
orall()
Function syntax:
bool orall(bool f)
The argument f represents a field of type boolean in an Aggregate's window, a Query Table column, or an
expression that depends on one or more fields in an Aggregate's window or Query Table.
This function evaluates the values in the specified field, and returns the results of a logical OR operation on all
values. For example, suppose field BoolField contains the following values in successive rows of an
Aggregate window or Query Table column: true, true, false, true, false. In that case,
orall(BoolField) returns true. Use orall() as an aggregate falsity detector function.
min()
146
StreamBase References
Null arguments have special handling. A null argument does not change the result of the evaluation if a
true value is among the arguments. Thus, if BoolField contains null, false, true, null,
false, then orall(BoolField) still returns true. However, if one or more arguments is null while
all other arguments are true, the function returns null. So if BoolField contains null, false,
false, null, false, then orall(BoolField) returns null.
The orall() function follows the logic expressed in this statement:
if any argument is true, return true
else if any argument is null, return null
else return false
See also the andall() aggregate function and the simple versions of andall() and orall().
Back to Top ^
product()
Function syntax:
double product(double f)
int
product(int f)
long
product(long f)
Returns the multiplication product computed for field f for all tuples in the Aggregate's window. Supports
data types double, int, and long.
See also the product() function for lists.
Back to Top ^ Back to Aggregate Overview ^
slope()
Function syntax:
double slope(double x, double y)
double slope(int x, int y)
For the data set of fields x and y for all tuples in the Aggregate's window, a best-fit linear regression line is
calculated, and then the function returns the line's slope. The method that is used to find the line that best fits a
group of points is called least squares (or linear least squares). The slope function takes two input
arguments (both can be an int or a double) and returns a double.
Back to Top ^ Back to Aggregate Overview ^
stdev()
Function syntax:
double
double
orall()
stdev(double f)
stdev(int f)
147
StreamBase References
double
stdev(long f)
timestamp stdev(timestamp f)
Returns the standard deviation for field f for all tuples in the Aggregate's window. The function takes one
input argument. If the input argument is an int, double, or long, it returns a double. If the input argument is a
timestamp, it returns an interval timestamp. For timestamp values, the aggregate field should contain all
interval timestamps or all absolute timestamps, but not both.
Standard deviation is a measure of the dispersion of a set of data from its mean. The more spread apart the
data is, the higher the deviation. For example, in financial applications, standard deviation could be applied to
the annual rate of return of an investment to measure the investment's volatility (risk). A volatile stock would
have a high standard deviation. In mutual funds, the standard deviation indicates how much the return on the
fund is deviating from the expected normal returns.
See also the stdev() function for lists.
Back to Top ^ Back to Aggregate Overview ^
stdevp()
Function syntax:
double
double
double
timestamp
stdevp(double f)
stdevp(int f)
stdevp(long f)
stdevp(timestamp f)
Returns the standard deviation for field f for all tuples in the Aggregate's window. The function takes one
input argument. If the input argument is an int, double, or long, it returns a double. If the input argument is a
timestamp, it returns an interval timestamp. For timestamp values, the aggregate field should contain all
interval timestamps or all absolute timestamps, but not both.
The stdevp() function is similar to the stdev() function: with stdevp() the data provided is the entire
population, while with stdev(), the data provided is treated as a random sample. The stdevp() function
is calculated using the biased (or n) method. The stdev() function is calculated using the unbiased (or n-1)
method.
See also the stdevp() function for lists.
Back to Top ^ Back to Aggregate Overview ^
sum()
Function syntax:
double
int
long
timestamp
sum(double f)
sum(int f)
sum(long f)
sum(timestamp f)
Returns the sum of field f computed for all tuples in the Aggregate's window. The field can be an double, int,
long, or timestamp.
stdev()
148
StreamBase References
When the field type is timestamp, summing members of the field follows the rules for adding timestamps as
shown in the table in timestamp Data Type. That is, you cannot sum an aggregate of two or more absolute
timestamps. However, you can sum an aggregate field composed of all interval timestamps, or one composed
of exactly one absolute timestamp plus one or more interval timestamps.
See also the sum() function for lists.
Back to Top ^ Back to Aggregate Overview ^
variance()
Function syntax:
double variance(double f)
double variance(int f)
double variance(long f)
Returns the variance for field f for all tuples in the Aggregate's window. The function takes one input
argument (an int, double, or long) and returns a double.
Variance is a measure of the dispersion of a set of data points around their mean value. It is a mathematical
expectation of the average squared deviations from the mean. Variance measures the variability (volatility)
from an average. Volatility is a measure of risk. So for example, this statistic can help determine the risk an
investor might take on when purchasing a specific security.
See also the variance() function for lists.
Back to Top ^ Back to Aggregate Overview ^
variancep()
Function syntax:
double variancep(double f)
double variancep(int f)
double variancep(long f)
Returns the variance for field f for all tuples in the Aggregate's window. The function takes one input
argument (an int, double, or long) and returns a double.
The variancep() function is similar to the variance() function: with variancep() the data
provided is the entire population, while with variance(), the data provided is treated as a random sample.
The variancep() function is calculated using the biased (or n) method. The variance() function is
calculated using the unbiased (or n-1) method.
See also the variancep() function for lists.
Back to Top ^ Back to Aggregate Overview ^
sum()
149
StreamBase References
vwap()
Function syntax:
double vwap(double price, double volume)
Returns the volume-weighted average-price value from (typically) the price and volume values, for all
tuples in the Aggregate's window. Both arguments are doubles.
Back to Top ^ Back to Aggregate Overview ^
withmax()
Function syntax:
T1 withmax(T compare_expr, T1 result_expr)
Returns the result_expr for this Aggregate's window that has the maximum corresponding
compare_expr using the greater-than relational operator. The data type, T1, of the returned value is the
same as the result_expr. The data type of the compare_expr can be any data type, not necessarily the
same as the result_expr's type.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
Back to Top ^ Back to Aggregate Overview ^
withmin()
Function syntax:
T1 withmin(T compare_expr, T1 result_expr)
Returns the result_expr for this Aggregate's window that has the minimum corresponding
compare_expr using the less-than relational operator. The data type, T1, of the returned value is the same
as the result_expr. The data type of the compare_expr can be any data type, not necessarily the same
as the result_expr's type.
StreamBase data types are comparable with relational operators in different ways, as listed in the entry for
each data type on StreamBase Data Types.
Back to Top ^ Back to Aggregate Overview ^
Aggregate Functions: Windowing
This category includes the following functions:
Function
vwap()
Use in Aggregate Operator?
Use in Query Read on Query
Tables?
150
StreamBase References
closeval()
yes
no
firstn()
yes
yes
firstnonnullval()
yes
yes
firstval()
yes
yes
lag()
yes
yes
lastn()
yes
yes
lastnonnullval()
yes
yes
lastval()
yes
yes
openval()
yes
no
All windowing functions work on columns of data in Aggregate windows, and most windowing functions also
work on table columns returned by Query Read operations on Query Tables.
Note
When used with a Query operator, these functions are specified in the Output Settings tab of the Query
operator's Properties view, and operate on the initial selection of rows from the Query Table as specified in
the Query Settings tab for a Query-Read operation. Remember that the order of rows returned from the Query
Table depends on the Read predicate expression and on the sort order, if specified.
For example, if the Query-Read operation specifies Read All Rows on a table whose primary index is a string
field, and you specify running the firstn() or lastn() functions on that selection, those functions return fields
from the first n rows (or last n rows) in alphabetical order by primary index.
closeval()
Function syntax:
double
int
long
timestamp
closeval([string
closeval([string
closeval([string
closeval([string
dimension])
dimension])
dimension])
dimension])
The closeval() function behaves the same as openval() except that it returns the upper limit of the
specified dimension when the window is closed. Like openval(), this function works in Aggregate operators,
and not in Query operators.
The value returned by closeval() might differ from any of the actual tuple values included in the window.
For example, consider an Aggregate operator with a dimension CountDim, where the windows created by
that dimension include a window with a range of 5 to 10. If the actual tuple values in the window are 6, 7, and
9, then closeval(CountDim) returns 10 for that window, not 9.
If the dimension name is omitted and the aggregate has only one dimension, then closeval() uses that
dimension. If the dimension name is omitted and the aggregate has more than one dimension, the result is a
typecheck error.
Back to Top ^ Back to Aggregate Overview ^
Aggregate Functions: Windowing
151
StreamBase References
firstn()
Function syntax:
list(T) firstn(int count, T f)
Returns a list with count elements containing the first count values for field f in an Aggregate's window
or in a Query Table column. Accepts fields of all data types and returns a list whose elements are the same
type as the type of field f. Field f can contain null values, and such fields are returned in the list.
The value of count must be nonnegative, cannot be null, and must remain the same for the duration of the
Aggregate window. For count=0, an empty Aggregate window, or an empty Query Table column, an empty
list is returned.
This function works best in conjunction with the Aggregate operator. See the note above about using this
function with Query operators.
Back to Top ^ Back to Aggregate Overview ^
firstnonnullval()
Function syntax:
T firstnonnullval(T f)
Returns the first non-null value for field f in the Aggregate's window or in a Query Table column. Accepts all
data types and returns the same type as its argument.
This function works best in conjunction with the Aggregate operator. See the note above about using this
function with Query operators.
Back to Top ^ Back to Aggregate Overview ^
firstval()
Function syntax:
T firstval(T f)
Returns the first value for field f in the Aggregate's window or in a Query Table column. Accepts all data
types and returns the same type as its argument.
This function works best in conjunction with the Aggregate operator. See the note above about using this
function with Query operators.
Back to Top ^ Back to Aggregate Overview ^
firstn()
152
StreamBase References
lag()
Function syntax:
T lag(T f)
Returns the next-to-last value for field f in the Aggregate's window or in a table column. If the window or
table column has only one row or zero rows, lag() returns null. Accepts all data types and returns the same
type as its argument.
This function works best in conjunction with the Aggregate operator. See the note above about using this
function with Query operators.
Example usage in an aggregate context: avg(fieldname/lag(fieldname)) where fieldname is a
numeric value such as a price field.
Back to Top ^ Back to Aggregate Overview ^
lastn()
Function syntax:
list(T) lastn(int count, T f)
Returns a list with count elements containing the last count values for field f in an Aggregate's window or
in a Query Table column. Accepts fields of all data types and returns a list whose elements are the same type
as the type of field f. Field f can contain null values, and such fields are returned in the list.
The value of count must be nonnegative, cannot be null, and must remain the same for the duration of the
Aggregate window. For count=0, an empty Aggregate window, or an empty Query Table column, an empty
list is returned.
This function works best in conjunction with the Aggregate operator. See the note above about using this
function with Query operators.
Back to Top ^ Back to Aggregate Overview ^
lastnonnullval()
Function syntax:
T lastnonnullval(T f)
Returns the last non-null value for field f in the Aggregate's window or in a Query Table column. Accepts all
data types and returns the same type as its argument.
This function works best in conjunction with the Aggregate operator. See the note above about using this
function with Query operators.
Back to Top ^ Back to Aggregate Overview ^
lag()
153
StreamBase References
lastval()
Function syntax:
T lastval(T f)
Returns the last value for field f in the Aggregate's window or in a Query Table column. Accepts all data
types and returns the same type as its argument.
This function works best in conjunction with the Aggregate operator. See the note above about using this
function with Query operators.
Back to Top ^ Back to Aggregate Overview ^
openval()
Function syntax:
double
int
long
timestamp
openval([string
openval([string
openval([string
openval([string
dimension])
dimension])
dimension])
dimension])
Can only be used in an Aggregate operator, not in a Query Operator. Returns the lower limit of the specified
dimension for the current window. The dimension name is passed as a quoted string, and must match the
name of a dimension in the Aggregate operator. This function works even if the dimension specified is not the
one that actually opened the current window. In that case, the value returned is the value of the dimension at
the time the window was created.
The value returned by openval might differ from any of the actual tuple values included in the window. For
example, consider an Aggregate operator with a dimension CountDim, where the windows created by that
dimension include a window with a range of 5 to 10. If the actual tuple values in the window are 6, 7, and 9,
then openval(CountDim) returns 5 for that window, not 6.
If the dimension name is omitted and the aggregate has only one dimension, then openval() uses that
dimension. If the dimension name is omitted and the aggregate has more than one dimension, the result is a
typecheck error.
Back to Top ^ Back to Aggregate Overview ^
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
lastval()
154
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Pattern Matching Language
StreamBase Pattern Matching Language
StreamBase queries can compare data from one or more input streams using pattern matching statements. This
topic describes the basic concepts.
In an EventFlow application, pattern evaluation is performed by the Pattern operator, where separate controls
on the StreamBase Properties view's Pattern Settings tab are used to specify the desired template, dimension,
and interval values. A predicate entry qualifies which tuples match the pattern. See Using the Pattern Operator
for the details of configuring the Pattern operator.
In a StreamSQL application, pattern matching expressions are included within a SELECT statement's FROM
PATTERN clause. In addition to the basic pattern, a predicate can be specified in a WHERE clause. See the
SELECT Statement topic for StreamSQL details.
Syntax
template [template [pattern_operator [NOT] template]...] window
Pattern Elements
template
An expression that evaluates to a stream identifier or alias. The pattern can include nested templates,
or templates combined using pattern operators.
pattern_operator
A logical operator (AND, OR, THEN, or NOT) that describes the relationship between a pair of
templates. See Pattern Operators for descriptions and shortcut notation.
window
• For time-based patterns, specifies a time interval within which the operation must terminate.
• For value-based patterns, specifies a maximum range of values in a particular field. The
window terminates when the range of values for that order field, across all streams, equals or
exceeds the specified value.
For value-based patterns, the order field must be a top-level numeric or timestamp field: that
is, it cannot be a sub-field in an event schema. For example, consider the following schema,
whose second field is a nested tuple:
StreamBase Pattern Matching Language
155
StreamBase References
(id int, sub (id2 int))
Given the preceding schema, the only valid order field is id; you cannot specify either sub
or sub.id2.
If the pattern is composed of multiple subpatterns, the entire pattern, not just each subpattern in
isolation, must match within the window limits.
In EventFlow modules, windows (either time or value) are defined graphically in the Pattern Settings
tab of the operator's Properties view. In StreamSQL, the FROM PATTERN clause has a WITHIN
subclause, which indicates the window type using either the TIME or ON keyword.
Pattern Operators
Operator names are not case-sensitive. Operators have the following order of precedence (starting with the
most tightly bound):
1. NOT
2. AND
3. OR
4. THEN
The following list describes the use of each pattern operator in templates. Notice that the operator keywords
can also be expressed using the shorthand symbols shown:
NOT A or !A (Absence)
Matches when no A tuple is received within the window interval.
A AND B or A && B (Conjunction)
Combines two subpatterns, and matches when both subpatterns match. It is like a join in that it
produces the cross-product of two streams. The AND pattern is right-associative. For example,
A AND B AND C is interpreted as A AND (B AND C).
A OR B or A || B (Disjunction)
Combines two subpatterns, and matches when either subpattern matches. It is like union. The OR
pattern is right-associative (for example, A OR B OR C is interpreted as A OR (B OR C)).
A THEN B or A -> B (Followed By)
Matches when a match on the left side is followed in sequence by a match on the right side. The
THEN pattern is right-associative. For example, A THEN B THEN C is interpreted as
A THEN (B THEN C).
Examples
Example 1. Equivalent Patterns
The following patterns are equivalent:
a AND b OR c THEN NOT d AND e
a && b || c -> !d && e
(((a and b) or c) then ((not d) and e))
Pattern Elements
156
StreamBase References
Example 2. Predicate
A predicate added after the pattern further constrains the potential matches. For example consider this pattern
statement:
A -> B
followed by this predicate:
WHERE A.id == B.id
This combination produces matches only where the ID of a tuple on the A stream matches the ID of a tuple on
the B stream, and the tuple on the A stream arrived first. By contrast, a NOT predicate would specify which
tuples resulting from the main pattern must not occur.
Example 3. Negated Stream in Predicate
You can use fields from a negated stream in a predicate. For example, consider the following time-based
pattern query:
SELECT A.id AS fi, C.id AS fo
FROM PATTERN A -> !B -> C WITHIN 5 TIME
WHERE B.id == A.id
INTO out;
The predicate causes the pattern to ignore any tuple arriving on Stream B if the tuple's ID field does not match
the ID field of a tuple that previously arrived on A.
To illustrate, the following figure represents a sequence of tuples flowing into Stream A, B, and C. At each
step, the figure shows the value of the ID field. Assume that all these events occur within the specified time
interval:
Notice these events:
Examples
157
StreamBase References
• After Step 3, tuples have arrived in the specified sequence, and the Stream B ID field does not match
the existing Stream A ID. This satisfies the conditions of both the pattern and the predicate, and so the
selected A.id and C.id values are emitted as output.
• No output can occur after Step 3 until the specified pattern is repeated, beginning in Step 6.
• In Step 7, the tuple arriving on Stream C satisfies the specified sequence, because after Step 6, no
intervening tuple arrived on Stream B. Therefore, another tuple is output.
Related Topics
• Detecting Patterns
• Using the Pattern Operator
• SELECT Statement
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
Related Topics
158
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Server Configuration File XML Reference
StreamBase Server Configuration File XML
Reference
This topic provides a reference for the XML syntax of StreamBase Server configuration files. See Server
Configuration File Overview for important information on using configuration files.
Create new server configuration files as described in Creating New Server Configuration Files. Edit
configuration files in Studio with the validating and syntax-aware Configuration File Editor, as described in
Deployment File Editor.
You can break a complex server configuration file into component pieces, and then include smaller portions
into a master configuration file as described in Using Modular Configuration Files. You can encipher
password and URI values in server configuration files as described in Enciphering Passwords and Parameter
Values. See Using Environment Variables in Configuration Files when defining variables in your
configuration file.
Server configuration files use a schema-defined XML syntax. The root element is
streambase-configuration, which contains all configuration elements. It has one or more of the
following child elements:
<global>
<server>
<page-pool>
<runtime>
<custom-functions>
<sbmonitor>
<security>
<authentication>
<high-availability>
<java-vm>
<data-sources>
<operator-parameters>
<error-handler>
<jms-connections-defaults>
StreamBase Server Configuration File XML Reference
159
StreamBase References
Note
If a parameter includes a Microsoft Windows path, for separators you should either use forward slashes ('/')
or escape backward slashes ("\\") by doubling them. For example, both this syntax
<operator-parameter name="SCRIPT_ROOT" value="D:/scripts/"/>
and this syntax
<operator-parameter name="SCRIPT_ROOT" value="D:\\scripts"/>
are valid.
<global>
Identifies the locations of resources, such as custom function plug-ins or modules, that should be loaded when
the StreamBase Server runs your application.
Normally, it is not necessary to identify such resources when they are stored and managed within StreamBase
Studio. However, you do need to edit the global element to specify the locations of these resources for
running from the sbd command line outside of StreamBase Studio. In addition, you may need to provide
references to resources stored outside of StreamBase Studio, such as third-party libraries.
global has one or more of the following child elements:
• Zero, one, or more of: <plugin>
• Zero, one, or more of: <module-search>
• Zero, one, or more of: <operator-resource-search>
Note
For all three elements, when running sbd in background mode with the -b flag, be sure to specify fully
qualified paths, or use paths with environment variable components that sbd can resolve at runtime. See
Using Environment Variables in Configuration Files.
The current directory of sbd at runtime is generally the directory that contains the primary EventFlow or
StreamSQL application loaded, but might be a different directory if you start sbd from another directory or if
you start sbd from a cron job or automatically start sbd at system startup as a Windows service or with
/etc/init.d on UNIX.
Example 1. global
The following UNIX example assumes that you have given a value to the STREAMBASE_HOME environment
variable:
<global>
<plugin directory="/usr/share/sbplugins" />
<plugin file="/home/sbuser/sbproject/waycooloperator.so" />
<module-search directory="/usr/share/sbapps" />
<operator-resource-search directory="${STREAMBASE_HOME}/resourceFiles" />
Note
160
StreamBase References
</global>
Back to top ^
<plugin>
Identifies a native code library in the form of a DLL file for Windows or a .so file for UNIX, that contains
the implementation of one or more custom simple or aggregate functions to be loaded when the application
runs. You can have as many plug-in elements as you need, each identifying a different library. For custom
C++ functions, each function name must also be declared in a <custom-functions>.
Do not confuse the global/plugin element with the java-vm/library element, which also specifies
native code libraries to load. Use plugin to specify native libraries that contain C++ functions
custom-written for your organization. Use library to specify native libraries called by Java functions,
adapters, or JDBC drivers, possibly written and provided by third parties.
Attributes
Attribute
Required
Description
Specifies the path to a directory containing one or more custom function
Either this attribute
plug-ins to be loaded. StreamBase Server scans each specified directory and
directory
or file
loads all the .so or DLL files it finds there, as appropriate for the platform.
Specifies the path to an individual DLL or .so file that implements a custom
function or custom adapter that you want to load when your application runs.
Unlike the directory attribute, this option causes only the specified file to
Either this attribute
be loaded.
file
or directory
You can omit the file extension: StreamBase loads the platform-appropriate
shared object (.so) file on UNIX, or DLL file on Windows.
<module-search>
Identifies a directory containing EventFlow or StreamSQL application modules to be called and used by the
top-level module at run time. These external modules then can be referenced using a module reference in an
EventFlow application, or an APPLY statement in a StreamSQL application.
StreamBase Studio maintains its own module search path as described in module search path in the Authoring
Guide. Studio appends entries specified in global/module-search elements in the server configuration
file, after reconciling relative paths, as described in How Studio Uses Server Configuration Files in the
Administration Guide.
StreamBase Systems recommends deploying your StreamBase applications by bundling your Studio project
and running the bundle file as an argument to the sbd command. Running a bundle has the advantage of
preserving the Studio module search path (supplemented as necessary by module-search entries in the
configuration file), plus the resource search path and Java build path, all in a runnable format.
Note
161
StreamBase References
To run an application from the sbd command line without the benefit of a bundle, you must specify each
module-containing directory with module-search elements, even if that means re-specifying the Studio
module search path.
See Module Search Path Order of Precedence to understand how StreamBase locates module files.
Attribute Required
Description
Directory where application modules are stored at runtime.
directory Yes
The directory must be local (or shared) to the runtime system.
<operator-resource-search>
Specifies a directory containing resource files used by Java operator and adapter code at run time. File
resources might include text files, SQL files, CSV data files from which to load tables or feed simulations, or
other file types.
StreamBase Studio maintains its own resource search path as described in resource search path in the
Authoring Guide. Studio appends entries specified in global/operator-resource-search elements
in the server configuration file, after reconciling relative paths, as described in How Studio Uses Server
Configuration Files in the Administration Guide.
StreamBase Systems recommends deploying your StreamBase applications by bundling your Studio project
and running the bundle file as an argument to the sbd command. Running a bundle has the advantage of
preserving the Studio module search path, resource search path, and Java build path in a runnable format.
To run an application from the sbd command line without the benefit of a bundle, you must specify each
resource-containing directory with operator-resource-search elements, even if that means
re-specifying the Studio resource search path.
See Module Search Path Order of Precedence to understand how StreamBase locates resource files. The
search path order for modules also applies to locating resources on the resource search path.
Attribute Required
directory Yes
Description
Directory where Java operator or adapter files are stored at runtime.
The directory must be local (or shared) to the runtime system, and StreamBase
Systems recommends using only full pathnames.
<server>
Specifies aspects of the StreamBase Server that relate to network I/O. Optionally designates a data directory
for disk-based Query Tables (so that data can persist between StreamBase Server sessions). The server
element has the following child elements :
• One or more of: param with any of these name-value attribute pairs:
name Attribute
tcp-port
<module-search>
value Attribute
TCP port number to be used for network I/O. Default: 10000.
162
StreamBase References
connection-backlog
client-heartbeat-interval
datadir (Enterprise Edition only)
disk-querytable-cache (Enterprise
Edition only)
disk-querytable-pagesize
(Enterprise Edition only)
Number of backlogged connections. Servers with many clients may want
to increase the maximum number of backlogged connections to the
server. For further details, lookup the manual page for the system call
listen. The default is 10.
The number of milliseconds between heartbeat packets sent to clients.
Clients can be configured to require a heartbeat packet from the server at
a minimum interval. This is used primarily for network segmentation
detection. Setting client-heartbeat-interval to 0 will disable heartbeats
from the server. Clients connected to such a server will not have
heartbeat protection, regardless of their locally configured minimum
heartbeat interval. The default value is 10000.
Path to a directory to be used to store persistent data from any on-disk
Query Tables in your StreamBase application. You must specify a
closing slash for UNIX paths, or a closing backslash for Windows paths,
to designate the path as a directory path.
The value of datadir can be specified in several ways, not only in the
server configuration file. The precedence order used is described as part
of the STREAMBASE_DATA environment variable.
Amount of main memory that will be allocated to cache data from any
disk-based Query Table operations. The value units are in MB of main
memory and must be a power of 2. When unspecified, the default value
is 16 MB. If your application uses disk-based Query Tables, you may be
able to improve performance by setting a higher value. However, use
caution with setting this parameter, as too high a value may consume
more memory than needed and could negatively impact other resources
that require memory. Memory is allocated for this parameter by the
native code portion of the StreamBase Server launcher, and thereby
competes with memory available for the Java VM. See Java VM
Memory Settings.
As with any resource setting, establish baseline performance metrics and
then test the affect of increasing or decreasing values under normal and
peak loads.
The page size used internally for disk-based Query Table operations.
You may be able to improve performance by setting a higher value. This
page size setting is not related to the StreamBase page size, nor the
operating system (OS) page size. The value units are in KB and must be
a power of 2. Valid values are 0, 1, 2, 4, 8, 16, 32 and 64. The default is
0 which specifies using an default value, which varies by operating
system.
Mode of transaction support for disk-based Query Tables.
Enumeration: { 0 | 1 | 2 }
disk-querytable-transaction_mode
(Enterprise Edition only)
<server>
The default mode is 1, where transactions are enabled, but not flushed to
persistent store in any predictable time. Mode 2 transactionally commits
every single table update to persistent store. Mode 0 disables
transactional support. See the next parameter for a related setting.
163
StreamBase References
If you are using disk-based Query Tables in transaction mode 1 or 2,
disk-querytable-logsize (Enterprise
your Query Table performance may improve if you increase the size of
Edition only)
transaction log files. The value units are in MB. The default is 10 MB.
If you are using disk-based Query Tables in transaction mode 1 or 0,
writes to tables are not committed to disk in a predictable time frame.
Setting the disk-querytable-flush-interval-ms parameter forces disk
disk-querytable-flush-interval-ms
commits at the interval specified in milliseconds. A flush interval is
(Enterprise Edition only)
needed in transaction mode 1 and 2 in order to write a checkpoint and
remove unneeded log files. The default interval for mode 0 is no flushing
(0) and 30000 (30 seconds) for modes 1 and 2.
Settings for disconnecting idle clients.
An idle enqueue client is a client who has enqueued at least one tuple
and has been idle for idle-enqueue-client-timeout-ms. An idle dequeue
client is a client who has subscribed to at least one stream (at any point)
and has been idle for idle-dequeue-client-timeout-ms.
idle-enqueue-client-timeout-ms,
idle-dequeue-client-timeout-ms
idle-client-check-interval-ms
max-persistent-connections
operator-state-change-timeout-ms
Clients that have enqueued and subscribed are subject to both settings.
The server checks clients every idle-client-check-interval-ms. The actual
point that a client is disconnected will be approximate modulo
idle-client-check-interval-ms.
Values are in milliseconds. Values greater than zero turn these features
on. The default is off.
How often the server should check for idle clients. The value is in
milliseconds. The default is 60000 (60 seconds).
Maximum number of persistent connections. Each persistent connection
uses up server resources. To protect the server from errant client
connections a user can specify a maximum number of persistent
connections. Any attempted client connections over the limit will be
disconnected.
Default value = -1 (no limit).
Each Java Operator or Embedded Adapter changes state along with the
server process as a whole. The server waits for each Operator or Adapter
to change state before it completes its state change. The value of
operator-state-change-timeout-ms is the amount of time
(in milliseconds) the server will wait before timing out the Operator or
Adapter. If an Operator or Adapter is timed out on a state change, the
server shuts down the Operator or Adapter, and proceeds with its own
server state change. If unspecified in your sbd.sbconf, the default
operator-state-change-timeout-ms value is 10000
milliseconds (ten seconds).
Example 2. server
<server>
<param name="tcp-port" value="10100"/>
<param name="connection-backlog" value="12"/>
<param name="datadir" value="/tmp/112233/querytable/last10stocks"/>
<server>
164
StreamBase References
<param name="disk-querytable-cache" value="256"/>
<param name="disk-querytable-transaction_mode" value="1"/>
<param name="disk-querytable-flush-interval-ms" value="40000"/>
</server>
Back to top ^
<page-pool>
Defines memory parameters used by the StreamBase Server. page-pool has the following child elements:
• One or more of: param with any of these name-value attribute pairs:
name Attribute
value Attribute
Use this setting to specify the initial size for output buffers and to calculate the
maximum size a client output queue can reach before the client is disconnected.
page-size
See max-client-pages below for further details. The default value for all
supported platforms is 4096 bytes.
Use this setting to specify how many buffers per output stream to maintain in a
max-pooled-buffers
buffer cache. The default is 1024. To disable the cache, set the value to -1. This
parameter does not determine when and whether slow clients are disconnected.
Use this setting to specify the behavior of slowly dequeuing clients. The server
either disconnects slow clients (the default) or blocks the server to wait for slow
clients to catch up. A value of -1 (the default) causes slow clients to be
slow-dequeue-client-wait
disconnected. A value greater than -1 causes the server to sleep for that amount of
time in milliseconds when it detects that a dequeuing client is running behind. The
server continues sleeping until there is available dequeuing space for the client.
Sets the maximum number of pages that a dequeuing client connection can
allocate. Depending on the setting of the slow-dequeue-client-wait
parameter, the server either disconnects a slow client or blocks. This setting is
designed to protect sbd from a slow or hung dequeuing clients.
max-client-pages
With the default page-size setting of 4096 bytes, the default
max-client-pages value of 2048 will provide 8 megabytes. To allow ALL
dequeuing clients to allocate unlimited memory in the server, set the value to zero.
Note that the number of pages that a client allocates will change over time. A
client that is consuming tuples as fast as the server produces them will only use
one or two pages. The maximum can be reached with a slow or hung client, or if
there is a large spike of output data.
Example 3. page-pool
In the following configuration example, the administrator decided to double the max-client-pages value
from its 2048 default, resulting in a 16 MB page buffer for all dequeuing client connections:
<page-pool>
<param name="page-size" value="4096" />
<page-pool>
165
StreamBase References
<param name="max-client-pages" value="4096" />
</page-pool>
For related details, see the java-vm section below.
Back to top ^
<runtime>
Starting with release 7.0.0, the <application> child element of the <runtime> element is deprecated.
StreamBase Systems recommends migrating your <application> settings to a StreamBase deployment
file, whose syntax is described in StreamBase Deployment File XML Reference.
Use the <runtime> element to specify certain parameters for running StreamBase Server. The <runtime>
element supports the following child elements:
• One or more <application> child elements (deprecated as of release 7.0.0).
• One or more of: param with either of the following name-value attribute pairs:
name Attribute
schema-max-size
now-implementation
value Attribute
The maximum size of a stream's schema; that is, the total number of bytes of all fields
you expect in the tuple. The default value is 1048576 bytes, which is 1 MB. While
there is no theoretical upper limit, in practice there is a maximum based on the
available memory on the machines that will host the processing of your application. Be
cautious about creating very large schemas, because applications that move smaller
amounts of data perform much better than applications that move tuples containing
unnecessary fields.
The StreamBase expression language provides a now() function to return the current
time. With this parameter, you can select one of two now() implementations. Default:
system.
• The system value means that the now() function uses Java's
System.currentTimeMillis(). This is the default.
• The thread value means that the now() function uses a background thread
that checks the time approximately every millisecond. This option will result in
decreased accuracy, but may be more efficient than the system option if you
call now() more frequently than 1000 times per second.
Example 4. runtime
<runtime>
<param name="schema-max-size" value="1048576"/>
<param name="now-implementation" value="system"/>
</runtime>
Back to top ^
<runtime>
166
StreamBase References
<custom-functions>
Use this element to declare the parameters for a custom function. This element has the following child
elements:
• One or more of: <custom-function>
Use the custom-functions section for several reasons:
• To make a custom C++ function available for use in a StreamBase application.
• To register a C++ function's type signatures.
• To assign aliases to C++ or Java functions so they can be called in the same way as built-in functions.
• In rare cases, to register a Java function's type signatures.
Back to top ^
C++ Function Overview
To use a custom C++ function in your StreamBase application, you must:
• Identify the DLL (Windows) or .so (UNIX) file that contains your custom function, using the
plugin directory="path" or plugin file="filename" elements described above in
the global section.
• Name the function and provide the signatures of its arguments and return type using a
custom-function element.
In the following example, a custom C++ function named func1 takes a string and an int argument and
returns a string:
<custom-functions>
<custom-function name="func1" type="simple" >
<args>
<arg type="int" />
<arg type="string" />
</args>
<return type="string" />
</custom-function>
</custom-functions>
Add the alias attribute to allow the use of a short name or alternate name for a given function. For example,
the following allows you to call the func1 function (from the example above) in StreamBase expressions in
the form f(myString, myInt):
<custom-functions>
<custom-function name="func1" type="simple" alias="f">
<args>
... [same as example above]
The language attribute in the above examples is the default, which is the same as specifying
language="cplusplus".
<custom-functions>
167
StreamBase References
Use the args and return elements to describe the data types of the function's arguments and return types.
For C++ functions, you must register each argument and return type. If the type attribute of an arg or
return element is list or tuple, the element must have a child element that further describes the type. For
tuple types, this is a schema element. For list types, this is an element-type element. For example:
<args>
<arg type="tuple">
<schema>
<field name="f1" type="int" />
<field name="f2" type="double" />
</schema>
</arg>
<arg type="list">
<element-type type="string" />
</arg>
</args>
<return type="list">
<element-type type="tuple">
<schema>
<field name="g1" type="blob" />
<field name="g2" type="timestamp" />
</schema>
</element-type>
</return>
The example above describes the arguments to a function that takes:
• A tuple whose fields are an int and a double
• A list of strings
The example returns:
• A list of tuples whose fields are a blob and a timestamp
Back to top ^
Java Function Overview
Unlike C++ functions, you do not need to add a custom-function element for every Java function. A
custom-function element is required under two circumstances:
• You want to assign an alias for a custom function or for a standard library function so that your
StreamBase application can call the function directly with the alias name (instead of using
calljava()).
• Your custom function takes arguments or returns values of the list or tuple data types, and you do not
want to provide a custom function resolver.
For simple Java functions that you expect to use in limited cases, it may be simpler to call it with
calljava() than to define a custom-function element.
To use a custom Java function in your StreamBase application, you must:
• Make sure the JAR or class file that implements the function is available on StreamBase Server's
classpath. Use the jar or dir elements of the java-vm element to extend the server's classpath.
C++ Function Overview
168
StreamBase References
• Call the function in an expression in your application using either:
• A function alias
• calljava() for simple functions
• calljava() for aggregate functions
Java functions that have a custom-function definition must have the alias attribute defined. If not
defined, StreamBase Server starts but does not load the specified function, instead printing a notification
message on the console that the function definition will be ignored. As an alternative, you can call a Java
function using calljava(), without first specifying a custom-functions definition for that function.
When using custom-function to describe a custom Java function:
• You must specify language="java".
• You must specify the fully qualified class name with the class attribute.
• You must specify the alias attribute.
• For simple functions (that is, when using type="simple" or with no type attribute), you must
specify the name attribute.
For Java functions only, as an alternative to explicitly specifying argument and return types, you can specify
args="auto" to have StreamBase Server autodetect the argument and return types. If the server
autodetects overloaded functions of the same name with different argument types, it adds all detected versions
of the specified function.
Java functions typically use the args="auto" attribute. If you do not use args="auto" for a Java
function, then you must specify arg and return elements to describe each argument and return type, using
the syntax described above for C++ functions. You might use arg type= instead of args="auto" if your
function has many overloaded signatures, and you only want to expose a subset of those signatures for use in
your StreamBase application.
If your Java function has an argument or return value of type list or tuple, and you use args="auto", then
you must provide a custom function resolver as described on Custom Functions with Complex Data Types. If
you use explicit arg type= elements, you do not need to provide a custom function resolver.
The following example shows a typical definition for a Java function:
<custom-functions>
<custom-function
language="java"
class="com.streambase.sb.sample.Hypotenuse"
name="calculate"
alias="hypotenuse"
type="simple"
args="auto" />
</custom-functions>
You can specify an alias for any Java function in the server's classpath, including standard library functions:
<custom-functions>
<custom-function
language="java"
class="java.lang.Math"
name="toDegrees"
alias="degrees"
Java Function Overview
169
StreamBase References
args="auto" />
</custom-functions>
You can use the same string for name and alias. Using the same string allows you to call a function
directly by its original name. For example, the following allows you to call log10() in a StreamBase
expression:
<custom-functions>
<custom-function
language="java"
class="java.lang.Math"
name="log10"
alias="log10"
args="auto" />
</custom-functions>
Back to top ^
<custom-function>
Each simple or aggregate C++ function must be declared in a custom-function element, as described
above in C++ Function Overview. Java functions can be optionally declared in a custom-function
element, as described in Java Function Overview.
C++ and Java functions can be assigned aliases. You can use the aliased function name as if that function
were embedded in your StreamBase application. For example, setting alias="foo" means you can invoke
foo(arg) in a StreamBase expression instead of calljava(foo(arg)) or callcpp(foo(arg)).
Attributes
Attribute
Required for C++ Required for Java
Functions
Functions
name
Yes
Yes
type
No
No
alias
No
Yes
language
No
Yes
class
No
Yes
args
Not used.
No
<custom-function>
Description
The function's name as it appears in its C++ or
Java source file. This attribute is required for
simple functions (that is, when
type="simple"), but can and should be
omitted for aggregate functions.
Either simple or aggregate. The default is
simple.
A substitute name for this function, to be called
directly instead of using calljava() or
callcpp(). This attribute is required when
language="java", and is optional for C++
functions.
Either cplusplus or java. The default is
cplusplus.
For Java functions only, the fully qualified class
name where the specified function is defined.
For Java functions only, you can set
args="auto" to have StreamBase Server
170
StreamBase References
autodetect the arguments and return type of the
current function. If you elect to use an args
child element for Java functions, do not use this
args= attribute.
For C++ functions, use an args child element
(not this args= attribute) to describe the data
type of each of the function's arguments.
The custom-function element has the following child elements:
• Zero or one of: <args>
• Zero or one of: <return>
Back to top ^
<args>
For Java functions, you can set the args="auto" attribute of the custom-function element to have
StreamBase Server autodetect the argument types. In this case, do not use the args element. You can
optionally use args for Java functions as described in Java Function Overview.
For C++ functions, you must use an args element with arg child elements for each of the function's
arguments.
The args element has the following child element:
• One or more of: <arg>
Back to top ^
<return>
Defines the data type returned by a C++ or Java function. For C++ functions, this element is required if the
function returns a value.
For Java functions only, setting the args="auto" attribute of the custom-function element
autodetects the return type as well as the argument types. Thus, when using args="auto", no return
element is required.
Attributes
Name Required
type
Yes
<args>
Description
The data type to be returned from the function to the StreamBase application.
For type="list" and type="tuple" you must also supply the appropriate
element-type or schema child element, respectively.
171
StreamBase References
The return element has the following child elements:
• Zero or more of: <schema>
• Zero or more of: <element-type>
Back to top ^
<arg>
Defines the data type of one of a function's arguments. The order of arg elements in the configuration file
should match the argument order for the function.
Attributes
Name Required
type
Description
The data type for this argument for this function. Valid values are the names of the
StreamBase data types in all lowercase letters.
Yes
For type="list" and type="tuple" you must also supply the appropriate
element-type or schema child element, respectively.
The arg element has the following child elements:
• Zero or more of: <schema>
• Zero or more of: <element-type>
Back to top ^
<schema>
Defines the schema for a value when type="tuple" for the arg, return, element-type, or field
elements. The schema element has one child element:
• One or more of: <field>
<field>
Defines the data type for a single field in a tuple.
Attributes
Name Required
Description
name Yes
The name of this field in the tuple.
type Yes
The data type for this field in the tuple. Valid values are the names of the StreamBase data
types in all lowercase letters.
<return>
172
StreamBase References
For type="list" and type="tuple" you must also supply the appropriate
element-type or schema child element, respectively.
The field element has the following child elements:
• Zero or more of: <schema>
• Zero or more of: <element-type>
Back to top ^
<element-type>
Defines the data type for the elements of a list when type="list" for the arg, return,
element-type, or field elements.
Attributes
Name Required
type
Description
The data type for the elements of the current list. Valid values are the names of the
StreamBase data types in all lowercase letters.
Yes
For type="list" and type="tuple" you must also supply the appropriate
element-type or schema child element, respectively.
The element-type element has the following child elements:
• Zero or more of: <schema>
• Zero or more of: <element-type> (in the case of a list of lists)
Back to top ^
<sbmonitor>
Use this element to define characteristics of the statistics that will be generated for use by the sbmonitor
utility. sbmonitor has the following child elements:
• One or more of: param with any of these name-value attribute pairs:
name Attribute
value Attribute
Either true or false.
enabled
Set to true to enable statistics collection, or false to disable it. If it is set to false,
sbmonitor will not be usable with this instance of StreamBase Server. The default is
true.
period-ms
<field>
173
StreamBase References
Specifies the period, in milliseconds, over which statistics are aggregated. The default
is 1000 ms (every second).
Example 5. sbmonitor
<sbmonitor>
<param name="enabled" value="true"/>
<param name="period-ms" value="2000"/>
</sbmonitor>
Back to top ^
<security>
The security section controls security and authentication in the sbproxy and sbd. If there is a security section,
the sbd will only listen for connections on localhost, so connections from remote computers cannot be made.
If there is a security section in the sbconf file, the sbproxy server will allow only SSL connections from
clients.
Note
This section cannot be configured together with the <authentication> section, which provides a different
authentication method.
security has one or more of the following child elements:
• One of: <ssl-authentication>
• One param element using this name-value attribute pair:
name Attribute
value Attribute
true
Restrictions to user actions will be added in this section.
perform-authentication false
All users will be able to perform any action. The client connections
will still be SSL, but no further authentication will be performed.
• Zero or one of: <transform-principal>
• Zero or one of: <client-ssl-connections>
• Zero or more of: <ldap>
• Zero or more of: <role>
• Zero or one of: <user-data>
Example 6. security
<security>
<ssl-authentication>
<param name="keystore" value="../test/proxy/security/signed.keystore"/>
<param name="keystore-password" value="secret"/>
</ssl-authentication>
<sbmonitor>
174
StreamBase References
<param name="perform-authentication" value="false"/>
<transform-principal>
<param name="searchRegexp" value="cn=([^,]*).*"/>
<param name="replaceRegexp" value="$1"/>
</transform-principal>
<client-ssl-connections>
<param name="require-client-authentication" value="true"/>
<param name="cipher-suite" value="SSL_RSA_WITH_3DES_EDE_CBC_SHA"/>
</client-ssl-connections>
<ldap>
<!-- a TLS auth server -->
<server host="parallels" port="838">
<param name="principal-root" value="ou=Users,dc=example,dc=com"/>
<param name="principal-search" value="cn={0}"/>
<param name="keystore" value="ldapuser.keystore"/>
<param name="keystore-password" value="secret"/>
</server>
</ldap>
<ldap>
<!-- a basic auth server -->
<server host="parallels" port="839">
<param name="principal-root" value="ou=Users,dc=example,dc=com"/>
<param name="principal-search" value="cn={0}"/>
<param name="root-dn" value="cn=Manager,dc=example,dc=com"/>
<param name="password" value="secret"/>
</server>
</ldap>
<role name="StreamBaseSuperuser">
<param name="action" value="Administrate"/>
</role>
<role name="InnocentBystander">
<param name="action" value="Status"/>
<param name="action" value="Enqueue default.InputStream1"/>
<param name="action" value="Dequeue default.OutputStream1"/>
</role>
<user-data>
<user>
<param name="cn" value="cn=Alice Pleasance Liddell,ou=Users,dc=example,dc=com"/>
<param name="role" value="InnocentBystander"/>
<param name="role" value="StreamBaseSuperuser"/>
<param name="password" value="secret"/>
</user>
<user>
<param name="cn" value="[email protected], CN=Bob Newhart,
OU=Users, O=StreamBase Systems, L=Waltham, ST=Massachusetts, C=US"/>
<param name="role" value="InnocentBystander"/>
</user>
</user-data>
</security>
Back to top ^
Note
175
StreamBase References
<ssl-authentication>
Specifies the keystore that holds the signed X.509 server certificate that will be used for SSL connections
between clients and the sbproxy server.
ssl-authentication has the following child elements:
• Two param elements, each using one of these name-value attribute pairs:
name Attribute
value Attribute
URI of the keystore that identifies a certificate authority (CA). Alternatively, the
keystore
URI can point to a trust store, which defines multiple CAs that your organization
recognizes.
keystore-password The password to access the keystore.
Back to top ^
<transform-principal>
Defines a search/replace regular expression that will change the name of the principal. The transform in the
preceding security example extracts the CN section from the entire principal's name as it appears in a
certificate.
transform-principal has the following child elements:
• Two param elements, each using one of these name-value attribute pairs:
name Attribute
searchRegexp
replaceRegexp
value Attribute
Matches on a pattern in a field in an LDAP
database.
Specifies the replacement pattern.
Back to top ^
<client-ssl-connections>
Defines the type of SSL connection and the external tools used for encryption.
client-ssl-connections has the following child elements:
• One of: param with this name-value attribute pair:
name Attribute
require-client-authentication false
value Attribute
SSL connections will be accepted from clients that do not have
a signed user certificate. This is sometimes called 1-way SSL,
and is the default value. The principal and password attributes
(user= and password= attributes) must be specified in the URI,
<ssl-authentication>
176
StreamBase References
unless the perform-authentication parameter is false (see
below)
true
Only client connections that have a certificate signed by a
known certificate authority will be allowed. This is sometimes
called 2-way SSL. The principal will be taken from the
certificate.
• Zero or more of: param with this name-value attribute pair:
name
Attribute
value Attribute
Comma-separated list of cipher suites that can be used for SSL encryption. If this
element is not listed, sbproxy uses all the cipher suites that are installed with the JVM.
When this element is present, sbproxy is limited to the suites you list. Typical suites for
the JDK 1.5 JVM include: SSL_RSA_WITH_RC4_128_MD5,
SSL_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA,
TLS_DHE_RSA_WITH_AES_128_CBC_SHA,
TLS_DHE_DSS_WITH_AES_128_CBC_SHA,
SSL_RSA_WITH_3DES_EDE_CBC_SHA,
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA,
SSL_RSA_WITH_DES_CBC_SHA, SSL_DHE_RSA_WITH_DES_CBC_SHA,
SSL_DHE_DSS_WITH_DES_CBC_SHA,
SSL_RSA_EXPORT_WITH_RC4_40_MD5,
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA,
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA,
cipher-suite
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA,
SSL_RSA_WITH_NULL_MD5, SSL_RSA_WITH_NULL_SHA,
SSL_DH_anon_WITH_RC4_128_MD5,
TLS_DH_anon_WITH_AES_128_CBC_SHA,
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA,
SSL_DH_anon_WITH_DES_CBC_SHA,
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5,
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA,
TLS_KRB5_WITH_RC4_128_SHA, TLS_KRB5_WITH_RC4_128_MD5,
TLS_KRB5_WITH_3DES_EDE_CBC_SHA,
TLS_KRB5_WITH_3DES_EDE_CBC_MD5, TLS_KRB5_WITH_DES_CBC_SHA,
TLS_KRB5_WITH_DES_CBC_MD5, TLS_KRB5_EXPORT_WITH_RC4_40_SHA,
TLS_KRB5_EXPORT_WITH_RC4_40_MD5,
TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA,
TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
Back to top ^
<ldap>
Specifies information for connecting to and searching LDAP servers to manage user authentication. Create a
separate ldap element for each LDAP server. If more than one LDAP server is defined, the requests will be
sent to each LDAP server in turn, in a round-robin manner. You can configure one or more LDAP servers.
<client-ssl-connections>
177
StreamBase References
ldap has the following child elements:
• One of: <server>
Back to top ^
<server>
Identifies an LDAP server that you want to connect to, and specifies the type of authentication to be used.
Attributes
Attribute Required
Description
host
Yes
The address presented to clients.
port
Yes
The port number used by the LDAP server.
server has the following child elements:
• Two of: param elements, each with one of these name-attribute pairs:
name Attribute
value Attribute
The Distinguished Name pattern that describes the directory
information tree on the LDAP server, from the required entry to the
principal-root
directory root. Principal names will be applied to the pattern during
authentication.
The field name and index within the LDAP to use when looking up
principal-search
principals.
The StreamBase connection to the LDAP server needs the credentials
of any LDAP user to validate the connection. This does not need to be
a user with any particular privileges and can be a username you add to
root-dn
the LDAP database only for StreamBase authentication, such as
sbuser. <param name="root-dn"
value="cn=sbuser,dc=example,dc=com"/>
• One of the following groups of elements:
To authenticate in the sbconf file
Two of: param, each with one of these name-attribute pairs
name Attribute
value Attribute
The Distinguished Name pattern that identifies a valid user to the LDAP
root-dn
server.
password
The password that must be entered to authenticate a user.
To authenticate in LDAP (TLS)
Two of: param, each with one of these name-attribute pairs
name Attribute
<ldap>
value Attribute
178
StreamBase References
keystore
URI of the keystore that identifies users for the LDAP server.
keystore-password The password to access the keystore.
Back to top ^
<role>
Use the role element to define a role and assign its actions. You can define any number of roles and use any
role names, each with a different combination of actions. Later (in the user-data element) you can assign users
to roles.
When a client attempts to perform an action, such as dequeue OutputStream1, the user is authenticated, then
the authentication source (an LDAP server or a user-data in the sbconf file) is asked for all of the roles the
user has. If the user has as role which has the dequeue default.OutputStream1 action listed, then the dequeue
operation is allowed. .
Attributes
Attribute Required
Description
name
Yes
A name for a group of actions. You can assign any name.
role has the following child elements:
• One or more param elements with this name-attribute pair:
name Attribute
action
value Attribute
By assigning actions, you determine the commands that a user is authorized to
use (and, by omission, not use). Specify one of the following:
Administrate
Matches Administer actions in the LDAP server, and enables the
following all sbadmin commands.
Status
Matches Status actions in the LDAP server, and enables the following
subcommands: status, describe, list.
Enqueue container.stream
Matches Status actions in the LDAP server. Enables the user to enqueue
the specified stream.
Dequeue container.stream
Matches Status actions in the LDAP server. Enables the user to dequeue
the specified stream.
Back to top ^
<server>
179
StreamBase References
<user-data>
Defines the Principal-to-role mapping for each user. This section should not be defined if an ldap section is
defined.
user-data has the following child elements:
• One or more of: user
Back to top ^
<user>
A user corresponds to a Principal in an LDAP database. Specifies authentication data and assigns user roles.
user has the following child elements:
• One of: param with the following name-attribute pair:
name Attribute
value Attribute
The full Distinguished Name of the
cn
Principal.
• One of: param with the following name-attribute pair:
name Attribute
value Attribute
password
The user's password.
• Zero or more of: param with the following name-attribute pair:
name Attribute
value Attribute
role
One of the roles defined in a role element.
Back to top ^
<authentication>
Use this element to define the authentication parameters that will be used to protect the StreamBase
application from unauthorized access.
Note
The authentication element cannot be configured together with the security element. You can only
use one of these security methods.
authentication has the following child elements:
• One or more of: param with any of these name-value attribute pairs:
<user-data>
180
StreamBase References
name Attribute
value Attribute
Enumerated: { true | false }. Set to true to require authentication
information from clients, or false to allow access from anyone. The default is
false, but it should be set to true in production systems.
Enumerated: sb-password-file. This is the only value allowed. It
specifies the type of authentication to use to verify user names and password.
Required if authentication is enabled.
The path to the password file containing StreamBase user names and
passwords. Required if authentication is enabled. The default is sbpasswd in
the etc subdirectory of your StreamBase installation.
The username for the administrative user in the StreamBase authentication
system.
The password for the administrative user.
enabled
type
filepath
adminuser
adminpassword
Example 7. authentication
<authentication>
<param name="enabled" value="true"/>
<param name="type" value="sb-password-file"/>
<param name="filepath" value="/opt/streambase/etc/sbpasswd"/>
</authentication>
Back to top ^
<high-availability>
Use this element to enable automatic leadership detection, to enable automatic table replication, and to define
the high-availability leadership status for an instance of StreamBase Server. You can also specify other
parameters required for a particular high-availability server pair. For more information about using
StreamBase for high availability, see Clustering and High Availability in the Administration Guide.
<high-availability> has the following child elements:
• param containing each of the following name-value attribute pairs:
name Attribute
value Attribute
value=LEADER or value=NON_LEADER. Specifies the leadership status of this
leadership-status
server.
enabled
value="auto" or value="custom" or value="ha-off". The default is
ha-off.
Specifies whether automatic leadership tracking is enabled. When value="auto"
or value="custom", you must either define parameters in the
ha-application element described below, or specify the name of your
customized HA container with the <ha-container> parameter.
StreamBase release 6.6 and earlier used settings of true and false for the
enabled value. Applications that still use settings are silently recognized, with
Note
181
StreamBase References
false=ha-off and true=auto, or true=custom if there is also an <ha-container>
element. StreamBase Systems recommends updating to use one of the three current
settings.
value="container-name". Used when enabled=custom to specify the
name of the HA container, and optionally used with enabled=auto to override
the default the name of the HA container used for automatic leadership tracking.
ha-container
Without this parameter, automatic leadership tracking uses an HA container named
_SB_ha.
When you use the ha-container parameter, you must not also specify an
ha-application element.
• ha-application, which has one child element, param. Specify one or more of the following
name-value attribute pairs with one or more param elements:
name Attribute
Required?
value Attribute
Host name or IP address of the other server in a
HB_OTHER_SERVER
required
high-availability pair.
HB_PORT
required
Port number for HB_OTHER_SERVER.
Integer, number of milliseconds. Specified how long the
HB_TIMEOUT
optional
HA Heartbeat should wait before declaring a timeout.
Integer, number of milliseconds. Specifies how often to
HB_INTERVAL
optional
send a heartbeat message
Integer. Specifies the number of times to attempt to
HB_RECON_ATTEMPTS optional
reconnect.
Integer, number of milliseconds. Specifies how long to wait
HB_RECON_SLEEP
optional
between reconnection attempts.
• table-replication, which has one child element, param. Specify one or more of the following
name-value attribute pairs with one or more param elements:
name Attribute
Required?
HB_OTHER_SERVER
required
REPL_OTHER_SERVER_PORT
required
REPL_CHECK_INTERVAL
optional
REPL_BATCH_SIZE
optional
REPL_RECONNECT_INTERVAL optional
value Attribute
Host name or IP address of the other server
participating in table replication.
The port on HB_OTHER_SERVER.
Integer, number of seconds. Specifies how often to
check the replication state of the table.
Integer, number of tuples. Specifies the size of the
batches to be sent from the LEADER to the
NON_LEADER.
Integer, number of milliseconds. Specifies how
often to attempt reconnection between the
LEADER and NON_LEADER.
The optional parameters can be used only if you set the enabled parameter of high-availability to
auto or custom.
The following example shows some sample settings. See also High Availability Sample for an example of this
<high-availability>
182
StreamBase References
section.
Example 8. high-availability
<high-availability>
<param name="leadership-status" value="LEADER"/>
<param name="enabled" value="auto"/>
<ha-application>
<param name="HB_OTHER_SERVER" value="name_of_other_server"/>
<param name="HB_PORT" value="12345"/>
<param name="HB_TIMEOUT" value="3000"/>
<param name="HB_INTERVAL" value="1000"/>
<param name="HB_RECON_ATTEMPTS" value="10"/>
<param name="HB_RECON_SLEEP" value="500"/>
</ha-application>
<table-replication>
<param name="HB_OTHER_SERVER" value="name_of_other_server"/>
<param name="REPL_OTHER_SERVER_PORT" value="6789"/>
<param name="REPL_CHECK_INTERVAL" value="1"/>
<param name="REPL_BATCH_SIZE" value="100"/>
<param name="REPL_RECONNECT_INTERVAL" value="250"/>
</table-replication>
</high-availability>
Back to top ^
<java-vm>
Use the <java-vm> element to specify settings and properties to pass to the Java virtual machine (JVM) that
runs StreamBase Server. The <java-vm> top-level element has the following child elements:
Zero, one, or two of <param>
Zero, one, or more of <jar>
Zero, one, or more of <dir>
Zero, one, or more of <library>
Zero, one, or more of <sysproperty>
See the next section for an example of a <java-vm> element in use.
Back to top ^
<java-vm> Complete Example
The following shows a complete example of the <java-vm> top-level element with all of its child elements
in use.
<java-vm>
<param name="java-home" value="/usr/lib/jvm/java-6-sun" />
<param name="jvm-args" value="-XX:MaxPermSize=128m
-Xms512m -Xmx1024m -XX:+UseParNewGC -XX:+UseConcMarkSweepGC
-XX:+CMSParallelRemarkEnabled -XX:MaxGCPauseMillis=50 "/>
<java-vm>
183
StreamBase References
<jar file="/usr/lib/calcs/othercalcs.jar" />
<jar file="./Resources/ojdbc14.jar" />
<dir path="./java-bin" />
<dir path="/usr/share/maths/classes" />
<library path="/usr/lib/vendor/lib/" />
<sysproperty name="streambase.tuple-charset"
value="UTF-8" />
<sysproperty name="codegen.intermediate-stream-dequeue"
value="true" />
</java-vm>
Back to top ^
<param> Child Element
The <java-vm> element accepts zero or one of the <param> child element for each of the name-value
pairs in the following table:
name Attribute
value Attribute
Rarely used. StreamBase installs a JDK for internal use by StreamBase
Studio and StreamBase Server in streambase-install-dir/jdk.
Thus, you only need to set the java-home parameter to override the default
JDK. See Using an External JDK for instructions.
If used, set the value of java-home to the full, absolute path to a supported
JDK on your machine. For example, on UNIX:
java-home
<java-vm>
<param name="java-home"
value="/usr/lib/jvm/java-6-sun" />
</java-vm>
Or, on Windows:
<java-vm>
<param name="java-home"
value="C:/Program Files/Java/jdk1.6.0_30" />
</java-vm>
jvm-args
See Supported Configurations in the Installation Guide for information on the
minimum JDK versions supported. See How StreamBase Server Searches for
a JDK for background information when considering a change in the
java-home parameter.
Specifies a quoted set of arguments to send to the JVM that runs the server.
You can specify minimum and maximum values for the memory allocation
pool, and can specify Java properties, or other JVM options.
Do not set the classpath here, and do not specify -server or -client,
because the server JVM is always loaded.
Use the guidance in Java VM Memory Settings for assistance when setting
the -Xms (minimum) and -Xmx (maximum) Java heap size arguments, and
the -XX:MaxPermSize setting to specify the maximum size of the
<java-vm> Complete Example
184
StreamBase References
permanent generation of Java objects for garbage collection.
Use the guidance in Garbage Collection Policy Settings when adding or
changing settings that affect Java garbage collection algorithms.
You can use the <sysproperty> Child Element element as an alternative to, or
in addition to, setting Java properties in the <jvm-args> element.
When you generate a default server configuration file in Studio and you opt to include the default contents, or
when you generate a default configuration file with sbd â s, it contains the following settings for the
<java-vm> element:
<java-vm>
<param name="jvm-args" value="
-XX:MaxPermSize=128m
-Xms256m -Xmx512m
-XX:+UseParNewGC
-XX:+UseConcMarkSweepGC
-XX:+CMSParallelRemarkEnabled
-XX:MaxGCPauseMillis=50 "/>
</java-vm>
See Java VM Memory Settings and Garbage Collection Policy Settings for detailed discussions of these
settings.
Back to top ^
<jar> Child Element
Specifies a JAR file to be loaded at runtime, used by a Java Operator or by a JDBC data source server.
Required within a parent java-vm element when Java operators or JDBC tables are used in the StreamBase
application. You can specify multiple JAR files, as shown in the <java-vm> example.
• JARs that provide JDBC access to a supported JDBC database.
• JARs that implement a custom Java operator or adapter.
• JARs provided by third parties that implement code needed by an adapter or operator.
You can specify multiple <jar> elements. One <jar> element specifying the path to a JDBC driver is
required when using a JDBC Table data construct.
The <jar> element has the following attribute:
Attribute Required
Description
file
Yes
Path to the JAR file.
Note on Portability of Paths
For maximum portability of your application for deployment on another server, specify a relative path in the
Studio project folder, or deploy your application with a StreamBase bundle so that the bundler can resolve
absolute paths at bundle time.
Examples:
<param> Child Element
185
StreamBase References
<java-vm>
<jar file="./Resources/ojdbc14.jar" />
<jar file="/usr/lib/calcs/othercalcs.jar" />
</java-vm>
Back to top ^
<dir> Child Element
Use the <dir> element to add a directory to the classpath of the JVM that runs StreamBase Server. You can
use multiple dir elements.
The <dir> element has the following attribute:
Attribute Required
path
Description
Directory path to add to the JVM's classpath.
Yes
See the Note in the <jar> element, which also applies here.
Examples:
<java-vm>
<dir path="./java-bin" />
<dir path="/usr/share/maths/classes" />
</java-vm>
Back to top ^
<library> Child Element
Use the library element to specify the path to a directory that will be prepended to the JVM's
java.library.path to identify the location of native libraries used by your Java code, by an adapter, or
called by JDBC drivers. The directory you specify is expected to contain one or more DLL files for Windows
or .so files for UNIX. To load multiple library sets, use multiple library elements. See <java-vm> for an
example.
Do not confuse the java-vm/library element with the global/plugin element, which also specifies
native code libraries to load. Use plugin to specify native libraries that contain C++ functions
custom-written for your organization. Use library to specify native libraries called by Java functions,
adapters, or JDBC drivers, possibly written and provided by third parties.
The <library> element has the following attribute:
Attribute Required
path
Description
Path to the directory containing native libraries called by Java code.
Yes
See the Note in the <jar> element, which also applies here.
Example for UNIX:
<java-vm>
<library path="/usr/lib/vendor/lib" />
</java-vm>
Note on Portability of Paths
186
StreamBase References
Example for Windows:
<java-vm>
<library path="C:/Program Files/vendor/lib" />
</java-vm>
Back to top ^
<sysproperty> Child Element
Use the sysproperty element as an alternative to adding system properties with the jvm-args parameter
of the java-vm element. You can only specify one jvm-args parameter, so in order to add a system
property with it, you must append the property setting to the jvm-args parameter. By contrast, you can add
as many sysproperty elements as you need, each one specifying an individual property.
The <sysproperty> element has the following attributes:
Attribute Required
name
Yes
value
Yes
Examples:
Description
The name of the system property, such as streambase.tuple-charset or
codegen.intermediate-stream-dequeue. See StreamBase Java System
Properties.
The value to set for the named property, such as UTF-8 or true.
<java-vm>
<sysproperty name="streambase.tuple-charset"
value="UTF-8" />
<sysproperty name="codegen.intermediate-stream-dequeue"
value="true" />
</java-vm>
Back to top ^
<data-sources>
Parent element for data-source declarations, which identify all external database connections accessed by
StreamBase applications. You can define as many data sources as you need, each pointing to a single server.
data-sources has the following child elements:
• One or more of: <data-source>
<data-sources> Examples
The following shows three examples of data-sources sections of the server configuration file, illustrating
three different database connections. First, a connection to a MySQL database:
<data-sources>
<data-source name="MYSQL" type="jdbc">
<driver value="com.mysql.jdbc.Driver"/>
<library> Child Element
187
StreamBase References
<uri value="jdbc:mysql://mysql.example.com:3306/qa?user=username&amp;password=secret"/>
<param name="jdbc-reconnect-regexp" value="Communications link failure"/>
<param name="jdbc-reconnect-regexp" value="Connection reset"/>
<param name="jdbc-reconnect-attempts" value="5"/>
<param name="jdbc-reconnect-sleep" value="250"/>
</data-source>
</data-sources>
Next, a connection to an Oracle 10g database, using an enciphered connection password:
<data-sources>
<data-source name="Oracle_10g" type="jdbc">
<driver value="oracle.jdbc.driver.OracleDriver"/>
<uri value="jdbc:oracle:thin:@orasrv.example.com:1521:sb_test"/>
<param name="user" value="orauser"/>
<param name="password" enciphered="true"
value="M5DSWylszg5aA9AK29MOiaDLq7SMqmTor+nW3qURTrT9E9eqJfTPyyUudCK34nhXHE53PXK6pregp4MW8qru
<param name="jdbc-fetch-size" value="10000"/>
<param name="jdbc-batch-size" value="20"/>
<param name="jdbc-max-column-size" value="32768"/>
</data-source>
</data-sources>
Finally, a JDBC connection to a Vertica database. (StreamBase also supports high-performance loading of a
Vertica database using non-JDBC native API connectivity.)
<data-sources>
<data-source name="Vertica" type="jdbc">
<driver value="com.vertica.Driver"/>
<uri value="jdbc:vertica://MyHost:5433/chron_vertica"/>
<param name="user" value="vertigo"/>
<param name="jdbc-share-connection" value="true"/>
<param name="jdbc-quote-strings" value="true"/>
</data-source>
</data-sources>
Back to top ^
<data-source> Examples
The following shows examples of the data-source, driver, and uri elements for several supported
databases, showing examples of the JDBC connection string format for each database vendor. See Supported
Configurations for the currently supported databases.
You must obtain the JDBC driver JAR file from your database vendor's web site, or packaged as part of your
database distribution. Remember that, in addition to these lines, you must configure a jar child element of
the java-vm element, with a path pointing to the JDBC driver JAR file.
DB2
<data-source name="DB2" type="jdbc">
<driver value="com.ibm.db2.jcc.DB2Driver"/>
<uri value="jdbc:db2://db2server.example.com:50000/db2_test"/>
</data-source>
Microsoft SQL Server
<data-source name="MSSQL64" type="jdbc">
<driver value="com.microsoft.sqlserver.jdbc.SQLServerDriver"/>
<uri value="jdbc:sqlserver://mssql64.example.com;databasename=mssql_test;user=sa;password
<data-sources> Examples
188
StreamBase References
</data-source>
MySQL
<data-source name="MYSQL" type="jdbc">
<driver value="com.mysql.jdbc.Driver"/>
<uri value="jdbc:mysql://mysqlsvr.example.com:3306/mysql_test?user=username&amp;password=
</data-source>
Oracle
<data-source name="Oracle_10g" type="jdbc">
<driver value="oracle.jdbc.driver.OracleDriver"/>
<uri value="jdbc:oracle:thin:@oraserver.example.com:1521:ora_test"/>
</data-source>
Sybase
<data-source name="SybaseASE" type="jdbc">
<driver value="com.sybase.jdbc3.jdbc.SybDriver"/>
<uri value="jdbc:sybase:Tds:sybserver.example.com:5001/syb_test"/>
</data-source>
Vertica
<data-source name="vertica" type="jdbc">
<driver value="com.vertica.Driver"/>
<uri value="jdbc:vertica://vertserver.example.com:5433/vertica_test"/>
</data-source>
Thomson Reuters Velocity Analytics
<data-source name="myDB" type="jdbc">
<driver value="org.firebirdsql.jdbc.FBDriver"/>
<uri value="jdbc:firebirdsql://velocity.example:3050/TRTCE"/>
</data-source>
<data-source>
This element identifies a database server to be used as a data source and accessed from an EventFlow or
StreamSQL application. This element specifies the JDBC driver, the JDBC connection string that identifies
the server's location, and one or more JDBC connection parameters.
Note
For a JDBC data source, you must also edit the java-vm element. Add the jar or library elements that
specify the location of the JAR file that implements the database vendor's JDBC driver. If your JDBC driver
requires supplemental files such as configuration files, specify their location in a library element.
Attributes
Attribute Required
name
Yes
type
Yes
Description
A unique identifier for the database server. The name you assign to your data source
must follow the StreamBase identifier naming rules, as described in Identifier Naming
Rules.
Must be jdbc.
data-source has the following child elements:
• One of: <driver>
<data-source> Examples
189
StreamBase References
• One of: <uri>
• Zero or more of: <param> with jdbc-retry-sqlstate, jdbc-reconnect-regexp, and
jdbc-dont-reconnect-regexp attributes.
• Zero or one of <param> with any of the other name-value attribute pairs.
Back to top ^
<driver>
Identifies the database driver's Java class.
Attributes
Attribute Required
Description
value
Yes
The fully qualified Java class that implements the database vendor's JDBC driver.
See examples of the driver element in <data-source> Examples below.
Back to top ^
<uri>
Use the uri element to specify the JDBC connection string appropriate for your database and server location.
Each supported database has its own syntax for JDBC connection strings. You must obtain the correct
connection string syntax from your database vendor, possibly from a README file distributed with the JAR
file that implements the vendor's JDBC support. Use the examples in <data-sources> Examples as general
guidelines for constructing your site's JDBC connection string.
Attributes
Attribute Required
Description
value
Yes
The JDBC connection string appropriate for your database vendor and server
location. The correct string to use will be both vendor-specific and site-specific.
The format of JDBC connection strings are vendor-specific, but generally follow a
format like the following:
jdbc:vendorname://server-address:port
The connection string for some vendors appends username and password fields,
while other vendors require a protocol name in the string.
If the uri value contains ampersands, replace them with &amp;. Failing to do so
results in an error at connection time stating Unterminated entity
Note
190
StreamBase References
reference.
enciphered no
Use the example JDBC connection strings in the next section as guidelines.
Set to "true" to specify that the contents of the value attribute were enciphered
with the sbcipher command. This allows you to specify a JDBC connection string
that contains private values such as passwords and server connection information, but
not have the values appear as clear text in the configuration file. For further
information, see Enciphering Passwords and Parameter Values.
Back to top ^
<param>
The param child element of the data-source element has the attributes shown in the following table. See
<data-sources> Examples for examples of the param element used in the context of several data-source
elements. These elements only affect Query operator access to a JDBC database through the JDBC Table data
construct. They do not affect feed simulations that take input data from JDBC data sources.
Attributes
Attribute Required
Description
name
yes
Parameter label that can be used in an expression.
Set to "true" to specify that the contents of the current value attribute were
enciphered with the sbcipher command. This allows you to specify private values
enciphered no
such as passwords and user names, yet not have the values appear as clear text in the
configuration file. For further information, see Enciphering Passwords and Parameter
Values.
value
yes
Value to which the parameter is resolved.
Note
Pay close attention to the parameter options for your data source. In particular, notice that the StreamBase
default for the jdbc-reconnect-attempts option is zero, which means failed database connections are
not automatically reconnected by default. Be sure to specify a non-zero value for this option if you want to use
automatic reconnection.
The following table lists the possible values for the name attribute, with the corresponding values for each:
name attribute settings
user
password
jdbc-fetch-size
<uri>
corresponding value attribute setting
Username with which to log in to the database server.
Password with which to log in to the database server. You can encipher the
password and store the enciphered string instead of a plain text password. See
Enciphering Passwords and Parameter Values.
This parameter can be used to control the size of the buffer used by the JDBC
driver when fetching rows. Consider limiting the fetch size when your
191
StreamBase References
StreamBase application experiences memory problems related to large result
sets returned from queries to the JDBC data source. Consider increasing fetch
size if deadlocks occur because you are performing multiple queries against the
same JDBC data source and query result sets are larger than the current
database fetch size.
Possible values:
• 0: Uses the JDBC driver's default value (default).
• -2147483648 (For MySQL databases only): Normally, MySQL
retrieves complete result sets and stores in them in memory. Setting the
Integer.MIN_VALUE in this parameter serves as a signal to the
MySQL driver to stream result sets row-by-row instead. Caution For
other databases, a negative value causes a SQLException.
• positive integer (for databases other than MySQL): A positive
integer serves as a hint to non-MySQL JDBC drivers for the size to
allocate for result set buffers. The actual size allocated depends on how
a given driver interprets it, which may vary among drivers. A positive
integer is ignored by MySQL drivers.
The timeout (in milliseconds) of background JDBC operations in StreamBase
Studio. This parameter affects only typecheck times in Studio, and has no effect
during runtime.
jdbc-timeout
StreamBase Studio communicates with the data source server in order to
typecheck an application that has a JDBC data source connection. If the
database server does not respond during this interval, the typecheck fails. The
default value of 15000 (15 seconds) is adequate for normal local area network
connections. Consider increasing this value if you experience typecheck failures
due to a slow network connection. For example, the following example
increases the interval to 25 seconds:
<param name="jdbc-timeout" value="25000"/>
jdbc-query-timeout
jdbc-connection-timeout
jdbc-max-column-size
Note
Specifies an integer number of milliseconds that StreamBase waits for JDBC
query operations to execute. The default is 0, which means wait forever for each
query to return; this default matches the previous StreamBase behavior before
this parameter was added in releases 6.6.14, 7.0.7, and 7.1.2. Specify a value
such as 15000 (15 seconds) to prevent StreamBase Server from hanging in rare
cases where the JDBC server never responds to a query. This setting specifies
the default timeout value for all queries to this data source.
Starting with release 7.1.5, you can also specify a timeout value separately for
each Query operator, using the Timeout field on the Query Settings tab of the
Properties view.
The timeout in milliseconds to wait before each JDBC connection request to the
JDBC data source times out.
The maximum column size expected in a JDBC table. Columns that are larger
than this value (2048, by default) will cause a typecheck exception. If you
override the default, remember that the resulting output tuple's schema must
entirely fit into the pool-size. Therefore, consider also increasing the page
pool-size, described in <page-pool>.
192
StreamBase References
Retry any select, insert, or update JDBC operation that returns the specified
SQLSTATE for this database driver. The operation is retried until it succeeds.
jdbc-retry-sqlstate
A useful example is when you know that the database might return an exception
due to transaction deadlocks in the database. When a deadlock occurs, the
database returns a specific exception SQLSTATE indicating deadlock or
timeout, and the expected behavior is to roll back the operation or transaction
and retry.
You can use multiple parameters to test for multiple SQLSTATEs.
Allows a Query operator to perform an insert or update operation in batch
mode, and sets the number of statements that will be executed at one time. For
example, if jdbc-batch-size is set to 10, then when the first nine tuples
arrive at the Query operator, they are held by the JDBC connection instead of
being executed immediately. When the tenth tuple arrives and is added to the
batch of statements, the entire batch is executed at once.
jdbc-batch-size
If an update is interrupted normally (for example, by stopping the sbd server),
the Query operator updates the JDBC table using all the accumulated
statements, even if there are fewer than the specified number. However, if the
application is stopped abnormally, the updates may not occur.
The value must be an integer greater than 1 (a value of 1 is valid, but not
meaningful for a batch operation).
jdbc-batch-timeout-ms
jdbc-reconnect-regexp
Note that your application may require more memory when you perform query
updates in batch mode.
Specifies as an integer number of milliseconds the longest time that batched
tuples remain buffered and unsent. Like the jdbc-batch-size setting, this
setting only affects insert or update operations. Tuples may be written sooner
than this number, or more frequently, for any number of reasons. The default
setting is 60000 (60 seconds).
If a connection is lost between StreamBase Server and the database server, the
next attempted JDBC operation returns an error. There are no standard error
codes (or SQLSTATE) for communications failures, so to detect these errors,
we must parse the text of the database-specific error messages. Use the
jdbc-reconnect-regexp parameter to specify a regular expression to be
compared to any received error messages.
You can specify more than one jdbc-reconnect-regexp parameter to
specify several error message strings to be considered communications failures.
Each specified string is compared in order to the received error message text.
If a specified string is matched in the text of any error message, the JDBC
operator assumes a communications failure has occurred, and attempts to open a
new connection to the database server in order to re-execute the current
command. If the error text is not matched in the error strings, and the JDBC
operator has an error port, an error tuple is sent to the error port. If there is no
error port, a tuple is sent on the error stream.
Note
193
StreamBase References
If you do not specify a jdbc-reconnect-regexp parameter, the pattern
.* (period-asterisk) is used as the pattern string, which means any received
error causes a reconnection attempt.
This parameter is similar to jdbc-reconnect-regexp, but is used to
specify the database error messages for which you do NOT want to retry
communicating with the database server.
You can use this parameter more than once to specify different regex patterns.
Each specified string is compared in order to the received error message text.
When a JDBC error occurs, if the error message text matches a pattern specified
in one of the jdbc-dont-reconnect-regexp patterns, the current JDBC
jdbc-dont-reconnect-regexp
command is not executed again, and an error tuple is sent to the JDBC
operator's error port, if enabled, or to the error stream if not. The next time a
tuple is read by the JDBC operator, a new connection is made to the database
server.
jdbc-reconnect-attempts
If no error strings match a pattern in any jdbc-dont-reconnect-regexp
parameter, then the error strings are checked against the
jdbc-reconnect-regexp patterns, with a fallback to a pattern of .*, as
described above.
The jdbc-reconnect-attempts parameter controls the number of
reconnections StreamBase Server will attempt. If the connection to the database
server is lost, the configuration example above attempts to establish a
connection to the database server five times. If five connection attempts fail, an
error message is printed and StreamBase Server exits with an error status. If a
connection is reestablished to the database server, and then the connection is
lost some time thereafter, the reconnection count is reset so that five attempts to
reconnect will be made again. The retry count is reset for each SQL exception,
not for the lifetime of the connection.
A jdbc-reconnect-attempts value of -1 specifies that the server is to
continue reconnection attempts without limits. A value of zero disables
reconnection attempts.
If the jdbc-reconnect-sleep parameter is specified, reconnection
attempts are delayed by the specified number of milliseconds. If no
jdbc-reconnect-sleep parameter is used, there will be no delay between
reconnection attempts.
jdbc-reconnect-sleep
jdbc-share-connection
Note
Just like the initial connection to the database, reconnection attempts use the
jdbc-timeout parameter to limit how long the StreamBase Server waits to
establish a connection. The default value for jdbc-timeout is 15000
milliseconds (15 seconds).
This parameter has no effect if your StreamBase application has only one JDBC
operator. The default setting is false, which means that, in an application with
two or more JDBC operators, each JDBC operator gets its own connection from
the StreamBase Server to the specified data source. Set this parameter to true
to specify that all JDBC operators in an application are to share a single
connection from StreamBase Server to the specified data source.
194
StreamBase References
jdbc-quote-strings
Some databases such as Vertica require the strings passed into a JDBC
PreparedStatement object to be enclosed in single quotes within double
quotes ("'Dallas'"). Set this parameter to true if the database vendor's
documentation specifies quoting the strings passed into
PreparedStatement.setString().
Back to top ^
<operator-parameters>
This element contains declarations of global parameters that you want to use in expressions in any module or
container run by the current StreamBase Server instance. Parameters declared with an
operator-parameter element are global to the StreamBase Server instance configured herein, and apply
to any application or container run under that server instance. See Using Global Parameters for details. See
Parameter Overview to understand the difference between this element and the module-parameter child
element of the application element in StreamBase deployment files.
operator-parameters has the following child element:
• One or more of: <operator-parameter>
<operator-parameter>
Use this element to declare global operator parameters and assign them a default value. Parameters are
defined as name-value attribute pairs, with the name attribute being a simple name such as ParamOne.
Assign a value to ParamOne for two purposes:
1. To expose a parameter available to StreamBase modules using the ${param} syntax. (The same
syntax also resolves to module parameters defined directly in application modules, if present.)
2. To set the specified value as the parameter value for any Java operator or adapter with a parameter
of the specified name.
In this usage, the parameter's name can also be a dotted path name such as
ContainerName.OperatorName.ParamOne to set a particular adapter or operator's
parameter, without affecting other operators in the system.
If the operator is in a submodule, you must include the submodule in the dotted path name; for
example, ContainerName.SubModuleName.OperatorName.Param. When a path is used,
the parameter value is only set for that named operator. All other parameters with the same name on
other operators remain unmodified.
You can set the value of an <operator-parameter> to the value of a system environment variable
whose value is resolved at StreamBase Server startup time. However, if the specified system variable is not
set or not present, StreamBase Server can fail to start. In this case, you can use the colon-equals syntax
described in Environment Variables and the Colon-Equals Syntax.
Specify the following name-value attribute pair:
<operator-parameters>
195
StreamBase References
Attribute Required
Description
Parameter label that can be used in an expression. The label can be a simple
parameter name or a qualified name in StreamBase path notation.
When this attribute specifies a simple parameter name such as ParamOne, all
operators in the application that have a parameter named ParamOne are set with the
specified value.
name
yes
You can narrow the setting to apply only to a particular operator by specifying the
StreamBase path to the operator in the form
ContainerName.OperatorName.ParamName. If the operator is in a
submodule, you must include the module's name in the path:
ContainerName.ModuleName.OperatorName.ParamName. This sets the
value of ParamName only for the specified operator. All other operators with a
parameter named ParamName remain unset.
Set to true to specify that the contents of the value attribute were enciphered with
the sbcipher command. This allows you to specify global parameters with private
enciphered no
values, including passwords and server connection information, but not have the
values appear as clear text in the configuration file. For further information, see
Enciphering Passwords and Parameter Values.
value
yes
Value to which the parameter is to be resolved.
See String Values in Parameters for StreamBase Systems' recommended policy on quoting string parameters.
Examples:
<operator-parameters>
<operator-parameter name="MyStringParam" value="somestring"/>
<operator-parameter name="MyIntParam" value="2"/>
<operator-parameter name="ContainerName.OperatorName.ParamName"
value="120" />
</operator-parameters>
Applying this example, the following expressions could be used:
SELECT * FROM SourceTagger_1
"${MyStringParam}" AS source
...
WHERE myint > ${MyIntParam}
Note
If an operator-parameter name conflicts with a declared module parameter name, the module
parameter value takes precedence.
<operator-parameter name="Host" value="${STREAMBASE_SERVER}"/>
Or use the colon-equals syntax to specify a default value for the environment variable:
<operator-parameter name="Host" value="${STREAMBASE_SERVER:=sb://sbhost:9900}"/>
Back to top ^
<operator-parameter>
196
StreamBase References
<error-handler>
As of release 6.0, the default handling for runtime errors is to discard the error-producing event and continue
processing. You can specify different processing for certain error types. error-handler has the following
child elements:
• One or more of: <error>
Example 9. error-handler
<error-handler>
<error type="eval-error" action="shutdown" />
<error type="eval-plugin-error" action="shutdown" />
</error-handler>
Back to top ^
<error>
Defines a single error type for the error handler. Use multiple error elements to define multiple error types, as
shown in the <error-handler> example.
Attributes
Attribute Required
Description
• eval-error
This exception is caused by a variety of reasons, including errors that occur
when evaluating expressions or when flushing disk-based query table logs,
and incorrect timestamp formats. Continuing after such errors is not
recommended.
• eval-plugin-error
type
Yes
Java and C++ plug-ins can get eval-plugin-error exceptions for a variety of
reasons, including TupleExceptions, errors, and when setting parameters.
Continuing after such errors is not recommended.
• ordering-error
The Gather operator throws this error when an order by field value is null. The
Aggregate operator throws it when an order by field value is null or the
current value is less then a previous value.
action
Yes
• shutdown: Stop the server
<error-handler>
197
StreamBase References
• continue: Continue and display error
• ignore: Continue and display no error
Back to top ^
<jms-connections-defaults>
The jms-connections-defaults element is used ONLY to specify JMS connection parameters for
container connections over JMS. This element is described in Specifying JMS Container Connection Defaults.
Settings made with this element do NOT manage or control the operation of the embedded StreamBase JMS
adapters. Those adapters have their own independent configuration file formats described in JMS Input and
Output Adapters.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
<error>
198
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Deployment File XML Reference
StreamBase Deployment File XML Reference
This topic describes the XML syntax of StreamBase deployment files.
The root element of a deployment file is deploy, which contains all XML elements that describe a runnable
StreamBase deployment. The <deploy> element supports one instance of the <runtime> element.
The syntax of the <runtime> element of deployment files is comparable to, but not identical to, the
deprecated <runtime> element of server configuration files. See Server Configuration File Overview for a
discussion of the differences between old and new <runtime> elements.
Edit deployment files in Studio with the Deployment File Editor, which provides typechecking of your
deployment file as you compose it, as well as color coding, autocompletion, and context-aware tag proposal of
valid elements and attributes.
The root element of deployment files is <deploy>, which one first-level child element:
<runtime>
This first-level element in turn has the following child elements:
<application>
<container-connection>
<runtime>
Use this element to specify one or more containers (one per application) that will be hosted by StreamBase
Server. You can have one or more <application> child elements. The <runtime> element has the
following child elements:
• Zero, one, or more <application> elements
• Zero, one, or more <container-connection> elements
The following synthetic example shows all deployment file elements used at least once. In practice, it is
unlikely that you will need to specify all elements for the same deployment case.
<?xml version="1.0" encoding="UTF-8"?>
StreamBase Deployment File XML Reference
199
StreamBase References
<deploy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbdeploy/">
<runtime>
<application container="default" module="app1.sbapp"/>
<application container="holder2" module="app2.sbapp">
<extension-point-contents>
<extension-point target-id="extpt.id">
<extension name="caseA" module="submoduleA.sbapp"/>
<extension name="caseB" module="submoduleB.sbapp">
<module-parameters>
<param name="myVar" value="myValue" enciphered="false"/>
</module-parameters>
</extension>
</extension-point>
</extension-point-contents>
<module-parameters>
<param name="varname" value="varvalue" enciphered="false"/>
</module-parameters>
<trace traceFileBase="tracebase" traceCompress="true"/>
</application>
<container-connections>
<container-connection dest="holder2.input1"
source="default.output3" where="tradeID % 2 == 0"/>
</container-connections>
</runtime>
</deploy>
<application>
Use this element to specify an application module to load into a named container. The application file can be
an EventFlow or StreamSQL module, or a precompiled application (.sbar) file. The element has the
following attributes:
Attribute Required
module
Yes
container Yes
enqueue
No
dequeue
No
suspend
No
<runtime>
Description
The name of an EventFlow, StreamSQL, or precompiled application file, which must
exist in the current Studio project's module search path. You can use Ctrl+Space in
the Deployment File Editor to pop up a list of the available modules in the module
search path.
If you selected a module name before starting the New Deployment File wizard, then
the module and container attributes are filled in for you.
The name you assign to the container to hold the specified application. For running or
debugging in Studio, the top-level module must be in a container named default.
One of ENABLED, DISABLED, or DROP_TUPLES to specify the startup state of
enqueuing for this container. ENABLED is the default setting. If you specify
DISABLED, then enqueue attempts are actively refused and exceptions are thrown. If
you specify DROP_TUPLES, then tuples are silently dropped.
One of ENABLED, DISABLED, or DROP_TUPLES, as described above.
Use suspend=true to specify that the application in this container should start up
suspended. Specify false, the default, to have the application start running when the
container is added. When starting the server with sbd --suspend, you can use this
suspend="false" attribute to override the suspension. You can start or restart a
suspended container with the sbadmin resume command.
200
StreamBase References
Specify the absolute path (or a path relative to the running location of the sbd server)
to a directory to contain the files that implement all disk-based Query Tables for this
datadir
No
container. If unspecified, the container uses the --datadir location if specified on
the sbd command line, or the default temporary location if not.
application has the following child elements:
• Zero or more of: <extension-point-contents>
• Zero or more of: <module-parameters>
• Zero or more of: <trace>
<module-parameters>
This element can be a sub-element of both <application> and <extension>. Use it to specify the
value of one or more parameters to be passed to the top-level application module in the current container.
There are several ways in StreamBase to pass parameters to modules, but using this element in a deployment
file or server configuration file is the only method that allows parameter values to be enciphered. See Using
Module Parameters for details of passing module parameter values.
module-parameters supports one or more of the <parameter> child element.
<parameter>
Use this element to specify the name and value of a parameter to be passed to the top-level module in the
specified container. You can specify param as an alias for parameter.
Attribute Required
Description
name
yes
Parameter label that can be used in an expression.
Set to "true" to specify that the contents of the current value attribute were
enciphered with the sbcipher command. This allows you to specify private values
enciphered no
such as passwords and user names, yet not have the values appear as clear text in the
configuration file. For further information, see Enciphering Passwords and Parameter
Values.
value
yes
Value to which the parameter is to be resolved.
See String Values in Parameters for StreamBase Systems' recommended policy on quoting string parameters.
<extension-point-contents>
The <extension-point-contents> element contains zero or more <extension-point> child
elements.
<extension-point>
Each <extension-point> has one attribute, target-id:
Attribute Required
Description
target-id yes
The Extension Point ID for an Extension Point operator in a module loaded in the
container for this application, as specified in the Extension Point ID field in the
Modules tab of the Properties view of an Extension Point operator whose module
instances are defined externally. The target-id must exactly match such an
Extension Point ID. Extension Point IDs are container-scoped and must be unique
<application>
201
StreamBase References
among all Extension Point operators in all modules loaded in the same container.
You can use Ctrl+Space in the Deployment File Editor to pop up a list of the
available Extension Point IDs in modules in the module search path.
The target-id specifies an extension child element, which must be present in the file.
The <extension-point> element contains zero or more <extension> child elements.
<extension>
Use the <extension> element to specify modules that implement the interface in an Extension Point
operator for this application module. This element has the following attributes:
Attribute Required
Description
The module ID assigned to this module. The module ID is used in your application's
name
yes
logic as a handle to pass to an Extension Point component's input stream for dispatch
using the Name dispatch style.
The name of an EventFlow or StreamSQL module in the current module search path.
module
yes
Specify the module name only. You can use Ctrl+Space in the Deployment File
Editor to pop up a list of the available modules in the module search path.
See Using the Extension Point Operator and Using Interfaces with Extension Points for further information.
Each <extension> may have a <module-parameters> element that implements the extension point's
interface. The <module-parameters> element of <extension> can contain the same kinds of
elements as the <module-parameters> element of <application> does.
<trace>
Use this element to configure runtime tracing. Remember that these settings do not enable tracing, they only
configure tracing when it is set up and enabled. Tracing does not occur unless you set up StreamBase Server
for it and tracing is enabled. To set up for tracing, set the system property
streambase.codegen.trace-tuples or environment variable
STREAMBASE_CODEGEN_TRACE_TUPLES to true, as described in Runtime Tracing and Creating Trace
Files.
If the setup conditions are met, then tracing is enabled by default when the application starts. You can disable
tracing at runtime with sbadmin modifyContainer containerName trace false. In that case,
re-enable tracing with sbadmin modifyContainer containerName trace true. As soon as
you stop tracing, all trace files are closed.
The element has the following attributes:
Attribute
Required Default
traceStreamPattern No
none
traceFileBase
none
<extension-point>
No
Description
Specify a regular expression pattern in the format of
java.util.regex.Pattern. The pattern limits tracing to the operators
and streams whose name matches the pattern. If not specified,
tracing is active for all operators and streams in the application.
By default, trace output is written to StreamBase Server's console.
To redirect trace output to a file, specify traceFileBase with a
202
StreamBase References
basename argument.
There is one trace file generated per parallel module. Specify a
string to serve as the basename for trace files. Trace file names
are generated as basename+containername.sbtrace. For
modules running with parallel execution enabled, the module's path
becomes part of the trace file name:
basename+containername.modulepath.sbtrace.
traceOverwrite
No
false
traceCompress
No
false
traceBuffered
No
true
Tracing also creates a second file with extension
.sbtrace.meta. This file, in XML format, contains the
equivalent of the output of sbc describe. This file is automatically
used by the Trace Debugger perspective when reading and
displaying .sbtrace files.
Either true or false. Set to true to cause tracing to overwrite
all trace files on Server restart. By default, new trace information is
appended to existing trace files for each traced container.
Either true or false. Set to true to specify that the generated
trace file is to be compressed with gzip. If true, the trace file's
extension becomes .sbtrace.gz. Compressed trace files are
readable by Studio's Trace Browser perspective.
Either true or false. When set to false, the output trace file is
flushed on every trace line. This slows down performance
considerably, but makes it easier to use tracing as part of debugging
a live application. When set to true, the default, tracing output is
buffered before the trace file is written, to minimize tracing's drag
on performance.
Example:
...
<application container="default" module="BestBidsAsks.sbapp">
<trace traceStreamPattern="Bids" traceFileBase="trace_"
traceOverwrite="true" traceCompress="true" />
</application>
...
<container-connections>
Use this element to specify a set of one or more container connections. See Container Connections to
understand the types and uses of connections between containers.
The <container-connections> element (plural) supports one or more
<container-connection> elements (singular).
See the deployment file example above. You can establish container connections in several other ways, as
described in Specifying Container Connections.
<trace>
203
StreamBase References
<container-connection>
Use this element to specify a single connection between containers. The <container-connection>
element has the following attributes:
Attribute
Required
dest
Yes
source
Yes
synchronicity No
where
No
Description
The entity (usually an input stream) in one named container that will consume the
output of the connected source container.
For both dest and source attributes, you usually specify a StreamBase
component path in the form
container-name.module-name.stream-name. If required by your
application, you can also specify a full StreamBase URI to a container in remote
server, including remote connection parameters.
The entity in another named container (usually an output stream) that will send the
data to the destination container.
Either "ASYNCHRONOUS" (default) or "SYNCHRONOUS". See Synchronous
Container Connections.
Specifies a predicate expression filter to limit the tuples that cross to the
destination container. The expression to enter must resolve to true or false, and
should match against one or more fields in the schema of the connection's stream.
Back to top ^
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
<container-connection>
204
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference
StreamBase Command Reference
This topic provides links to reference descriptions for all the StreamBase tools and commands run at the
command prompt.
On Windows, run StreamBase utilities in a StreamBase Command Prompt, not a standard Windows command
prompt.
On UNIX, run StreamBase tools in a shell terminal window. UNIX users can access the manual page for each
command by entering man command-name at the shell prompt.
Contents
sbadmin â starts the StreamBase Administration Client
jsbadmin â starts the StreamBase Administration Client, Java implementation
sbargen â runs the StreamBase archive generator
sbbundle â Creates StreamBase application bundles.
sbc â starts the StreamBase client to send commands to a running server
jsbc â starts the StreamBase Client, Java implementation
sbcipher â enciphers text or generates cipher keys for use in StreamBase Server configuration files
sbconfutil â Shows as a single file the merged results of multiple configuration file fragments.
sb-config â a tool to determine and set StreamBase-related compiler and linker flags
sbfeedsim â starts the StreamBase Feed Simulator.
sbfeedsim-old â starts the StreamBase feed simulator for legacy feed simulator files.
jsbclientgen â Generates a simple Java dequeue client for the running StreamBase application
sbhelp â starts StreamBase Help Viewer
sb-install-zing-system-support â verifies presence of Azul Zing JDK and installs it
sb-manage-zing-system-support â starts, stops, and provides status of Zing JVM
sbmanager â starts the StreamBase Manager
sbmonitor â starts the StreamBase Monitor utility
sbprofile â Runs the StreamBase profiler to produce formatted statistics about operators and queues in a
running server.
sbproxy â starts the StreamBase Proxy server
sbrecord â Records data enqueued onto all Input Streams
sbd â the StreamBase event processing server
sbstudio â starts StreamBase Studio
StreamBase Command Reference
205
StreamBase References
sbtest â runs a unit test defined in a StreamBase test file
sbunit â runs a StreamBase JUnit test defined in a Java JUnit class
sburi â Describes the StreamBase URI format and its shortcut forms.
sbuseradmin â runs the StreamBase authentication system user management tool
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
StreamBase Command Reference
206
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbadmin
sbadmin
StreamBase Administration Client â
starts the StreamBase Administration Client
SYNOPSIS
sbadmin [OPTIONS] [COMMAND]
DESCRIPTION
The sbadmin command starts the StreamBase Administration Client, which lets you perform StreamBase
administration tasks such as addContainer, suspend, resume, and shutdown.
You can optionally limit the use of sbadmin commands to certain designated user accounts by enabling a
feature of StreamBase authentication. See the sbuseradmin reference page for more information.
Use the sbc command rather than sbadmin for non-administrative commands.
Suspending and Resuming
You can use sbadmin suspend to request suspension of an application, a container, an adapter, a Java
operator, or an embedded adapter. However, not all StreamBase objects respond to a suspend request. If the
specified target cannot be suspended, the command succeeds silently, but the specified target continues to run.
In general, embedded adapters supplied by StreamBase respond to suspend requests, while global operators
and adapters supplied by StreamBase are not subject to suspension. The suspend and resume commands are
best used with custom operators and adapters you write to extend StreamBase functionality, and for which
you define suspend state behavior.
The container suspend state is a flag to which custom operators and adapters may respond, depending on how
sbadmin
207
StreamBase References
they are coded. Streams ignore the suspend state and instead respond to enqueue and dequeue
STREAMSTATUS as set by sbadmin modifyContainer --enqueue= and --dequeue= commands, described
below. Suspending a container applies the suspend state to all operators and adapters, but if there are none in
the container that have a specific suspend state defined, then the application behavior does not change when
receiving a suspend command.
Shutting Down and Restarting Containers
The sbadmin shutdown containername and sbadmain removeContainer containername
commands are equivalent and you can use either one. Shutting down a container stops the execution of all
operators in the container as soon as the current tuple and any pending JDBC operations complete processing.
The current tuple only needs to enter an output queue to be considered complete. The shutdown process then
unloads all operators, queues, and connections from memory. Once shut down, a container is no longer
present in the server and cannot be restarted or reloaded with an application module. You can, however, add a
new container with the same name.
Restarting a container is accomplished by shutting down the container and re-adding a new container with the
same name.
If you are shutting down a container with a container connection (for example, if the output stream of one
container is the input stream of another container), remove or shut down the containers using the reverse order
in which they were added to the server.
Container Connections
You can set up connections between containers when you add a container with the addContainer command
or when you modify existing containers with the modifyContainer addConnection command. Container
connections can be one of the following types:
--Stream-to-stream connections, where an output stream in one container connects to an input stream in
another container. These can be asynchronous (default) or synchronous.
--JMS-mediated connections, where an output stream in one container connects to a Java Messaging
Service server, then an input stream in another container connects to the same JMS server. This is a
stream-to-stream connection that passes through a JMS server to insure reliable delivery of messages.
--CSV file connections, where an input or output stream in a container is connected to a URI specifying the
path to a CSV file.
The syntax for expressing all forms of container connections is always destination=source, like an
assignment statement in some programming languages.
See Container Connections in the Administration Guide for more on container connections.
Runtime Tracing
When enabled, runtime tracing writes tuple trace information to StreamBase Server's console or to a trace file,
one per container. The default trace information is a single timestamped line per tuple. Each tuple is shown as
received at each operator and stream in the application. Trace files can grow quite large very quickly, so
Suspending and Resuming
208
StreamBase References
runtime tracing is best used only for short bursts, for debugging only, to follow a tuple's progress through an
application.
You can limit the traced operators and streams by using a regular expression to name the components of
interest.
You must set up runtime tracing with a system property or environment variable. Once set, you enable and
disable tracing using subcommands of sbadmin addContainer or sbadmin modifyContainer, or using the
trace element in the Server configuration file. See Runtime Tracing and Creating Trace Files for details on
setting up for tracing, and using the runtime tracing configuration options.
OPTIONS
-h [subcommand], --help [subcommand]
Displays usage text for the sbadmin command, then exits. If given a subcommand name as an
argument, displays help for the specified subcommand, then exits. The subcommand argument can
also precede the -h or --help:
sbadmin -h dequeue
sbadmin deq --help
-o filename
Redirects all non-error output to the specified file.
-p TCP-port
Specifies the port number on localhost for the StreamBase Server to communicate with. This is a
shortcut alternative to specifying the full URI with -u in cases where the server is running on
localhost but on a port other than the default 10000. Thus, the following lines are equivalent:
sbadmin -u sb://localhost:9900 listConnections
sbadmin -p 9900 listConnections
Note
The -p option is not supported for applications that have StreamBase authentication enabled (because
there is no way to specify a username and password), or in conjunction with the multiple URI syntax.
-u uri
Specifies the URI of the StreamBase Server to communicate with. See the sburi page of the Reference
Guide (or see sburi(5) at the UNIX shell prompt) for a discussion of the URI format and its shortcuts.
The URI can also be set using the STREAMBASE_SERVER environment variable.
-w waitMS:retryMS
Specifies a wait time waitMS in milliseconds for the command to continually attempt to connect to
StreamBase Server, with an optional retry period retryMS, also in milliseconds. The default
retryMS is 250 milliseconds. Use this command to start sbc enqueue and dequeue commands
before starting StreamBase Server. The sbc command waits and connects when the is server is ready.
--version
Prints version information and exits.
Runtime Tracing
209
StreamBase References
COMMANDS
addContainer containerName { file.sbapp | file.ssql | file.sbar } [
container-expression1 container-expression2 ... ] [--enqueue=STREAMSTATUS]
[--dequeue=STREAMSTATUS] [--traceStreamPattern=pattern] [--traceFileBase=basefilename]
[--traceOverwrite] [--traceCompress] [--traceBuffered=[true|false]] [--suspend] [--moduleSearch=path]
[--datadir=path] [--parameter=param=value ] [--verbose]
Adds a container to the running sbd server process, assigns the new container a name, and specifies
an application file to run in the context of the new container. The application file formats accepted are
EventFlow (extension sbapp), StreamSQL (ssql), and precompiled archive (sbar). For more on
precompiled StreamBase application files, see sbargen and Precompiled Application Archives.
When adding containers, you can optionally specify a connection between a stream in the container
you are adding to a stream in an existing container, as described in Container Connections. For each
container-expression, use the syntax destination=source, and include the container
name, stream name, and any intervening module names in the container. For example:
containerA.instream1=containerB.module1.outstream1
You can optionally enable or disable enqueuing or dequeuing to the container on startup. This
changes the enqueue or dequeue status for in-process adapters and for enqueue and dequeue clients.
The STREAMSTATUS values can be:
--ENABLED. This is the default.
--DISABLED. The enqueue or dequeue will actively refuse any enqueue or dequeue requests, and
throw an exception.
--DROP_TUPLES. The enqueue or dequeue will silently drop tuples.
When you interrupt queuing for an application running in a container, you also interrupt queuing for
any external clients, input adapters, and output adapters that were communicating with that
application. See Enabling and Disabling Enqueue or Dequeue for details.
Use the --trace* options to manage runtime tracing, as described in Runtime Tracing.
Use --suspend to specify that the application in this container should start up suspended. You can
start a suspended container with the sbadmin resume command.
Use --moduleSearch to specify an absolute or relative path to a directory containing StreamBase
application files that are called by this container's application as modules.
Use --datadir to specify an absolute or relative path to a directory to be used by this container to
hold the files that implement disk query tables for the application in this container.
Relative paths for --datadir and --moduleSearch are relative to the runtime location of the
sbd server, which is likely to be different between development and deployment environments. For
maximum portability, specify full absolute paths.
Use --parameter to specify module parameters for the container you are adding. See Using
Module Parameters for details.
With the --verbose flag, the addContainer command reports success instead of silently
returning.
COMMANDS
210
StreamBase References
addDeploy file.[sbdeploy | sbar] [--verbose]
Adds the module and container specified in a deployment file (or an archived deployment file) to the
running server. The deployment file must specify an application to run and container to run in, and
can optionally specify container connections, trace configuration, and module parameters. In general,
all the options you can specify with addContainer can also be declared in a deployment file. With
the --verbose flag, the addDeploy command reports success instead of silently returning.
getLeadershipStatus
Returns one of the strings LEADER or NON_LEADER to describe the leadership status of the specified
StreamBase Server.
getOperatorProperty operatorName [propertyName]
Displays a property or all properties for the named Java operator or embedded adapter. Optionally you
can request information about a specific property; otherwise, StreamBase displays all properties for
the Java operator or embedded adapter.
If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java
operator or embedded adapter with the appropriate container name. For example:
sbadmin getOperatorProperty containerB.MyJavaOperator
killAllConnections
Disconnects all connections from the sbd server.
killConnection connectionID
Disconnects the specified connection. Obtain the connectionID string from the first field returned
by an sbadmin listConnections command.
listConnections [listConnectionOption]
Lists all active client connections to the running StreamBase Server (sbd). For each connection, the
display shows:
id
The global connection ID assigned by the server to each connection. (Use this ID with the
killConnection command and the getClientIP() expression language function.)
peer, local
Client and server host name or IP address and port numbers.
memory
The size of the enqueue buffer.
subscriptions
The names of subscribed streams, if any.
dequeued, enqueued
The number of tuples currently dequeued and enqueued.
dequeuePackets, enqueuePackets
Tuples are not sent one at a time over the network but, by default, are batched into network
packets. These settings give you an idea of how many tuples per packet are enqueued or
received. It is a measure of the efficiency of the network protocol at a given time and is useful
to aid understanding performance when testing across the network. Low numbers mean more
network overhead per tuple. High numbers mean less.
protocolFamily
The network protocol version of the connected StreamBase Server, which increments in some
but not all major releases. StreamBase client programs such as sbc and sbadmin from an
older StreamBase release can always connect to servers from newer releases because of the
version proxying built into StreamBase Server. However, client programs from a newer
release can connect to older server releases only when they have the same protocol version.
The listConnections command supports the following options:
COMMANDS
211
StreamBase References
--current Shows active client connections currently conveying tuples.
--old Shows clients still running but disconnected from the server.
--all Shows both current and old client connections.
--clearOld Removes client connections that are running but disconnected from the server.
manageJdbcConnections close|count [datasource-name]
Lists the number of currently active JDBC connections and allows you to close a JDBC connection
without having to shut down the enclosing server or container. With either subcommand, close or
count, this command returns the current number of JDBC connections. Specify the case-sensitive
exact name of a data source as defined in a <data-source> element of the current server's
configuration file. If you do not specify a datasource-name argument, the close subcommand
closes the active JDBC connection.
modifyContainer container-name [[addConnection | removeConnection] container-expression1
container-expression2 ...] [--where "filter-expression"] [--enqueue=STREAMSTATUS]
[--dequeue=STREAMSTATUS] [trace [true | false ]] [--traceStreamPattern=pattern]
[--traceStreamPattern=pattern] [--traceFileBase=basefilename] [--traceOverwrite] [--traceCompress]
[--traceBuffered=[true|false]] [--verbose]
Adds or removes a container connection to a running container and/or changes the enqueue or
dequeue status of a container. The container connection syntax for the addConnection subcommand
and each container-expression is the same as for the addContainer command described
above. The values for STREAMSTATUS are the same as for the addContainer command above.
Use the trace option and its --trace* suboptions to manage runtime tracing, as described in
Runtime Tracing.
Use the --where option to specify a quoted predicate expression that limits the tuples sent over that
connection. The predicate expression must resolve to true or false, and should match against one or
more fields in the schema of the connection's stream. Since you can make more than one container
connection to the same stream, you can connect to one stream multiple times, with a different filter
predicate for each.
removeContainer containerName [--verbose]
Removes the specified container from the running sbd server process, and unloads the container's
module from memory. This command is equivalent to shutdown containername, described below.
With the --verbose flag, the removeContainer command reports success instead of silently
returning.
restart [ operatorName1 [ operatorName2 ... ] ]
Restarts one or more Java operators or embedded adapters in a server process that were previously
stopped with the shutdown command. You can separate multiple entities with a space.
If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java
operator or embedded adapter with its container name. For example:
sbadmin restart containerB.MyJavaOperator
restartContainer container-name
The container-name argument is not optional. Restarts the specified container that was
previously stopped with the shutdown command.
resume [ containerName | operatorName1 [ operatorName2 ... ] ]
Resumes a suspended StreamBase application, container, Java operator, or embedded adapter. You
can separate multiple entities with a space.
If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java
operator or embedded adapter with its container name. For example:
COMMANDS
212
StreamBase References
sbadmin resume containerB.MyJavaOperator
setLeadershipStatus [ NON_LEADER | LEADER ]
Changes the leadership status of the specified StreamBase Server as a member of a high availability
cluster. LEADER is the default status on server startup. Changes in leadership status are announced
on the system.control stream of the server.
setOperatorProperty operatorName propertyName value
Sets a property value for the specified Java operator or embedded adapter. Use sbadmin
getOperatorProperty to see the list of properties for a Java operator or an embedded adapter. If the
server is running multiple containers and you need to prevent a naming conflict, qualify the Java
operator or embedded adapter with its container name.
shutdown [ containerName | operatorName1 [ operatorName2 ... ] ]
Shuts down one or more StreamBase applications, containers, Java operators, or embedded adapters.
You can separate multiple entities with a space.
If you are shutting down a container with a container connection (for example, if the output stream of
one container is the input stream of another container), remove or shut down the containers using the
reverse order in which they were added to the server.
The commands shutdown containername and removeContainer containername are equivalent,
and both leave the server with no container by the specified name, and the container's module
unloaded from memory. To restart a container, you must shut it down or remove it, the add it to the
running server again as a new container.
If the server is running multiple containers with the same module, qualify the Java operator or
embedded adapter with its container name. For example:
sbadmin shutdown containerB.MyJavaOperator
suspend [ containerName | operatorName1 [ operatorName2 ... ] ]
Suspends a running StreamBase application, container, Java operator, or embedded adapter. You can
separate multiple entities with a space. If the server is running multiple containers and you need to
prevent a naming conflict, qualify the Java operator or embedded adapter with its container name. For
example:
sbadmin suspend containerB.MyJavaOperator
The specified target silently accepts the suspend command, but not all StreamBase objects can be
suspended, as described above in Suspending and Resuming.
[sbc commands]
For convenience, the sbadmin command also accepts all the sbc commands, as listed in the sbc
reference page, including status, list, enqueue, dequeue, describe, and typecheck. In
a deployment that uses the StreamBase user administration system to restrict access to the sbadmin
command, this feature allows authorized administrators to run the sbc commands with administrative
rights.
Note
When invoking one of the sbc command's subcommands, the sbadmin -u option accepts a
comma-separated list of URIs, where each URI specifies a different StreamBase Server in a high
availability cluster. See the sburi page in the Reference Guide for details.
Note
213
StreamBase References
FILES
There is no configuration file for sbadmin. Enabling or changing the StreamBase authentication setting for
sbadmin commands is done by editing the sbd.sbconf configuration file, which contains an
authentication section.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
SEE ALSO
sbc
sbd
syslog(3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
FILES
214
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > jsbadmin
jsbadmin
StreamBase Administration Client â
starts the StreamBase Administration Client, Java implementation
SYNOPSIS
jsbadmin [OPTIONS] [COMMAND]
DESCRIPTION
The jsbadmin command runs a Java implementation of the StreamBase administration client utility,
sbadmin. Both commands let you perform StreamBase administration tasks such as addContainer, suspend,
resume, and shutdown.
OPTIONS
With a few exceptions, the jsbadmin command has the same options as the sbadmin command, as described
in sbadmin. The exceptions are:
No space after -u or -p
For jsbadmin, there must be no space between -u and the following URI, and no space between -p
and the following port number:
jsbadmin -usb://localhost:10000 listConnections
jsbadmin -p9900 listConnections
enqueue and dequeue support the --json option
The jsbadmin command supports running all jsbc subcommands, in the same way that sbadmin
supports all sbc subcommands. When jsbadmin invokes the jsbc enqueue and dequeue
subcommands, it supports the --json option. For dequeue, this prints all tuples in the form of a
JSON object (as defined on http://www.json.org) instead of the default CSV format. For enqueue,
--json specifies that the tuples to be enqueued are in JSON object format. Use this option after the
enqueue or dequeue subcommand:
SEE ALSO
215
StreamBase References
jsbadmin enqueue --json InputPort
jsbadmin dequeue --json OutputPort
-J option supported
The jsbadmin command accepts the -J option, but sbadmin does not.
-J jvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs
this jsbadmin command. Use this option to specify temporary settings that affect only the
current invocation of jsadmin. You must specify multiple -J options to specify multiple
JVM arguments.
A space between the -J and its argument is optional. Use the full option syntax for
jvm-option that you would use at the Java command line, including the initial hyphen. For
example, specify -J-Dstreambase.log-level=2 to increase the log level for this
invocation of jsadmin.
Your jvm-option argument might require surrounding quotes, depending on the characters
it contains and the shell you are using. However, do not use quotes to escape the spaces
between separate JVM arguments; instead use separate -J options. For example:
-J-Xms512M -J-Xmx2G
No arguments for -h and --help
Unlike the sbadmin command, this jsbadmin command's -h and --help options do not take
subcommand arguments.
COMMANDS
The jsbadmin command accepts the same subcommands as the sbadmin command. See sbadmin.
FILES
There is no separate configuration file for jsbadmin. Enabling or changing the StreamBase authentication
setting for jsbadmin commands is accomplished by editing <authentication> element of the server
configuration file.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
OPTIONS
216
StreamBase References
the standard messages), and 2 (which adds DEBUG messages).
SEE ALSO
sbadmin
sbc
sbd
syslog (3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
ENVIRONMENT
217
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbargen
sbargen
StreamBase Archive Generator â
runs the StreamBase archive generator
SYNOPSIS
sbargen [OPTIONS] [app-name.[sbapp|ssql|sbdeploy]] {output.sbar}
DESCRIPTION
Compiles a top-level StreamBase application and returns a precompiled application archive file with .sbar
extension.
When you start StreamBase Server with an EventFlow or StreamSQL application argument, the server
compiles the application on the fly, then runs the compiled application. By contrast, when you start a server
with a precompiled archive file as an argument, the server runs the application immediately.
Specify the name of a top-level EventFlow or StreamSQL application file, or a deployment file that specifies
an application, as the optional first sbargen argument. If not specified, sbargen reads the application from
standard input. You must specify an output file name argument to contain the precompiled application
archive.
StreamBase Server honors precompiled application archives compiled with the exact same release of
StreamBase, and refuses to run applications generated with the sbargen commands from another StreamBase
release. Use sbargen --version and sbd --version to determine the respective release numbers.
OPTIONS
-f conf-file
Specifies a server configuration file to use when compiling the application.
-h, --help
Displays help, then exits.
SEE ALSO
218
StreamBase References
--if-modified
Check the target .sbar file's dependencies, and only rebuild the target if it is older than its
dependencies. By default, this option does not consider files whose names match the following
regular expression patterns as dependencies:
.*\.log
.*\.bak
.*~
#.*#
You can customize the list of exclusion patterns with the --exclude-pattern option.
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM running the
archive generation process. Use this option to specify temporary settings that affect only the current
invocation of sbargen. You must specify multiple -J options to specify multiple JVM arguments.
For example, specify -J-Xmx2G. Use the full option syntax for jvm-option that you would use at
the Java command line, including the initial hyphen. For example, specify
-J-Dstreambase.log-level=2 to increase the log level for this invocation of sbargen.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
-m module-directory, --module-search module-directory
Specifies a directory path in which to search for modules referenced by the specified application.
â P paramName=paramValue, â -parameter paramName=paramValue
Specifies a module parameter to pass to the top-level application module at runtime.
-q
Suppresses compiler warnings.
-v, --version
Returns the StreamBase release number.
-X regex-pattern, --exclude-pattern regex-pattern
Specifies a regular expression pattern for files to ignore when considering changed dependency files
with the --if-modified option. You can specify this multiple times to specify multiple patterns.
This option replaces the default patterns shown above for the --if-modified option. For
example, if you mean to append a fifth pattern, you must re-specify the four default patterns to
continue using them.
ENVIRONMENT
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
OPTIONS
219
StreamBase References
SEE ALSO
sbadmin
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
SEE ALSO
220
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbbundle
sbbundle
StreamBase Application Bundle Generator â
Creates StreamBase application bundles.
SYNOPSIS
sbbundle {-a appname.[sbapp|ssql|sbdeploy]} [-f config.sbconf] [-I|--include
file1[@path1],file2[@path2],...] [-o] [-c] [-i ignorelist] [-Jjvm-option]
{filename.sbbundle}
sbbundle {-a appname.[sbapp|ssql|sbdeploy]} [-p|-P projectdir1[:;]projectdir2[:;]...]
[-V|--classpath-variable name=path...] [-I|--include file1[@path1],file2[@path2],...] [-o] [-c]
[-i ignorelist] [-Jjvm-option] {filename.sbbundle}
sbbundle {-x sbconf-out} [-Jjvm-option] {filename.sbbundle}
sbbundle {-r sbconf-in} [-Jjvm-option] {filename.sbbundle}
DESCRIPTION
Use sbbundle to create or modify a StreamBase application bundle file, which must have the .sbbundle
extension. A bundle file is an archive file that contains a deployable application environment. That is, it
contains the collection of files needed to deploy and run a StreamBase application on StreamBase Server on a
supported platform. A typical use for bundle files is to package a StreamBase application along with all
required modules and resource files so that it is ready for deployment.
To run a bundled application, pass a bundle file as an argument to the sbd command that starts StreamBase
Server. For example:
sbd myapplication.sbbundle
In general, if you can successfully run an unbundled application file or deployment file from the command
line with the sbd command, then you can create an application bundle for that application or deployment.
sbbundle
221
StreamBase References
To create a new bundle, you must specify one of the following starting points for the bundler to parse:
--A top-level EventFlow or StreamSQL application file.
--A StreamBase deployment file (.sbdeploy) that specifies a top-level module to run in its
<application> element.
--A server configuration file (.sbconf file) that specifies a top-level application to run in its
<application> element. (This is a deprecated configuration.)
The bundling process determines the necessary files to bundle by reading the top-level EventFlow or
StreamSQL application specified directly or specified in a deployment or configuration file. The file is parsed
to determine any modules called and resources referenced. If a server configuration file is provided, it is
parsed by the bundler to determine the application's current requirements. All definitions in the configuration
file are preserved, and any referenced JAR files or other native resource files are included in the bundle.
Just as with unbundled StreamBase applications, you can create and run an application bundle on any
supported machine configuration. The version of StreamBase and of any called resources must be the same on
the machine that runs the bundle as on the machine that generates the bundle. The StreamBase version is
specific down to the minor release number, which is the second position in the release number. Thus, an
.sbbundle file created with the sbbundle command from StreamBase release 7.0 can only be run with the
sbd server from release 7.0.
If a specified configuration file references Java resources in <jar> and <dir> elements, those resources are
included in the bundle, and the bundle's configuration file is rewritten to specify the bundled path of those
resources.
If the application being bundled references a JDBC data source, then the same JDBC URI to access that data
source must be accessible from the server host that runs the bundle. As an alternative, you can specify the path
to a test data source during development, and bundle the application with a configuration file that references
the test data source. You can later extract the configuration file from the bundle using the -x option, edit the
JDBC URI to point to a production data source, then replace the edited configuration file back into the bundle
using the -r option.
The bundling process supports multiple containers and container connections if they are specified in a
deployment file or a server configuration file. The top-level application specified with the -a option is always
bundled to run in the container named default.
The following resource types are NOT included in the bundle:
--Global operators and adapters.
--Native code, such as C++ plug-ins in the form of native DLL or .so library files.
For more information, see What Files Do Not Get Bundled on the Application Bundling page in the
Administration Guide.
OPTIONS
-h, --help
Displays usage text.
-a appname.sbapp | appname.ssql | appname.sbdeploy
DESCRIPTION
222
StreamBase References
To create an application bundle, you must specify either -a or -f or both. Use -a to specify a
top-level EventFlow or StreamSQL application file to be the primary application in the bundle; or
specify the name of a StreamBase deployment file that in turn specifies a top-level module in an
<application> element. The specified application is bundled to run in the default container.
-c
Includes in the bundle a precompiled application generated from the specified top-level application
file. This option cannot be used to specify an existing .sbar file; it always generates a new
precompiled application.
-i ignorelist
Specifies a comma-separated list of path names to ignore when generating a bundle. This is especially
useful when working on a version-controlled working directory, to exclude the version control
system's metadata files or directories from the bundle. For example, sbbundle -i .svn ....
-I file1@path1,file2@path2, --include file1@path1,file2@path2
Specifies a comma-separated list of files or folders to copy into the bundle. Files are copied to the
bundle's /resources folder when no path is specified, or to the specified directory path resolved
relative to the bundle root. Specifying a directory for the file argument is equivalent to specifying
every file immediately contained within that directory. Use this feature to specify resource files
needed by third-party libraries used in your application, including logging system configuration files,
or to specify files used by adapters or operators that are not loaded normally in StreamBase. When
used in conjunction with -p|-P, this option appends to and supplements the configuration
determined by examining the specified Studio project directory.
-f sbd.sbconf
To create an application bundle, you must specify either -a or -f or both. Specifies the name of a
StreamBase Server configuration file to include in the bundle to control the runtime behavior of the
primary application in the bundle. If you specify both -a and -f, the configuration file controls the
application named with the -a option. If you specify only -f, the configuration file must contain an
application element that gives the path to a top-level EventFlow or StreamSQL application file.
The preferred configuration is to specify a StreamBase deployment file with -a instead of -f without
-a.
-J jvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM running the
bundle generation process. Use this option to specify temporary settings that affect only the current
invocation of sbbundle. You must specify multiple -J options to specify multiple JVM arguments.
A space between the -J and its argument is optional. Use the full option syntax for jvm-option
that you would use at the Java command line, including the initial hyphen. For example, specify
-J-Dstreambase.log-level=2 to increase the log level for this invocation of sbbundle.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
-o
Overwrites any existing StreamBase bundle file of the same name.
-p projectdir1[:;]projectdir2[:;]..., -P projectdir1[:;]projectdir2[:;]...
Cannot be used in conjunction with -f. Use one of these options to emulate the automatic inclusion
of Studio project metadata in the bundle, in the same way as the Studio bundler. Specifies a
colon-separated list (UNIX) or semicolon-separated list (Windows) of relative paths to Studio project
directories, whose Studio metadata is to be considered when generating the bundle. Studio project
metadata includes the Java build path, module search path, resource search path, any project
references, and other such information. With this option, the bundler generates a server configuration
file for inclusion in the bundle based on the metadata of the specified projects. When used with
OPTIONS
223
StreamBase References
uppercase -P, each specified project directory is recursively scanned for Studio project directories.
-V name=path ..., --classpath-variable name=path...
Define Java Classpath Variable for Studio-based project bundling. Arguments can be repeated to
define additional variables. Remember to escape any spaces in your path when invoking this from the
command shell.
-r sbconf.in
Specifies the name of a server configuration file to replace the configuration file currently in the
bundle. Use this feature in conjunction with the â x option to extract the configuration file from a
bundle, edit it to specify deployment-specific information, then replace the edited configuration file.
Only replace the configuration file with one that was extracted with â x from the same bundle.
--v
Displays version information and exits.
-x sbconf.out
Extracts the configuration file from an existing bundle, and writes it to the path and name you specify
as the argument to â x. Use this feature as described above for the â r option. Do not edit any
path attributes in the extracted configuration file.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
OPTIONS
224
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbc
sbc
StreamBase Client â
starts the StreamBase client to send commands to a running server
SYNOPSIS
sbc [OPTIONS] [COMMAND] [COMMAND-OPTIONS]
DESCRIPTION
sbc starts the StreamBase client utility, which lets you send requests to a running StreamBase Server (sbd).
For example, the command sbc list streams sends a request to the server for a list of available streams.
StreamBase users can submit sbc commands, but some may require authentication. To specify a username and
password, use a URI of the format described in the sburi page of the Reference Guide.
For administrative commands, use the sbadmin command rather than sbc.
OPTIONS
-h [subcommand], --help [subcommand]
Displays usage text for the sbc command, then exits. If given a subcommand name as an argument,
displays help for the specified subcommand, then exits. The subcommand argument can also precede
the -h or --help:
sbc -h dequeue
sbc deq --help
-o filename
Redirects all non-error standard output to the specified file.
-p TCP-port
Specifies the port number on localhost of the StreamBase Server instance to communicate with.
This is a shortcut alternative to specifying the full URI with -u in cases where the server is running
sbc
225
StreamBase References
on localhost but on a port other than the default 10000. Thus, the following lines are equivalent:
sbc -u sb://localhost:9900 listConnections
sbc -p 9900 listConnections
Note
The -p option is not supported for applications that have StreamBase authentication enabled (because
there is no way to specify a username and password), or in conjunction with the multiple URI syntax.
-u uri
Specifies the URI of the StreamBase Server instance to communicate with. See the sburi page of the
Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion of the URI format and the
available shortcuts. The URI can also be set using the STREAMBASE_SERVER environment variable.
Note
When used with the status, enqueue, and dequeue subcommands, the sbc command's -u
option accepts a comma-separated list of URIs, where each URI specifies a different StreamBase
Server in a high availability cluster. See Multiple URI Syntax for HA Scenarios in the Reference
Guide for details.
-w waitMS:retryMS
Specifies a wait time waitMS in milliseconds for the command to continually attempt to connect to
StreamBase Server, with an optional retry period retryMS, also in milliseconds. The default
retryMS is 250 milliseconds. Use this command to start sbc enqueue and dequeue commands
before starting StreamBase Server. The sbc command waits and connects when the is server is ready.
The following example waits 20 seconds before giving up on connecting to the server, retrying every
half second: sbc -w 20000:500 dequeue
--version
Prints version information and exits.
COMMANDS
checkLicense feature-name
Use this command under the guidance of StreamBase Technical Support, who will provide the
feature-name string.
dequeue [OPTIONS] [stream-names...]
Dequeues data from one or more streams to stdout. This command can be abbreviated as deq.
By default, outputs comma-separated values in the standard CSV format described in RFC 4180.
Fields containing commas are enclosed by default in double quotation marks.
stream-names
The names of streams from which to dequeue. The default is to dequeue from all output
streams (that is, all streams that do not feed into the input ports of other operators). You can
specify a simple stream name as reported by sbc list, or you can specify a stream name
qualified by its container name. Thus, the following commands are equivalent:
sbc deq BestAsks
OPTIONS
226
StreamBase References
sbc deq default.BestAsks
If the running application is structured with modules, and one or more output streams in a
module were declared public (that is, the streams were exposed for dequeuing regardless of
module depth), then you can also dequeue from such streams. In this case, qualify the stream
name with its containing outer module name, then the inner module name, then stream name.
For example:
sbc deq outer.inner.innerOutputStream
If you need to distinguish identically named streams in separate containers, you can prefix the
container name of interest:
sbc deq container2.outer.inner.innerOutputStream
-a | --as logical-name
Use logical-name as a logical name from the preceding stream specified on the sbc
command line. No two logical names can be identical.
--all[=input|output]
Dequeue from all streams in the specified container (including input, intermediate, and output
streams), or in the default container if unspecified. Use the -u option to specify a particular
container; -u is required if the running application does not have a primary container named
default. With the optional modifier =input, streams are limited to all input streams.
Likewise, specifying --all=output shows all the output streams. The default, without an
= modifier, is to show both input and output streams.
--all-containers[=input|output]
Dequeue from all streams in all containers. Use the -u option to specify a particular
container; -u is required if the running application does not have a primary container named
default. This option takes the same =input and =output modifiers as --all.
-d delim
Use delim (a single character, or the literal string tab) as a field separator. The default field
separator is a comma.
--header
Write a header at the beginning of the output. This option is valid only when exactly one
stream is specified.
--info
Write out informational lines, such as when all streams have been subscribed to.
Informational lines begin with an asterisk and two quotation marks (which is an invalid CSV
line) so they can be distinguished from other output.
-q quotechar
Use quotechar (a single character) as a quotation mark. The default quotechar is a
double quote.
-v
Output human-readable tuples, showing the stream name, a tuple ID number, then each field
name and value. The tuple ID number reflects the zero-based sequence number of this tuple
since the queried sbd server started. For example, the following line might be output from sbc
deq with its default settings: 33620,NCC,30.5. With the -v option, this same line shows
as follows:
BestAsks: (tupleid=643,time=33620,symbol="NCC",best_ask=30.5)
-w | --where "condition"
COMMANDS
227
StreamBase References
Apply the expression condition as a predicate expression to narrow or select data from the
preceding stream specified on the sbc command line. For example, for a stream named
outstream that has a field named symbol:
sbc deq outstream --where "symbol='IBM'"
describe name...
Outputs the EventFlow XML description of one or more components in the running application.
Specify each component name separated by spaces. You can use container-qualified and
module-qualified names. You cannot specify a query table as name, but you can enter the name of a
Query operator connected to that table, in which case the returned description includes the query plan
for that operator.
enqueue [OPTIONS] [stream-name]
This command can be abbreviated as enq. Reads data from stdin and enqueues it to
stream-name.
By default, enqueue expects lines of comma-separated values in the standard CSV format described
in RFC 4180. Fields containing the field separator character (comma by default) must be enclosed in
double quotes. For sbc enqueue, StreamBase extends the CSV format to support list and tuple data
types as follows:
Extensions for list fields
To specify a field of type list, enclose the list in quoted square brackets. For example: "[1,
2, 3]" or "[alpha, beta, gamma]". You only need to quote each element of a
list(string) if an element contains the field separator character (comma by default).
Extensions for tuple fields
To specify a field of type tuple, use quotes to surround the tuple field. For example, for the
schema string, tuple(int, int, int), enter lines in the following format:
IBM, "12, 45, 87"
For deeper nesting, use doubled quotes to specify a literal quote character. For example, for
the schema double, tuple(string, tuple(int, int, int)) (which has two
fields, a double and a tuple), enter lines like the following:
3.14159, " IBM, ""12, 45, 87"" "
To enqueue a no-fields tuple with sbc enqueue, send a line consisting of only white space, such as a
space or tab character. A no-fields tuple is the input format you send to an input stream defined with
an empty schema, as described in Using Empty Schemas.
stream-name
The name of the stream on which to enqueue data. If no stream name is provided, the first
input field for each line on stdin must be the stream name to receive that input line.
If the running application is structured with modules, and the definition of an input stream in
a module exposes that stream for enqueuing regardless of module depth, then you can
enqueue to such a stream. In this case, qualify the stream name with its containing outer
module names. For example:
sbc enq outer.inner.innerInputStream
COMMANDS
228
StreamBase References
If you need to distinguish identically named streams in separate containers, prefix the
container name of interest:
sbc enq container2.outer.inner.innerInputStream
-b size
Use size to indicate the number of tuples to buffer. The default is no buffering.
-d delim
Use delim (a single character, or the literal string tab) as a field separator. The default field
separator is a comma.
-f field1, field2...
Specify the order of fields in the input. The first column in the input is field1 in the input
stream, and so on. This option ismuch the same only valid when a stream name is provided.
-i interval
Use interval to specify the enqueuing flush interval in milliseconds. If buffering was not
enabled, defaults to 250 milliseconds.
-n null-string
Consider a field to be null when null-string is specified as a value. The default string to
indicate a null field is null.
-q quotechar
Use quotechar (a single character) as a quotation mark. The default quotechar is a
double quote.
getDynamicVariable dynvar-path
The argument is a StreamBase path to a dynamic variable in the form
container.module.dynvar-name.
list [-a] [-c] [-C] [-m] type...
Lists entities available on the running sbd server. type may be streams, schemas, operators,
input-streams, output-streams, container-connections, or tables (or the
singular forms of these keywords). By default, container names and module names are omitted. Use
the -c or -m flags to include either or both.
-a
Produces a list of all streams, containers, schemas, and tables in the connected application,
including intermediate streams, but not including any system streams. The -a list option
presumes the -c option, and always shows container names.
-c
Includes container names as a prefix to the entity names in the resulting list.
-C container-name
Lists the streams and operators for the specified container. For example, the following
command lists the contents of the container named mainapp on the default server and port:
sbc list -C mainapp
-m
Includes module references. Modules can be explicitly referenced in the application, or
referenced implicitly by StreamBase. That is, when a component runs in multiple parallel
regions, StreamBase creates an implicit module for each running instance.
readTable [OPTIONS] table-path [-w | --where predicate]
Dumps the contents of Query Tables and Materialized Windows in the running application, including
Placeholder Query Tables. You must specify the path to a table in the running application, which can
be determined with sbc list tables; there is no default. The simplest invocation, without options, reads
and displays ten rows from the specified table.
COMMANDS
229
StreamBase References
sbc readTable myQT
For tables within modules, prefix the module names:
sbc readTable top.middle.bottom.myQT
You can restrict the output to table rows that match a predicate expression. If used, the -w or
--where clause must follow the table-path. For example, for table named SimpleTable that
contains a field named city:
sbc readTable SimpleTable -w city=="'Boston'"
or
sbc readTable SimpleTable -w city==\"Boston\"
The predicate expression must contain at least one field from the specified table's schema, and must
resolve to Boolean true or false.
The readTable options, which must follow the readTable keyword and must precede the table path
name, are similar to options provided for the enqueue and dequeue commands:
--all | --limit count
Read and display all table rows with --all or specify a row limit. The default is
--limit 10.
-d delim
Use delim (a single character, or the literal string tab) as the displayed field separator; the
default is a comma. This option only affects the display of table rows, not how they are read.
--header | -v
These options are mutually exclusive; by default, both options are omitted. Specify
--header to write a header line at the beginning of the output that shows each field name,
like the following example:
key,city,papers
3,Boston,"[The Globe,void]"
2,Paris,"[Le Monde,Le Figaro,La Croix]"
As an alternative, specify -v (verbose) to emit more information for each row, like the
following example:
Table: SimpleTable
(tupleid=0,key=3,city="Boston",papers="[\"The Globe\",null]")
(tupleid=0,key=2,city="Paris",papers="[\"Le Monde\",\"Le Figaro\",\"La Croix\"]"
)
Result set size: 2 limit: 2
-n null-string
Specify the string you want to display when a table field is read as null. The default string to
indicate a null field is null.
-q quotechar
Use quotechar (a single character) as a quotation mark when the emitted display requires
quotes. The default quotechar is a double quote.
setDynamicVariable dynvar-path value
COMMANDS
230
StreamBase References
The first argument is a StreamBase path to a dynamic variable in the form
container.module.dynvar-name. The second argument is the value to set for that variable.
status [--verbose] [--operators [containerName]]
Displays a one-line summary of current information about the specified sbd server. By default, the
information includes:
--The URI and port of the server.
--The server's process ID.
--The StreamBase version number.
--The hostname of the host machine.
The --verbose option adds:
--The path to the Java JVM being used by the server.
--Memory usage (total memory used by the sbd process).
--The number of currently connected clients.
--The HA leadership status.
Here is a sample of verbose output:
sbd at monaghan:9900; pid=8241; version=6.3.0; name=monaghan; \
javahome=/usr/java/jdk1.6.0_10/jre; memory=445724kb; clients=1; \
leadership_status=LEADER
--operators [containerName]
Instead of server status, displays the status of any Java operators or embedded adapters in the
server. Optionally narrows the status to any Java operators or embedded adapters in the
specified container. The status for each Java operator or embedded adapter has possible
values of NOT_YET_STARTED, STARTED, SUSPENDED_AND_DROPPING_TUPLES,
SUSPENDED_AND_PROCESSING_TUPLES, and SHUTDOWN.
typecheck file.sbapp
Typechecks an application modification and prints descriptions of the resultant streams.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
STREAMBASE_RETITLE_TERMINALS
Optional. If set to any value, StreamBase command-line utilities assign a terminal window title to
match the name of the executable being run. By default, terminal titles are not affected.
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
ENVIRONMENT
231
StreamBase References
SEE ALSO
sbd
sbadmin
Using Containers
syslog(3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
SEE ALSO
232
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > jsbc
jsbc
StreamBase Client â
starts the StreamBase Client, Java implementation
SYNOPSIS
jsbc [OPTIONS] [command] [command-args]
DESCRIPTION
jsbc runs a Java implementation of the StreamBase client utility, which lets you send requests to a running
StreamBase Server (sbd). For example, the jsbc list streams command requests the server to list available
streams.
OPTIONS
With a few exceptions, the jsbc command has the same options as the sbc command, as described in sbc. The
exceptions are:
No space after -u or -p
For jsbc, there must be no space between -u and the following URI, and no space between -p and
the following port number:
jsbc -usb://localhost:10000 listConnections
jsbc -p9900 listConnections
enqueue and dequeue support the --json option
The jsbc subcommands enqueue and dequeue support the --json option. For dequeue, this prints
all tuples in the form of a JSON object (as defined on http://www.json.org) instead of the default CSV
format. For enqueue, --json specifies that the tuples to be enqueued are in JSON object format.
Use this option after the enqueue or dequeue subcommand:
jsbc enqueue --json InputPort
jsbc dequeue --json OutputPort
jsbc
233
StreamBase References
enqueue supports sending no-fields tuples with --json
A no-fields tuple is the input format you send to an input stream defined with an empty schema, as
described in Using Empty Schemas. Send a no-fields tuple as a line with one or more spaces or tabs,
or, when using the --json option, as one or more spaces or tabs surrounded by braces.
-J option supported
The jsbc command accepts the -J option, but sbc does not.
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs
this jsbc command. Use this option to specify temporary settings that affect only the current
invocation of jsbc. You must specify multiple -J options to specify multiple JVM arguments.
A space between the -J and its argument is optional. Use the full option syntax for
jvm-option that you would use at the Java command line, including the initial hyphen. For
example, specify -J-Dstreambase.log-level=2 to increase the log level for this
invocation of jsbc.
Your jvm-option argument might require surrounding quotes, depending on the characters
it contains and the shell you are using. However, do not use quotes to escape the spaces
between separate JVM arguments; instead use separate -J options. For example:
-J-Xms512M -J-Xmx2G
No arguments for -h and --help
Unlike the sbc command, this jsbc command's -h and --help options do not take subcommand
arguments.
COMMANDS
The jsbc command accepts the same subcommands as the sbc command. See sbc.
FILES
There is no configuration file for jsbc.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
STREAMBASE_RETITLE_TERMINALS
Optional. If set to any value, StreamBase programs assign a terminal window title to match the name
of the executable being run. By default terminal titles are not affected. Applies to jsbc dequeue and
jsbc enqueue only.
STREAMBASE_LOG_LEVEL
OPTIONS
234
StreamBase References
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
SEE ALSO
sbd
sbcsbadmin
Using Containers
syslog (3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
ENVIRONMENT
235
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbcipher
sbcipher
StreamBase â
enciphers text or generates cipher keys for use in StreamBase Server configuration files
SYNOPSIS
sbcipher [[-Jjvm-option]] {[-k pathToPrivateKeyFile]} {-c "clear text to
encipher"}
sbcipher [[-Jjvm-option]] {[-h || -v]}
sbcipher [[-Jjvm-option]] {-g pathToKeyFiles} {-s KeySize}
DESCRIPTION
Can be used to encipher passwords, URIs that contain passwords, and other parameter text values in the
data-sources and operator-parameters sections of the StreamBase Server configuration file.
Three elements of the configuration file accept the enciphered="true" attribute: param and uri in the
data-sources section, and operator-parameter.
A common key pair is embedded in clear text in the sbcipher command and in StreamBase Server. By
default, sbcipher -c uses the private key of that embedded common key pair. Specify -k with -c to designate
a separate private key generated in advance with -g.
sbcipher -g can be optionally used to create unique client-server key pairs that can be subsequently used by
the sbcipher command and supplied to StreamBase Server by means of the
streambase.security.key-file Java property.
OPTIONS
-c "clear text to encipher", --cipher "clear text to encipher"
Enciphers the argument, and prints the results on stdout.
SEE ALSO
236
StreamBase References
-g pathToKeyFiles, --generate pathToKeyFiles
Generates a client-server key pair and writes the files to the path specified, using the basename of the
last element of the path as the basename of the keys. The client key is generated with the name
basename.sbcipher, while the server key is generated as basename.server.
-h, --help
Displays usage information, then exits.
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM running the
enciphering process. Use this option to specify temporary settings that affect only the current
invocation of sbcipher. You must specify multiple -J options to specify multiple JVM arguments.
There must be no space after the -J. For example, specify -J-Xmx2G. Use the full option syntax for
jvm-option that you would use at the Java command line, including the initial hyphen. For
example, specify -J-Dstreambase.log-level=2 to increase the log level for this invocation
of sbcipher.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
-k pathToPrivateKeyFile, --key pathToPrivateKeyFile
Specify a basename.server file generated with -g as the private key to use when enciphering a
string with -c.
-s KeySize, --size KeySize
Specifies the desired bit size for the keys generated with -g. Valid values for KeySize are 512,
1024, 2048, and 4096.
-v, --version
Displays the version of the command.
SEE ALSO
Enciphering Passwords and Parameter Values
StreamBase Server Configuration File XML Reference
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
OPTIONS
237
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbconfutil
sbconfutil
StreamBase Server Configuration File Smart Merge Tool â
multiple configuration file fragments.
Shows as a single file the merged results of
SYNOPSIS
sbconfutil [OPTIONS] [path-to-conf-file]
DESCRIPTION
sbconfutil reads a top-level StreamBase Server configuration file specified as an argument in any position, or
specified as the argument for the -f option, and returns the reconciled and merged result of any
<xi:include> or <sb-include> fragments. This utility performs the exact same smart merge of
configuration file fragments as StreamBase Server, but at the command prompt without needing to start all of
the server. Use this utility to test and verify a complex configuration file composed of multiple fragments.
The tool reports its result to stdout by default, or to a file specified with the -o option. You can also use
sbconfutil with its -j option to extract the complete JVM arguments portion of a configuration file, including
<java-vm> portions specified in multiple fragment files.
See Using Modular Configuration Files in the Administration Guide for more on using the <xi:include>
or <sb-include> elements.
OPTIONS
-h, --help
Displays usage text, then exits.
-v, --version
Displays the current StreamBase release number, then exits.
-f path-to-conf-file
The path to the top-level server configuration file whose included fragments you want to resolve.
SEE ALSO
238
StreamBase References
-o path-to-output-file
The path to an output file in which to save the resolved configuration.
-j, --jvmargs
Extracts JVM arguments specified in all fragments of a top-level server configuration file, returning
the JVM arguments in a form that can be used as a set of arguments for a Java command or for
another Java-based StreamBase command for testing.
SEE ALSO
sbd
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
OPTIONS
239
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sb-config
sb-config
StreamBase Compiler Environment Utility â
linker flags
a tool to determine and set StreamBase-related compiler and
SYNOPSIS
sb-config [--no-logging-backend] [OPTION]
DESCRIPTION
sb-config is a convenience utility used to set compiler and linker environment variables to settings compatible
with the compiler and linker that built the library files for the current StreamBase installation.
On UNIX, the options --env, --cflags, --libs, --plugin-cflags, and --plugins-ldflags
emit shell lines or fragments that might contain double quotes such that any spaces in the emitted line do not
break up a variable definition or a command line option. This behavior interacts as expected with the shell
eval command and with back quote operators.
On Windows and UNIX, the --java, --javac, and --classpath options do not put quotes around
emitted paths that contain spaces, because the output of these options is likely to be combined with other
members of a PATH or CLASSPATH variable. If your StreamBase installation path contains spaces, you
might need to make sure your script or Makefile uses double quotes around the expansion of the sb-config
output that you capture in a variable.
OPTIONS
--cflags (UNIX only)
Returns the C++ compiler flags required for building StreamBase C++ client applications. Use this
option in Makefiles, in statements such as SB_CLIENT_CFLAGS=`sb-config --cflags`.
--classpath (UNIX and Windows)
SEE ALSO
240
StreamBase References
Returns the path to the StreamBase client library JAR file that must be added to the class path when
building and running StreamBase Java client applications.
--cxx (UNIX only)
Returns the path to the default C++ compiler detected on your system. Use this option in Makefiles in
statements such as CXX=`sb-config --cxx`.
--env (UNIX and Windows)
Returns, but does not execute, the commands to set environment variables for running StreamBase
utilities (Windows) or for running and building StreamBase client applications (UNIX). Use the
output of sb-config --env with eval or a similar command to execute the commands returned. For
Windows and UNIX, returns a setting for STREAMBASE_HOME and prepends the StreamBase bin
directory to the PATH. For UNIX, also returns settings for LD_LIBRARY_PATH and MANPATH.
--help, -h (UNIX and Windows)
Displays a usage message, then exits. Entering sb-config with no arguments also shows usage.
--java (UNIX and Windows)
Returns the path to the Java JRE used by the current StreamBase installation.
--javac (UNIX and Windows)
Returns the path to the Java compiler used by the current StreamBase installation.
--libs (UNIX only)
Returns the C++ linker flags appropriate for building StreamBase C++ client applications.
--no-logging-backend (UNIX and Windows)
Modifies the --classpath option, and must precede it. With this option, --classpath returns
the path to an alternate version of the StreamBase client library JAR file, with StreamBase logging
features disabled. Use this option if you have another logging system you want to use, such as log4j,
already in your CLASSPATH.
--plugin-cflags (UNIX only)
Returns the C++ compiler flags appropriate for building StreamBase C++ plug-ins. On most systems,
this returns the same value as --cflags.
--plugin-ldflags (UNIX only)
Returns the C++ linker flags appropriate for building StreamBase C++ plug-ins.
--pypath (UNIX only)
Returns the path to the appropriate version of the StreamBase Python Client library to use to match
the default version of Python detected on your system. Use this option when setting the
PYTHONPATH environment variable. For example: export PYTHONPATH=`sb-config
--pypath`:$PYTHONPATH.
--setenv (Windows only)
Modifies the Windows registry to add PATH and STREAMBASE_HOME settings appropriate for the
current version of StreamBase to the environment for the currently logged-in Windows user. Do not
use if you have a mix of StreamBase 3.x and StreamBase 5.x or 6.x installations, and use with caution
if you have multiple StreamBase 5.x or 6.x installations, as described in the StreamBase Command
Prompt topic of the Test/Debug Guide.
--setsysenv (Windows only)
Same as --setenv, but modifies the environment for all Windows users.
--version (UNIX and Windows)
Returns version information and exits.
EXAMPLES
The following examples are for use at the UNIX shell prompt, or at the Bash prompt of a UNIX-like
environment under Window such as Cygwin.
OPTIONS
241
StreamBase References
The next line sets the CXX environment variable to the path to the compiler used to build the StreamBase
libraries and binaries in the current release of StreamBase.
CXX=`sb-config --cxx`
The following line uses the specified compiler ($CXX) to compile MyApplication.cpp, using the same
compiler flags used to build the StreamBase libraries (sb-config --cflags). (The -c and -o are options to the
compiler, not to sb-config.)
$CXX MyApplication.cpp `sb-config --cflags` -c -o MyApplication.o
The next line links the object file generated by the above line.
$CXX MyApplication.o `sb-config --libs` -o MyApplication
The next lines show examples for building StreamBase C++ plug-ins instead of client applications.
$CXX MyPlugin.cpp `sb-config --plugin-cflags` -c -o MyPlugin.o
$CXX `sb-config --plugin-ldflags` MyPlugin.o -o MyPlugin.so
The next lines show how to compile and run a StreamBase Java client application.
javac -classpath `sb-config --classpath` MyApplication.java
java -classpath `sb-config --classpath`:. MyApplication
The next line shows how to compile a StreamBase Java client application using your preferred Java logging
libraries, which are assumed to be already in the CLASSPATH environment variable.
javac -classpath $CLASSPATH:`sb-config --no-logging-backend
--classpath`:. MyApplication.java
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
EXAMPLES
242
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbfeedsim
sbfeedsim
StreamBase Feed Simulator â
starts the StreamBase Feed Simulator.
SYNOPSIS
sbfeedsim [OPTIONS...] [feedsim-file.sbfs]
DESCRIPTION
The sbfeedsim command starts the StreamBase Feed Simulator, which connects to a running StreamBase
application and submits data to it. Use this tool to test the validity and performance of your application.
As with most StreamBase command-line tools, you can specify the StreamBase Server to communicate with
by using -p or -u arguments. In the absence of these arguments, sbfeedsim connects to the server specified
in the STREAMBASE_SERVER environment variable. In the absence of this variable, sbfeedsim attempts to
connect to the default StreamBase URI, sb://localhost:10000.
If you omit the optional feedsim-file.sbfs argument, sbfeedsim connects to the specified or default
server, determines the schema expected by the input stream of the running StreamBase application, and
generates default data for each data type in the schema. If the running application has more than one input
stream, sbfeedsim determines the expected schema for each stream and generates sample data for all fields in
each stream. You can use the -s option to narrow the list of input streams for which sample data is generated.
sbfeedsim can also populate input streams according to a user-specified statistical distribution, or via a data
file that contains data you created to test various streaming scenarios. The data file is typically in
comma-separated value (CSV) or tab-delimited format. With sbfeedsim, you have control over tuple values
and the input rate of generated data.
Running a feed simulations in StreamBase Studio is functionally equivalent to running one with the
sbfeedsim command. If you have feed simulation files created and saved with StreamBase 3.5 and earlier, use
the sbfeedsim-old command instead, or use the -c option to upgrade those files to the current format.
sbfeedsim
243
StreamBase References
OPTIONS
-a
Sets the data rate for this feed simulation to run as fast as possible.
-b count
Changes the maximum number of tuples to buffer on each stream to count, when using the default
load or a user-specified distribution. This setting adjusts the enqueue client buffer size for each input
stream. The default size is 100 tuples. Specify zero to disable buffering.
-B count
Changes the maximum number of tuples to buffer when using a data file or JDBC data source. The
default buffer in these cases is 40,000 tuples.
-c, --convert
Converts a legacy feed simulation file (saved with StreamBase 3.5 and earlier) to the current feed
simulator XML format, and prints the result to standard output. You can redirect the converted results
to a file, as in the following example:
sbfeedsim -c MyOldFeedsim.sbfs > MyNewFeedsim.sbfs
-F
When using a data file or JDBC data source, completely prefill the tuple buffer before sending the
first tuple.
--force
Run this feed simulation even if warnings occur during application compatibility validation.
-h, --help
Displays usage text, then exits.
-J jvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs this
sbfeedsim command. Use this option to specify temporary settings that affect only the current
invocation of sbfeedsim. You must specify multiple -J options to specify multiple JVM arguments.
A space between the -J and its argument is optional. Use the full option syntax for jvm-option
that you would use at the Java command line, including the initial hyphen. For example, specify
-J-Dstreambase.log-level=2 to increase the log level for this invocation of sbfeedsim.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
--legacy
Force an on-the-fly conversion and execution of a feed simulation file created with StreamBase 3.5 or
earlier.
--max-time secs
Limit the feed simulation run by time. Generates data appropriate for the schemas of the input ports of
the running StreamBase Server, until secs seconds have elapsed.
--max-tuples count
Limit the feed simulation run by number of tuples sent. Generates appropriate data as above up to the
number of tuples specified by count.
-p TCP-port
Sets the port number for the StreamBase Server instance to connect with. This is useful when the
server is localhost and you only need to specify a non-default port, instead of specifying the full
URI with the -u option. The default port is 10000.
OPTIONS
244
StreamBase References
Note
The -p option is not supported for applications that have StreamBase authentication enabled (because
there is no way to specify a username and password) or in conjunction with the multiple URI syntax.
-q
Does not display tuples (quiet).
-s streamname1,streamname2,...
Specifies a comma-separated list of input stream names in the application running on the connected
StreamBase Server. The -s option is only valid when no .sbfs feed simulation file is specified as
an argument.
-u uri
Specifies the URI of the StreamBase Server to communicate with. The default is
sb://localhost:10000/. The URI can also be set using the STREAMBASE_SERVER
environment variable. See the sburi page of the Reference Guide (or see sburi(5) at the UNIX shell
prompt) for a discussion of the URI format and its shortcuts.
Note
The sbfeedsim command's -u option accepts a comma-separated list of URIs, where each URI
specifies a different StreamBase Server in a high availability cluster. See the Multiple URI Syntax for
HA Scenarios page in the Reference Guide for details.
-x factor
Speeds up all streams by a factor specified by factor. For example, -x 2 runs the feed simulation
at twice the default speed.
-z seed
Specify a long value for seed to be used as the random value generator's seed, when automatically
generating values for each field in each stream. Without this option, sbfeedsim uses zero as the seed.
The values generated by sbfeedsim are the same for a given seed value, which makes tests with the
same seed value repeatable. Specify a seed value other than zero to generate a different set of values
than the default setting.
--version
Prints version information and exits.
FILES
The optional feed simulation file is file.sbfs. If specified, sbfeedsim generates a load using the
specifications in that file.
If you create a data file to contain sample data for testing purposes, it is typically a comma-separated or
tab-delimited file.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
Note
245
StreamBase References
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
STREAMBASE_RETITLE_TERMINALS
Optional. If set to any value, StreamBase command-line utilities assign a terminal window title to
match the name of the executable being run. By default terminal titles are not affected.
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
CLASSPATH
When you have saved a feed simulation file that specifies data generation from a JDBC data source,
you can run that file with sbfeedsim. For this to work, the JDBC driver JAR file must be in the
classpath. You can set the CLASSPATH environment variable, or use another standard classpath
setting method. If you use the CLASSPATH environment variable, append to the existing classpath
the full path to the JDBC JAR file. See Feed Simulation with a JDBC Data Source for further
information.
SEE ALSO
sbfeedsim-old
Using the Feed Simulation Editor
Feed Simulations View
syslog (3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
ENVIRONMENT
246
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > jsbclientgen
jsbclientgen
StreamBase Java Client Generation â
application
Generates a simple Java dequeue client for the running StreamBase
SYNOPSIS
jsbclientgen [OPTIONS] [STREAM [OutputStream.Field] | [OutputStream] | [OutputStream@Field] ...]
DESCRIPTION
jsbclientgen generates a simple Java dequeue client for the running StreamBase application, creating a
read-only display interface for one or more output streams. If no output streams are specified on the command
line, data is displayed from up to five streams. Different forms of the stream options allow you to control the
way dequeued data is displayed in the generated client.
If authentication is enabled for this application, the jsbclientgen command requires SBUser privilege level.
Here is a sequence of example commands. First, start the server for your StreamBase application:
sbd myapp.sbapp &
start sbd myapp.sbapp
UNIX
Windows
Next, enter the command to generate a Java source file for a client dequeuing from the running application:
jsbclientgen --class MyDequeueClient
To compile and run the client application, enter commands like the following for UNIX:
javac -cp `sb-config --classpath` MyDequeueClient
java MyDequeueClient
The equivalent commands for Windows are:
sb-config --classpath --setenv
SEE ALSO
247
StreamBase References
javac MyDequeueClient.java
java MyDequeueClient
With the dequeue client running, start a feed simulation in a different terminal window to send test data to the
application and view the dequeued results in the generated client. For example:
sbfeedsim myconfig.sbfs
OPTIONS
-d directory-name
Optional. Defaults to none. Use this option to specify a directory such as java-src for the location
of the generated source file.
-h command, --help command
Displays usage text, then exits.
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs this
jsbclientgen command. Use this option to specify temporary settings that affect only the current
invocation of jsbclientgen. You must specify multiple -J options to specify multiple JVM
arguments.
There must be no space after the -J. For example, specify -J-Xmx2G. Use the full option syntax for
jvm-option that you would use at the Java command line, including the initial hyphen. For
example, specify -J-Dstreambase.log-level=2 to increase the log level for this invocation
of jsbclientgen.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
-p TCP-port
Sets the port number only for the StreamBase Server. Useful when the server is localhost and you
only need to specify a non-default port, instead of specifying the full URI with the -u option. The
default port is 10000.
Note
The -p option is not supported for applications that have StreamBase authentication enabled (because
there is no way to specify a username and password) or in conjunction with the multiple URI syntax.
--package package-name
Optional. Defaults to none. Specifies a package name in which this class will be generated, such as:
jsbclientgen --package com.example.sbclient --class MyApplication
-u URI
Sets the URI of the StreamBase Server. The default is sb://localhost:10000/. The URI for
the StreamBase Server may also be set using the STREAMBASE_SERVER environment variable.
See the sburi page of the Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion
of the URI format and its shortcuts.
--version
Prints version information and exits.
DESCRIPTION
248
StreamBase References
COMMAND OPTIONS
STREAM
Allows you to specify one or more Output Streams in the StreamBase application. If no Output
Streams were specified on the jsbclientgen command line, data is displayed from up to five (5)
streams. If streams were specified, the format that you use on the command line determines how the
generated client displays the data. For each stream, you can use the following options in any preferred
combination (one format type per stream):
OutputStream.Field
Displays the value of the field Field of the most recent tuple.
OutputStream
Displays a table of all tuples on OutputStream.
OutputStream@Field
Displays a table of all tuples on OutputStream keyed by the field Field on OutputStream.
FILES
The jsbclientgen command generates a Java source file, class-name.java.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
STREAMBASE_RETITLE_TERMINALS
Optional. If set to any value, StreamBase programs assign a terminal window title to match the name
of the executable being run. By default, terminal titles are not affected.
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
SEE ALSO
sbd
sbadmin
syslog (3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
COMMAND OPTIONS
249
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbhelp
sbhelp
StreamBase Help Viewer â
starts StreamBase Help Viewer
SYNOPSIS
sbhelp
DESCRIPTION
sbhelp opens the StreamBase Help Viewer.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
SEE ALSO
250
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbmanager
sbmanager
StreamBase Manager â
starts the StreamBase Manager
SYNOPSIS
sbmanager
DESCRIPTION
sbmanager starts the StreamBase Manager graphical utility that shows information about StreamBase
applications running locally or on another host. On Windows, the sbmanager command starts the same
program as the Start menu's (All) Programs>StreamBase n.m>StreamBase Manager item.
After startup, you must connect or reconnect to a running StreamBase Server in order to see information about
the applications it is running. The first time StreamBase Manager is run, its Servers view is empty. Use
File>Add StreamBase Server to add localhost or another server to the list.
sbmanager presents in graphical form the same information as the character display of the sbmonitor utility.
StreamBase Manager also shows dynamic graphs of CPU and memory usage for the StreamBase Server it is
currently connected to.
For further information on StreamBase Manager, use Help>Help Contents to open its Help system.
OPTIONS
There are no options for sbmanager.
DESCRIPTION
251
StreamBase References
FILES
There is no configuration file for sbmanager.
ENVIRONMENT
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
SEE ALSO
sbmonitor
syslog (3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
FILES
252
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbmonitor
sbmonitor
StreamBase Monitor â
starts the StreamBase Monitor utility
SYNOPSIS
sbmonitor [OPTION]
DESCRIPTION
sbmonitor is a command-line utility that shows information about the current status and performance of a
running StreamBase application. The information shown includes the number of tuples processed by each
box, the percentage of CPU time consumed by each box, and the percentage of CPU time consumed by each
thread. sbmonitor presents a character-based display that contains the same statistics as the graphical display
of the sbmanager command.
While sbmonitor is running, type one of the following letters to control the display and to see help text for the
data columns.
C
Toggles container names on and off in the Name column of the Operators, Profile, and Queues views.
When monitoring a single-container application where the only container is named default, you
can toggle container names off for a cleaner presentation. When monitoring an application with more
than one container, leave container names enabled.
H or ?
Replaces the bottom part of the screen with help text. Press H or ? again to see the second and
subsequent pages of help text. Type Q to exit help mode and return to the view you were in.
L
Toggles the bottom part of the screen between Threads view, Queues view, Streams, and Sync
Threads views. Threads view is the default on sbmonitor startup.
P
Toggles the top part of the screen between Operators view and Profile view. Operators view is the
default on sbmonitor startup.
S
SEE ALSO
253
StreamBase References
Enables and disables column-sort mode for the Operators view. In column-sort mode, which is
enabled by default, use the left and right arrow keys to select another column heading. The display
automatically re-sorts based on the selected column. Type S to exit column sort mode.
U
Toggles screen updating on and off. In an active monitoring session with many constantly updating
rows, it can be hard to follow a single row across. Press U to temporarily disable screen updating;
press U again to restore screen updates. This toggle does not affect the running application, only the
screen display.
Q
Exits sbmonitor back to the terminal prompt, or exits the H help text screen.
OPTIONS
-h, --help
Displays usage text, then exits.
-k
Shows a description of the columns.
-u URI
Sets the URI of the StreamBase Server. The default is sb://localhost:10000/. The URI can
also be set using the STREAMBASE_SERVER environment variable. See the sburi page of the
Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion of the URI format and its
shortcuts.
-p TCP-port
Sets the port number only for the StreamBase Server. Useful when the server is localhost and you
only need to specify a non-default port, instead of specifying the full URI with the -u option. The
default port is 10000.
Note
The -p option is not supported for applications that have StreamBase authentication enabled (because
there is no way to specify a username and password) or in conjunction with the multiple URI syntax.
--version
Prints version information and exits.
FILES
There is no configuration file for sbmonitor.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
DESCRIPTION
254
StreamBase References
STREAMBASE_RETITLE_TERMINALS
Optional. If set to any value, StreamBase programs assign a terminal window title to match the name
of the executable being run. By default terminal titles are not affected.
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
SEE ALSO
sbmanager
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
ENVIRONMENT
255
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbprofile
sbprofile
StreamBase Profiler â Runs the StreamBase profiler to produce formatted statistics about operators and
queues in a running server.
SYNOPSIS
sbprofile {[-u sburi | -p port | -s statfile]} [-h] [OUTPUT OPTIONS] [FILTER OPTIONS]
DESCRIPTION
Use sbprofile to produce formatted statistical profile information about operators, queues, threads, and system
information in a given run of StreamBase Server. sbprofile reads the raw system.statv2 statistics stream
either from a live server process (-u or -p options), or from a saved raw statistics file (-s option), which can
be compressed with gzip. When calculating operator description information (-d or -D options), sbprofile
also examines the currently running application on the server.
The sbprofile command does not analyze and draw conclusions from the system statistics. Its purpose is to
extract useful information from the system statistics stream and format it for manual or automated inspection.
See Profiling for examples of output and for an overall discussion of StreamBase profiling.
By default, sbprofile with no arguments connects to the default server URI, sb://localhost:10000,
and prints to stdout a set of CSV formatted statistics lines, one line for each active operator, queue and
thread, plus a line of system information. sbprofile prints one set of statistics for every system.statv2
snapshot interval, which is once per second by default. You can change the snapshot interval using the
<period-ms> parameter of the <sbmonitor> element in the server configuration file. (See <sbmonitor>
for details.) The command extracts and formats statistics until it is stopped with Ctrl+C or until the server
shuts down.
Note
The profiling system shows meaningful statistics only for operators and queues that have run for a while. It is
common to have StreamBase applications with operators that use no measurable amount of CPU time when
SEE ALSO
256
StreamBase References
the application has not run very long or has not run with much data. For low latency applications running on
fast CPUs, it could take hundreds of thousands of tuples to register statistics greater than zero.
Use only one of the -u, -p, or -s options. You can specify connecting to a live server at a different
StreamBase URI than the default (-u), or to the localhost server on a non-default port (-p). Use -s to specify
reading from a saved raw statistics file, which must already exist, and must have been generated with sbc
-u sburi dequeue system.statv2 > statfile. Raw statistics input files compressed with gzip
are automatically interpreted by sbprofile, independent of filename extension.
The name of the statistics stream in the system container changed to statv2 with release 7.0.0. For earlier
releases, generate a statistics file from the statistics stream named stat, like this example:
sbc -u sburi dequeue system.stat > statfile. Because the statistics stream was renamed,
you cannot run a system monitoring client, including sbmonitor and StreamBase Manager from an earlier
release against StreamBase Server 7.0.0 or later. Dequeued system.stat data from StreamBase 6.x servers
should not be used with the 7.x sbprofile command, because the units of measuring CPU statistics changed.
Use the output options (-F, -o, -b, -c, and -i) to change the output format to a simple HTML table, to
redirect the formatted output to a file (or to a bzip2 or gzip compressed file), or to change the reporting
interval. Notice that the -i option does not alter the system.statv2 sampling interval, and does not
accumulate statistics. It only changes how often to print formatted output lines.
Use the filter options (-f, -Q, -t, -Y, -C, -S, -I, -O, -d, -D, and -z) to narrow the output report to
operators or queues matching a regular expression, to operators only, or queues only. You can suppress thread
or system information. You can restrict the output report for outlying cases by setting threshold values for
various fields. You can combine filter options so that an output report contains entries only for statistics
matching any of several conditions.
Do not confuse sbprofile's input and output files. If used, the input file is a collection of raw statistics emitted
from a server's system.statv2 stream, optionally compressed with gzip by an administrator. If specified,
the output file is a formatted CSV or HTML file, extracted from the input stream, optionally compressed with
gzip by the sbprofile -c option. The output of sbprofile cannot be used as the input of another sbprofile
command.
In the default CSV output format, each emitted line begins with a field containing a single letter that
distinguishes the output type. The values in the first field are one of the following:
O for operator statistics lines.
D for operator description lines.
Q for queue statistics lines.
T for thread statistics lines.
S for system information lines.
For the meanings of the other fields in each output line type, see the field tables in the Meanings of the
Profiling Statistics Collected section of the Profiling page of the Administration Guide.
Note
When a StreamBase application starts, the JVM associated with StreamBase Server interprets the bytecode at
the start of execution, compiles it into native CPU instructions, and then optimizes it as the application is run.
Thus, when profiling, statistics gathered at the start of the run do not reflect the optimization timing that will
Note
257
StreamBase References
be automatically applied as the application continues to run. Therefore, the longer the application runs, the
more accurate the profile.
OPTIONS
You must specify one of -u, -p, or -s (or specify -h, which overrides these three options).
-h, --help
Displays usage text.
-u sburi
Specifies the URI of the StreamBase Server instance to communicate with. See the sburi page of the
Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion of the URI format and its
shortcuts. The URI can also be set using the STREAMBASE_SERVER environment variable. If
neither -u, -p, nor -s is specified, the command proceeds with standard defaults as if you entered
-u sb://localhost:10000.
-p TCP-port
Specifies the port number on localhost for the StreamBase Server instance to communicate with.
This is a shortcut alternative to specifying the full URI with -u in cases where the server is running
on localhost on a port other than the default 10000.
Note
The -p option is not supported for applications that have StreamBase authentication enabled (because
there is no way to specify a username and password) or in conjunction with the multiple URI syntax.
-s statfile
Specifies the path to a file containing StreamBase Server raw statistics for an application or container,
to be opened for formatting and display. The raw statistics file must already exist and must be
collected with a command like the following:
sbc -u sburi dequeue system.statv2 > statfile (The name of the statistics stream
in the system container changed to statv2 with release 7.0.0. For earlier releases, generate a
statistics file from the statistics stream named stat, like this example:
sbc -u sburi dequeue system.stat > statfile
(The raw statistics input file created with sbc dequeue is NOT the same as a formatted output file
created with sprofile and its -o or -c options.)
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs this
sbprofile command. Use this option to specify temporary settings that affect only the current
invocation of sbprofile. You must specify multiple -J options to specify multiple JVM arguments.
There must be no space after the -J. For example, specify -J-Xmx2G. Use the full option syntax for
jvm-option that you would use at the Java command line, including the initial hyphen. For
example, specify -J-Dstreambase.log-level=2 to increase the log level for this invocation
of sbprofile.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
Note
258
StreamBase References
OUTPUT OPTIONS
-F csv | html, --format csv | html
Specifies the display output format. The default is CSV format, with one line per operator or queue
for each snapshot interval (or for the snapshot interval at every nSecs, if used with -i). Specify
HTML format to generate a simple HTML page with a table for each snapshot interval (one second
by default), or a table for the snapshot interval at every nSecs, if used with -i.
-o filename, --outfile filename
Specifies the path to a filename to contain the CSV or HTML formatted output of the command. The
default is to write to stdout.
-b filename, --bzip2-outfile filename
Specifies the path to a filename to contain the formatted output of the command, which will be
compressed with bzip2. The .bz2 filename extension is automatically appended to the filename you
specify. Since profile output files have a regular format, bzip2 compression provides about half the
file size of gzip compression.
-c filename, --compressed-outfile filename
Specifies the path to a filename to contain the formatted output of the command, which will be
compressed with gzip. The .gz filename extension is automatically appended to the filename you
specify.
-i nSecs
Specifies emitting statistics every nSecs seconds instead of every snapshot interval (every second by
default). This option does not accumulate statistics over the specified nSecs; instead it emits the
statistics for the specified snapshot interval at each nSecs period, omitting statistics between nSecs
values. For example, sbprofile -i 10 emits the statistics for the 10th second, then the 20th,
then the 30th, and so on, discarding statistics for seconds 0 through 9, 11 through 19, 21 through 29,
and so on. This option works best with the default CSV output format.
--roll-size M
When -o or -c is used to write an output file, close the file when it reaches M megabytes and start
writing to a new output file.
--roll-time T[M | H | D]
When -o or -c is used to write an output file, close the file when T time units have elapsed and start
writing to a new output file. The time units are expressed as M for minutes, H for hours, and D for
days, with H the default.
FILTER OPTIONS
The options in this section are OR'ed together. This allows you to specify two or more independent filter
options, in which case sbprofile prints output statistics for each match of any specified filter option.
-f regex, --format regex
Specifies filtering the formatted output by matching a regular expression against the operator or queue
name in the first field of the CSV output. You can specify more than one -f option. Use this feature
to restrict the output to a subset of operators or queues of interest. To match a substring of the
operator or queue name, place dot-asterisk (.*) before and after your case-sensitive substring
characters. For example:
sbprofile -s rawstatsfile.gz -f ".*Update.*"
-Q, --no-queues
By default, sbprofile shows formatted statistics for each operator, queue, system and thread in the raw
OUTPUT OPTIONS
259
StreamBase References
input statistics. Use -Q to suppress statistics for all queues.
-t, --no-threads
By default, sbprofile shows formatted statistics for each operator, queue, system, and thread in the
raw input statistics. Use -t to suppress statistics for all threads.
-Y, --no-system
By default, sbprofile shows formatted statistics for each operator, queue, system, and thread in the
raw input statistics. Use -Y to suppress statistics for System information.
-C T, --cpuThreshold T
Only include operators whose Time (ms) entry is greater than or equal to T milliseconds. (Has no
filter effect on queue statistics.) Since most operators show zero or very low values in the Time (ms)
column, start with low-numbered arguments such as 1 or 2 and increase them as required. Remember
that the argument is in milliseconds, so -C 1 means: show operators with a CPU time of .001
seconds or more.
-S N, --sizeThreshold N
Only include operators whose Size entry is greater than or equal to N, or queues whose Queue Current
Size entry is greater than or equal to N.
-I N, --inputThreshold N
Only include operators whose Operator In entry is greater than or equal to N. (Has no filter effect on
queue statistics.)
-O N, --outputThreshold N
Only include operators whose Operator Out entry is greater than or equal to N. (Has no filter effect on
queue statistics.)
-d, --description
For each operator that passes filtering, emit its type once.
-D, --properties
Same as -d, except include any operator properties.
-z, --printZeroOperators
Include all operators, even those that have accumulated zero processing time. Include all queues, even
those that have never had a size greater then 0. Include all threads, even those that have never had
CPU time charged to them.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
FILTER OPTIONS
260
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbproxy
sbproxy
StreamBase Proxy â
starts the StreamBase Proxy server
SYNOPSIS
sbproxy [-f file.sbconf] proxy-version proxy-port sbd-hostname sbd-port
DESCRIPTION
Run the StreamBase proxy server separately from the sbd server to provide authentication services using SSL
or LDAP for StreamBase clients attempting to access StreamBase Server. The server is configured to require
a secure connection using settings in the <security> section of the server's configuration file. This subject
is discussed in Using the Proxy Server.
In previous releases, the proxy server was also used to translate the network protocol for client programs built
with older StreamBase releases connecting to newer StreamBase Servers. However, the protocol proxying
aspect of sbproxy is now incorporated into the sbd server. You no longer need to run the proxy server to
translate between StreamBase clients and servers of different releases.
The StreamBase proxy server supports both enqueuing and dequeuing remote clients. It is a pass-through
server, and exchanges date between client and server without other processing.
OPTIONS
-f file.sbconf
The server configuration file where you have defined the security element to enable sbproxy
security.
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs this
sbproxy command. Use this option to specify temporary settings that affect only the current
invocation of sbproxy. You must specify multiple -J options to specify multiple JVM arguments.
ENVIRONMENT
261
StreamBase References
There must be no space after the -J. For example, specify -J-Xmx2G. Use the full option syntax for
jvm-option that you would use at the Java command line, including the initial hyphen. For
example, specify -J-Dstreambase.log-level=2 to increase the log level for this invocation
of sbproxy.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
ARGUMENTS
proxy-version
The StreamBase version that the client application was created with. This option is no longer
required.
proxy-port
The port number used by the sbproxy server.
sbd-hostname
The remote host on which the sbd server runs.
sbd-port
The port number used by the sbd server.
Example
The following command starts sbproxy and forces the associated sbd to communicate with clients only
through sbproxy on the local host:
sbproxy -f sbd.sbconf 6.2 10100 localhost 10000
SEE ALSO
Using the Proxy Server
Configuring the Proxy Server
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
OPTIONS
262
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbrecord
sbrecord
StreamBase Recording Tool â
Records data enqueued onto all Input Streams
SYNOPSIS
sbrecord [OPTIONS]
DESCRIPTION
sbrecord records data enqueued onto all Input Streams in a running StreamBase application. For example, the
sbrecord --name june28feedproc command records the data enqueued onto all Input Streams and creates
several files that can be played back with the sbfeedsim command. The generated files are based on the
--name parameter. Examples: june28feedproc.sbrec, which contains the recording's configuration
properties (pointers to one or more *.csv generated data files, one for each Input Stream, such as
june28feedproc-stream1.csv and june28feedproc-stream2.csv).
If authentication is enabled for this application, the sbrecord command requires SBUser privilege.
OPTIONS
-h command, --help command
Displays help for the specified command, then exits. For example, sbrecord -h shows a usage
message for the sbrecord command.
-u URI
Sets the URI of the StreamBase Server. The default is sb://localhost:10000/. The URI can
also be set using the STREAMBASE_SERVER environment variable. See the sburi page of the
Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion of the URI format and its
shortcuts.
-p TCP-port
Sets the port number only for the StreamBase Server. Useful when the server is localhost and you
only need to specify a non-default port, instead of specifying the full URI with the -u option. The
SEE ALSO
263
StreamBase References
default port is 10000.
Note
The -p option is not supported for applications that have StreamBase authentication enabled (because
there is no way to specify a username and password) or in conjunction with the multiple URI syntax.
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs this
sbrecord command. Use this option to specify temporary settings that affect only the current
invocation of sbrecord. You must specify multiple -J options to specify multiple JVM arguments.
There must be no space after the -J. For example, specify -J-Xmx2G. Use the full option syntax for
jvm-option that you would use at the Java command line, including the initial hyphen. For
example, specify -J-Dstreambase.log-level=2 to increase the log level for this invocation
of sbrecord.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
--name recording-name
Required. A name used to identify the recording session. Files generated by the sbrecord command
are based on the --name parameter. Examples: june28feedproc.sbrec, which contains the
recording's configuration properties (pointers to one or more *.csv generated data files, one for each
Input Stream, such as june28feedproc-stream1.csv and
june28feedproc-stream2.csv).
--outdir file-system-path
Optional. Sets the location of recorded data. The path must exist and be writeable. Default to the
current working directory.
--version
Prints version information and exits.
FILES
The sbrecord command generates a configuration file, using the value from the --name parameter, and uses
the sbrec file extension. For example, the sbrecord --name marketfeed command results in a configuration
file named marketfeed.sbrec, which contains pointers to one or more CSV data files (one for each Input
Stream in the running StreamBase application). In this example, each CSV file would be named
marketfeed-stream-name.csv. There is one configuration file (*.sbrec) for each recording.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
OPTIONS
264
StreamBase References
STREAMBASE_RETITLE_TERMINALS
Optional. If set to any value, StreamBase programs assign a terminal window title to match the name
of the executable being run. By default, terminal titles are not affected.
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
SEE ALSO
sbd
sbadmin
syslog (3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
ENVIRONMENT
265
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbd
sbd
StreamBase Server â
the StreamBase event processing server
SYNOPSIS
sbd [OPTIONS] [application-file]
DESCRIPTION
sbd is the StreamBase Server daemon, the server process that listens for and acts upon client requests
(commands and data) in a StreamBase application. The StreamBase Server accepts incoming streaming data,
manages execution queues, and performs the real-time processing work as defined in the specified application.
The sbd command takes one of five files types as the application-file argument:
--An EventFlow application, with .sbapp extension.
--A StreamSQL application, with .ssql extension.
--A StreamBase deployment file, with .sbdeploy extension.
--A precompiled application archive file with .sbar extension, generated with the sbargen command.
--An application bundle file with .sbbundle extension, generated in StreamBase Studio or with the
sbbundle command.
For EventFlow and StreamSQL application files and for deployment files, sbd typechecks and compiles the
specified application on the fly, then runs the compiled application. Precompiled application archive files are
run immediately. Application bundle files are unpacked to a temporary directory on the sbd server's host
computer. The top-level EventFlow or StreamSQL application in the bundle is then compiled, reconciling any
references to modules, external operators, and external adapters. The compiled top-level application is then
run.
You do not specify containers on the sbd command line. Instead you write a StreamBase deployment file
(.sbdeploy) to define one or more containers. For backward compatibility, you can also specify containers
in a server configuration file (.sbconf), but StreamBase Systems recommends migrating to deployment
files for this purpose.
SEE ALSO
266
StreamBase References
As an alternative, you can start a server process with the sbd command and no options or arguments, then use
the sbadmin addContainer and modifyContainer commands to add containers and applications on
the fly to the running server.
OPTIONS
-b
On UNIX, sends the server process into background mode. On UNIX, using this option sends server
log messages to the log4j logging back end instead of the default Logback back end. The log4j
configuration file shipped with StreamBase is installed in
$STREAMBASE_HOME/etc/log4j.configuration, and the default configuration on UNIX is
to send all output to syslog.
On Windows, StreamBase Systems discourages using sbd â b at the StreamBase Command
Prompt except for short-term testing. Instead, the â b option is designed to be used when specifying
the command line used when starting StreamBase Server as a Windows service, as described in
Running StreamBase Server as a Windows Service.
On Windows, the â b option sends log messages to log4j logging as on UNIX, and log4j is
configured to write to the Windows Event Log by default. However, on Windows, sbd â b does
not start a true background process. In addition, running sbd -b from the StreamBase Command
Prompt results in several benign console warning messages that complain of multiple SLF4J bindings,
as explained in Background Mode on Windows.
-d [key=value], --debug [key=value]
Use either version of this option to prepare StreamBase Server to accept connections from the
EventFlow Debugger in StreamBase Studio. The server starts as usual and echoes a line like the
following on the console:
Listening for transport dt_socket at address: 8000
This option is actually a convenient way to express three separate JVM options. When run without
arguments, --debug makes the following settings:
-agentlib:jdwp=transport=dt_socket,address=0.0.0.0:8000,server=y,suspend=n
-Dstreambase.appgen.debug=true
-Dstreambase.codegen.compile-debug=-g:vars,lines
As an optional argument to --debug, you can specify one or more key-value pairs in a
comma-separated list with no spaces to override the settings of the agentlib:jdwp line (except
that you cannot override the transport setting), or to specify other JDWP settings. Override the
address key to specify a different port on which the server is to listen for debugger connections.
Override the suspend key to cause the server to start and immediately suspend, waiting for a
debugger connection. Suspending immediately allows you to hit breakpoints that occur early, such as
those in the init and typecheck methods of custom Java operator or adapter code.
If your application includes custom Java code, provide a server configuration file for the
command-line launch that specifies a <java-vm/dir> path to the java-bin directory of your
Studio project (or other directory that contains your Java classes). For example:
sbd -f sbd.sbconf --debug suspend=y myapp.sbapp
DESCRIPTION
267
StreamBase References
If you have more complex requirements, you can still start the server in debug mode by specifying the
same three settings that --debug makes, but instead use separate -J lines:
sbd \
-J-agentlib:jdwp=transport=dt_socket,address=0.0.0.0:8000,server=y,suspend=n \
-J-Dstreambase.appgen.debug=true \
-J-Dstreambase.codegen.compile-debug=-g:vars,lines \
...
--datadir directory
Sets the directory to be used for persistent data in disk-based Query Tables. If this is not specified, or
the special value "+TEMP+" is used, a temporary directory is created on server startup and deleted on
shutdown. The path specified with this option on the sbd command line takes precedence over other
ways to specify the location of persistent data. See the STREAMBASE_DATA environment variable
for a list of the precedence order.
--eval expression
Evaluates a StreamBase simple expression and exits. You can evaluate simple expressions but not
aggregate expressions with --eval.
For both Windows and Linux, use double quotes around the expression you are testing. For example:
sbd --eval "cbrt(27)"
(double) 3.0
If you need to quote strings or tuple fields in your expression, use single quotes inside the expression's
double quotes. For example:
sbd --eval "list('alpha', 'beta', 'gamma')"
(list(string)) [alpha, beta, gamma]
-f config-file-path
Specifies the location of the server configuration file for sbd to read on startup. Without the -f
option, sbd uses the same internal default configuration as printed by the sbd -s command. Use -f
to override this default configuration by specifying a particular configuration file to use. It is an error
to specify -f with a StreamBase bundle file argument, because the bundle already contains a
bundle-specific configuration file.
-h, --help
Displays a syntax reminder message, then exits.
--install-service
Windows only. Creates a new StreamBase service with the name specified in the
--service-name parameter. The idea is to allow you to define multiple StreamBase services that
start at system boot time.
--intermediate-stream-dequeue
Enables intermediate stream dequeuing. See Intermediate Stream Dequeuing in the Test/Debug
Guide.
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM running the
server. This option does not substitute for putting StreamBase Server JVM arguments in the
<jvm-args> element of the server configuration file. Use this option to specify temporary settings
that affect only the current invocation of sbd. You must specify multiple -J options to specify
multiple JVM arguments.
You might use -J to increase the heap allocated by the JVM in order to compile and run a very large
application, to set the log level to assist debugging, or to set a system property temporarily when you
OPTIONS
268
StreamBase References
cannot update the server configuration file.
For example, specify -J-Xmx2G. Use the full option syntax for jvm-option that you would use at
the Java command line, including the initial hyphen. For example, specify
-J-Dstreambase.log-level=2 to increase the log level for this invocation of sbd.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
--override-version-checking
Directs StreamBase Server to override version checking of bundles. By default, when StreamBase
Server runs a bundle file, it checks the StreamBase version that created the bundle and refuses to run a
bundle not created with the same major.minor release number. If you override version checking,
incompatibilities between the bundled application and the server may still prevent the bundle from
running.
-p TCP-port
Sets the listen port of the sbd server, overriding any setting in sbd.sbconf. The default is 10000.
Note
The -p option is not supported for applications that have StreamBase authentication enabled (because
there is no way to specify a username and password) or in conjunction with the multiple URI syntax.
--remove-service
Windows only. Removes an existing StreamBase service with the name specified in the
--service-name parameter.
-s
Prints the skeleton configuration file to standard output and exits.
--service-name "servicename,Service Display Name"
Windows only. Specifies the StreamBase service name and the display name to be installed or
removed. The servicename term is used as a prefix in the Windows Registry key name. The
Service Display Name portion is used in the Services control panel listing. Both arguments are
required and must be separated by a comma. StreamBase Systems recommends that you begin each
Service Display Name with the word StreamBase, to make it easier for you to manage
multiple StreamBase services in the Services control panel.
sbd --install-service --service-name "sbd2,StreamBase My Application
Two"
--suspend
Start the server with applications in all application containers suspended (the system container is
never suspended). You can override the suspension for individual configured to applications by
specifying the suspend="false" attribute for the application element in the server
configuration file.
--use-custom-logging
Has the same effect as setting the STREAMBASE_USE_CUSTOM_LOGGING environment variable,
as described in Using StreamBase Logging in the Administration Guide. The advantage of this switch
is that it can be used when sbd is run as a Windows service, so that an alternate logging system can be
specified without needing to set a global environment variable.
--version
Prints version information and exits.
-w path, --working-directory path
Note
269
StreamBase References
Specifies a directory from which this instance of sbd is to be run. This option is especially useful
when running sbd in the background, or starting it from a script that changes directories before
launching sbd. This option does not specify the module search path, which still must be specified
normally as described on the Module Search Path page.
The -w option changes to the specified directory path before starting the server. You can specify an
absolute path, which is likely to be machine-specific, or a path relative to the default startup directory
for sbd, as described below. When running a bundle file, the -w path is the location where the bundle
file is unzipped before running its contents.
This option causes sbd to change to the specified directory very early in its startup sequence. When
used, every file the server needs to reference, including files specified on the sbd command line, must
be specified relative to that working directory, or must be absolute paths.
The default startup directory for sbd run in the foreground is the current directory of the launching
process. Thus, when invoked directly at the command prompt, it is the shell's current directory. When
invoked from a shell script, it is the script's current directory.
The default startup directory for sbd run in the background depends on the operating system. When
running sbd -b on UNIX, the default startup directory is the file system root (/). For sbd run as a
Windows service, the default startup directory is %windir%\System32.
EXAMPLES
By default, StreamBase Server uses an internally stored configuration. You can view the default configuration
by using the -s option. For example:
sbd -s | more
In the next example, the user specifies a StreamBase application on the command line. StreamBase Server
starts and loads the application:
sbd /home/myapps/trading.sbapp
In the next example, the user creates a local copy of the default server configuration file.
sbd -s > /home/mydir/mysbd.sbconf
The user makes edits, and then specifies the local copy on the sbd command line. Note that the -f flag and its
parameter must come before the application name. After you make changes in mysbd.sbconf, start sbd to
use the edited file as in the following example:
sbd -f /home/mydir/mysbd.sbconf trading.sbapp
The next example adds a new StreamBase service on Windows to be automatically started at boot time.
sbd --install-service --service-name "sbd2,StreamBase My Application Two"
EXAMPLES
270
StreamBase References
The next example shows several eval subcommands and their outputs. The first evaluates an expression with
no quote delimiters. The second expression requires quotes because it contains spaces. The third requires
quotes because the parentheses would otherwise be interpreted by the shell or command window. The fourth
requires quotes because it contains spaces and to avoid the parentheses being interpreted by the shell.
$ sbd --eval 2e3*6
(double) 12000.0
$ sbd --eval "2 % 7"
(int) 2
$ sbd --eval "pow(2,3)"
(double) 8.0
$ sbd --eval "timestamp('2012-12-21 9:22:34')"
(timestamp) 2012-12-21 09:22:34.000-0500
FILES
The configuration file for sbd is named sbd.sbconf by default. There is one sbd.sbconf file per
StreamBase instance per node. The default sbd.sbconf file can be generated with sbd -s.
ENVIRONMENT
STREAMBASE_DATA
Optional. Sets the directory to be used for persistent data in disk-based Query Tables. The precedence
order for determining the directory is described in STREAMBASE_DATA.
STREAMBASE_RETITLE_TERMINALS
Optional. If set to any value, StreamBase command-line utilities assign a terminal window title to
match the name of the executable being run. By default terminal titles are not affected.
STREAMBASE_LOG_LEVEL
Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is
0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE
messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to
the standard messages), and 2 (which adds DEBUG messages).
SEE ALSO
sbc
syslog (3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
FILES
271
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbstudio
sbstudio
StreamBase Studio Tool â
starts StreamBase Studio
SYNOPSIS
sbstudio [OPTIONS]
DESCRIPTION
sbstudio starts StreamBase Studio, a graphical development environment used to create and test StreamBase
applications.
OPTIONS
--version
Displays the StreamBase version number, then exits.
-h or --help
Displays help, then exits.
SEE ALSO
sbc
sbadmin
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
SEE ALSO
272
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbtest
sbtest
StreamBase Test Utility â
runs a unit test defined in a StreamBase test file
SYNOPSIS
sbtest [-afile.sbapp|-uuri] [OPTIONS] [testfile.sbtest | directory-name]
DESCRIPTION
sbtest runs a unit test of a StreamBase application as defined in a StreamBase test configuration file. You can
also specify the name of a test suite directory, which contains two or more test configuration files, plus the
data input and validation comparison resources needed for those tests.
This command runs a StreamBase Test or Test Suite. Use the sbunit command to run a StreamBase JUnit test
class.
OPTIONS
-h, --help
Displays usage text.
-u[uri]
Specifies the URI of the StreamBase Server to communicate with, overriding the server URI, if any,
defined in the test file. No space is allowed between -u and its argument. If a URI is not currently
specified in the test file, you must specify -a without an argument to remove the application setting at
the same time.
Without an argument, -u ignores the current URI setting in the test file and requires
-aapplication.sbapp on the same command line.
See the sburi page of the Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion
of the URI format and its shortcuts. The URI can also be set using the STREAMBASE_SERVER
SEE ALSO
273
StreamBase References
environment variable.
-a[file.sbapp]
Specifies an EventFlow or StreamSQL application file to run the test against, overriding the
application, if any, defined in the test file. No space is allowed between -a and its argument.
If an application name is not currently specified in the test file, you must specify -u without an
argument to remove the URI setting at the same time.
Without an argument, -a ignores the current application setting in the test file and requires
-usb://host:port on the same command line.
-f config-file
Specifies an sbd.sbconf configuration file to use when running the test.
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs this
sbtest command. Use this option to specify temporary settings that affect only the current invocation
of sbtest. You must specify multiple -J options to specify multiple JVM arguments.
There must be no space after the -J. For example, specify -J-Xmx2G. Use the full option syntax for
jvm-option that you would use at the Java command line, including the initial hyphen. For
example, specify -J-Dstreambase.log-level=2 to increase the log level for this invocation
of sbtest.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
--version
Prints version information and exits.
EXAMPLES
Run the test file named tradeapp.sbtest, which specifies an application name and server URI:
sbtest tradeapp.sbtest
Run the same test file, but override the server URI specified in the test file:
sbtest -usb://localhost:9900 tradeapp.sbtest
Run the same test file, but override the application specified in the test file, instead running
tradetest.sbapp:
sbtest -atradetest.sbapp tradeapp.sbtest
Another test file named uri-noapp.sbtest specifies a server URI, but does not specify an application
name. You can run this test against an application named with -a, but you must override the test file's URI at
the same time with an empty -u. In this case, the default URI is used, unless you specify a URI in a server
configuration file:
sbtest -u -atradetest.sbapp -f sbd.sbconf uri-noapp.sbtest
OPTIONS
274
StreamBase References
A third test file named app-nouri.sbtest specifies an application name, but does not specify a server
URI. You can run this test with a URI specified with -u, but you must also override the test file's application
name at the same time with an empty -a. In this case, specify the application to test in a server configuration
file:
sbtest -a -usb://sbhost:9500 -f sbd.sbconf app-nouri.sbtest
Run all the test configuration files in the directory suitefolder on the server instance at port 9900 of the
current host:
sbtest -usb://localhost:9900 /home/sbuser/suitefolder
FILES
sbtest requires at least one StreamBase test configuration file, which usually has an .sbtest extension. The
test file is typically generated in StreamBase Studio, either by recording a running application in test mode, or
by editing a test scenario with the Test Editor. See Using the StreamBase Test Editor in the Test/Debug Guide
for more information.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
EXAMPLES
275
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbunit
sbunit
StreamBase JUnit Test Utility â
runs a StreamBase JUnit test defined in a Java JUnit class
SYNOPSIS
sbunit [[-Jjvm-option]] {-f config | --config config} {class}
DESCRIPTION
sbunit runs a StreamBase JUnit Test for a StreamBase module, where the test is defined in a JUnit Java test
class. You must specify class as a fully qualified Java path. You must specify a server configuration file,
usually with the .sbconf extension.
This command runs a StreamBase JUnit test class. Use the sbtest command to run a StreamBase Test or Test
Suite.
The server configuration file must have the following minimum setting:
A <dir> child element of the <java-vm> element, specifying the path to the package directory containing
the test class. For test classes developed in StreamBase Studio, the package directory is usually the
java-bin folder of the project folder in your Studio workspace.
The application to run is specified in the loadApp() method in the test class.
The following provides an example of the minimum server configuration file required for use with sbunit:
<?xml version="1.0" encoding="UTF-8"?>
<streambase-configuration xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbconf/">
<java-vm>
<dir path="./java-bin"/>
</java-vm>
</streambase-configuration>
ENVIRONMENT
276
StreamBase References
OPTIONS
-h, --help
Displays usage text.
-f config-file, --config config-file
Specifies a StreamBase Server configuration file (.sbconf file) to use when running the test. The
configuration file must be specified, and must contain the path to the directory containing your JUnit
test class file (which is usually the java-bin folder of the Studio workspace).
-Jjvm-option
Specifies a system property setting or other JVM argument to be passed to the JVM that runs this
sbunit command. Use this option to specify temporary settings that affect only the current invocation
of sbunit. You must specify multiple -J options to specify multiple JVM arguments.
For example, specify -J-Xmx2G. Use the full option syntax for jvm-option that you would use at
the Java command line, including the initial hyphen. For example, specify
-J-Dstreambase.log-level=2 to increase the log level for this invocation of sbunit.
Your jvm-option argument might require surrounding quotes, depending on the characters it
contains and the shell you are using. However, do not use quotes to escape the spaces between
separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G
--version
Prints version information and exits.
EXAMPLE
Run the JUnit test class BBA_test1 developed in the com.example.sbjunit package in StreamBase Studio:
sbunit -f sbd.sbconf com.example.sbjunit.BBA_test1
FILES
sbunit requires at least one StreamBase JUnit Java test file and a server configuration file with minimum
settings described above.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
OPTIONS
277
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sburi
sburi
StreamBase URI format â
Describes the StreamBase URI format and its shortcut forms.
SYNOPSIS
sburi
DESCRIPTION
A StreamBase URI references an instance of StreamBase Server, or references containers running on the
server. Most StreamBase command line utilities address their target server with the -u option, which takes a
StreamBase URI. You might also use StreamBase URIs when specifying container connections, or when
programming StreamBase client applications.
The format of the StreamBase URI is:
sb://[host][:port][/container][;user=xxx;password=yyy]
The following example uses the StreamBase defaults for host, port, and container:
sb://localhost:10000/default;user=sbuser;password=secret
The simplest version of the default URI is used as a default in StreamBase Studio and for all StreamBase
utilities:
sb://localhost
See URI Shortcuts for a list of the default values assumed if not specified.
The following example addresses a container named holdingcell running on a remote server that does not
require authentication:
sb://streamhost:9900/holdingcell
FILES
278
StreamBase References
When using the â u option to specify a URI for a StreamBase command line utility, a space between the
â u and the URI is optional. Exception: When used with the jsbc, jsbadmin, and jsbclientgen commands,
you cannot have a space after the â u (or â p). Thus, the following commands are all in correct form, and
produce the same results:
sbc -u sb://localhost:9900/ha list
sbc -usb://localhost:9900/ha list
jsbc -usb://localhost:9900/ha list
If you have a non-default URI you use often, you can set it in the STREAMBASE_SERVER environment
variable in lieu of typing it every time on the command line. See the Environment section below.
Authentication Parameters
The user and password parameters are only necessary if you are communicating with a StreamBase
Server instance that has StreamBase authentication enabled. For example:
sb://streamhost:9900/holdingcell;user=rose;password=nuh-UH
When specifying authentication parameters at the UNIX shell prompt, enclose the URI in quotes to escape the
shell's interpretation of the semicolon:
"sb://streamhost:9900/holdingcell;user=rose;password=nuh-UH"
Remote Container Connection Parameters
When using a StreamBase URI as part of a stream-to-stream container connection string to specify that one
side of the container connection is on a remote StreamBase Server, you can optionally specify parameters as
part of the remote URI.
For example, you might specify a container connection with the source end of the connection on a remote
server, and at the same time specify a reconnection interval of 30 seconds, using a container connection
specification like the following:
boxA.instream1=("sb://remotehost:9900/boxB.outstr4;reconnect-interval=30000")
For more on the parameters usable with remote container connections, see Remote Container Connection
Parameters.
URI Shortcuts
StreamBase URIs recognize defaults, which lets you enter a shortcut URI in many cases. Any unspecified
portion of the URI defaults to the following:
• The default host is localhost.
• The default port is 10000.
• The default container is named default.
• An empty container string selects the default container.
DESCRIPTION
279
StreamBase References
• The default authentication parameters are none. This means that, by default, the server is presumed to
not require authentication.
Using the sbc list command for illustration, all of the following commands produce the same results for a
server with all default settings:
sbc
sbc
sbc
sbc
sbc
sbc
sbc
sbc
sbc
list
-u sb://localhost list
-u sb://localhost:10000 list
-u sb://localhost:10000/ list
-u sb://localhost:10000/default list
-u :10000 list
-u :10000/default list
-u /default list
-u / list
The following examples illustrate various combinations of default and non-default URI sections:
sbc -u :9900 list
sbc -u :9999/ha list
sbc -u /crosseng list
(localhost, port 9900, default container)
(localhost, port 9999, container named ha)
(localhost, port 10000, container named crosseng)
The following examples show several commands to access a remote server running on the default port, 10000.
These commands all produce the same results:
sbc
sbc
sbc
sbc
-u
-u
-u
-u
sb://streamhost:10000/default list
sb://streamhost:10000 list
sb://streamhost/default list
sb://streamhost list
When using authentication parameters, at least one portion of the URI must be present. That is, you cannot
specify only the authentication parameters by themselves, relying on all the URI defaults described above.
You can, however, rely on partial defaulting when using authentication. For example:
sbc
sbc
sbc
sbc
sbc
sbc
-u
-u
-u
-u
-u
-u
:10000;user=rose;password=nuh-UH
":10000;user=rose;password=nuh-UH"
/default;user=rose;password=nuh-UH
"/default;user=rose;password=nuh-UH"
/;user=rose;password=nuh-UH
"/;user=rose;password=nuh-UH"
(Windows)
(UNIX)
(Windows)
(UNIX)
(Windows)
(UNIX)
Most StreamBase utilities recognize the -p option in addition to -u. Use -p to specify only the port number,
defaulting to host=localhost and the default container. The -p option is not supported for StreamBase
applications that have authentication enabled. The following commands are equivalent:
sbc -p 9900 list
sbc -u :9900 list
sbc -u sb://localhost:9900 list
Multiple URI Syntax for HA Scenarios
Certain commands that accept StreamBase URIs can also accept a comma-separated list of URIs to address
more than one StreamBase Server at the same time. The following example requests status information from
two local server instances, one running on port 9900, the other on port 9901:
URI Shortcuts
280
StreamBase References
sbc -u sb://localhost:9900,sb://localhost:9901 status --verbose
You can address multiple servers running on separate hosts. The following example assumes that two server
instances both have identical containers named app2 in which the running application has an input stream
named instream3:
sbc -u sb://primary.example.com:10000,sb://secondary.example.com:10000 enqueue app2.instream3
The same command as above, using defaults for the port number:
sbc -u sb://primary.example.com,sb://secondary.example.com enqueue app2.instream3
You can use the URI shortcuts described above to specify multiple URIs. For example, to check the status of
four server instances running on different ports on localhost, use a command like the following:
sbc -u :9900,:10000,:10099,:11000 status
In general, the multiple URI syntax is accepted by programs based on the StreamBaseClient API,
including sbc, sbfeedsim, and any client applications you write. By contrast, programs based on the
StreamBaseAdminClient API, including sbadmin, are expected to address a single server at a time for
administration purposes, and do not accept the multiple URI syntax. For example, you can issue an sbadmin
shutdown command only to one server at a time.
The STREAMBASE_SERVER environment variable supports a list of multiple URIs. When writing client
code, use the StreamBaseURI.listFromEnvironment class instead of
StreamBaseURI.fromEnvironment to make sure your code supports this feature.
ENVIRONMENT
STREAMBASE_SERVER
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default
StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in
this variable, overriding their built-in default URI, which is sb://localhost:10000. If this
variable is set, you must use the -u option to communicate with any server other than the one
specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
Multiple URI Syntax for HA Scenarios
281
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > StreamBase Command Reference > sbuseradmin
sbuseradmin
StreamBase Authentication System User Management â
management tool
runs the StreamBase authentication system user
SYNOPSIS
sbuseradmin [OPTION]
DESCRIPTION
Use sbuseradmin add, edit, or remove user names, passwords, and user roles from the file-based
authentication list used by the StreamBase authentication system to control access to a running StreamBase
Server. The default location for the authentication database is $STREAMBASE_HOME/etc/sbpasswd.
The user roles currently supported are:
SBAdmin -- StreamBase administrator
SBUser -- StreamBase user
SBDeveloper -- StreamBase developer
OPTIONS
-a
Adds a username to the StreamBase authentication database. This option requires the -n and -r
options, and, optionally, the -p option.
-d username
Deletes an existing username. This option requires the -n option.
-h, --help
Displays help, then exits.
ENVIRONMENT
282
StreamBase References
-l
Lists the contents of the authentication database.
-n username
Specifies a username to add, update, or delete.
-p password
Specifies a password for the username being added or updated. If you omit -p when using the -a
option, the command prompts for a password.
-r user-role
Specifies a user's role, with one of the following keywords: SBAdmin, SBUser, SBDeveloper.
Specify multiple user roles in a comma-separated list. The spelling of the keywords is case-sensitive
and must be exactly as shown.
-u username
Updates information about an existing username. This option requires the -n option and the -p or -r
option or both.
-f path/to/passwd/file , --passwordfile path/to/passwd/file
You can optionally specify the path and name of the password file to use. The path supplied here must
also be set in the authentication section of the StreamBase server configuration file.
--version
Prints version information and exits.
FILES
There is no configuration file for sbuseradmin. The user names and passwords entered by the sbuseradmin
command are saved in the sbpasswd file. By default, the file resides in /opt/streambase/etc.
SEE ALSO
sbadmin
syslog (3)
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
OPTIONS
283
StreamBase References
• Site Map
• Index
HomeInstallationStartAuthoringStreamSQLTest/DebugAPI GuideAdminAdaptersSamplesStudio
GuideReferences
Current Location: Home > StreamBase References > API References
StreamBase API Documentation
StreamBase provides client libraries in four languages for writing extensions to StreamBase. The links on this
page take you to the API reference documentation for each supported language. See the API Guide for
overviews.
• Java API Documentation (Javadoc format)
Use the Java API to write StreamBase clients, custom operators, custom functions, and monitor
listeners. For further information, see the following topics in the API Guide:
• Creating Java Clients
• Using the StreamBase Java Function Wizard
• Using the StreamBase Java Operator Wizard
• Creating Custom Java Embedded Adapters
• Developing StreamBase Monitor Applications
• C++ API Documentation (Doxygen format)
Use the C++ API to write StreamBase clients or custom functions. For further information, see the
following topics in the API Guide:
• Creating C++ Clients
• Creating Custom C++ Functions
• Python API Documentation (Pydoc format)
Use the Python API to write StreamBase clients. See Creating Python Clients in the API Guide.
• .NET API Documentation
Only on StreamBase Windows installations, the above link provides HTML documentation for the
StreamBase .NET API. Use this API to write StreamBase clients and monitor listeners in C# or other
.NET-compliant languages. See Creating .NET Clients in the API Guide.
• Copyright © 2004-2013 StreamBase Systems, Inc. All Rights Reserved.
• Contact Us
StreamBase API Documentation
284