sbc

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 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

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 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"

Apply the expression condition as a predicate 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]

Reads and enqueues data from stdin. This command can be abbreviated as enq.

By default, enqueue expects comma-separated values in the standard CSV format described in RFC 4180. Fields containing commas must be enclosed in quotation marks.

To specify a field of data type tuple, use nested quotes as described in Viewing and Specifying Tuple Data in CSV Format in the Reference Guide. For example:

To specify a field of data type list, enclose the list in square brackets in standard array notation, using doubled quotes around string list elements as described in Viewing and Specifying List Data in CSV Format in the Reference Guide. For example: "[1, 2, 3]" or "[""alpha"", ""beta"", ""gamma""]".

stream-name

The name of the stream on which to enqueue data. If no stream name is given, the first input field on stdin is expected to be the stream name for each tuple.

If the running application is structured with modules, and the definition of an input stream in a module exposed 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 name, then the inner module name, then stream name. For example:

sbc enq outer.inner.innerInputStream

If you need to distinguish identically named streams in separate containers, you can prefix the container name of interest:

sbc enq container2.outer.inner.innerInputStream

-b size

Use size to indicate the number of tuples to buffer. Default is no buffering.

-d delim

Use delim (a single character, or the 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 field field1 in the input stream, and so on. Only valid when a stream name is provided.

-i interval

Use interval to indicate the enqueuing flush interval in milliseconds. If buffering was not enabled, defaults to 250 milliseconds.

-n string

Consider a field to be null when 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] [-m] type...

Lists entities available on the running sbd server. type may be streams, schemas, operators, input-streams, output-streams, 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 threads, StreamBase creates an implicit module for each running instance.

setDynamicVariable dynvar-path value

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).

sbc

SYNOPSIS

DESCRIPTION

OPTIONS

Note

Note

COMMANDS

ENVIRONMENT

SEE ALSO