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

The sbc 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
-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), and is not supported 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.

Note

sbc does not support the Encrypted StreamBase Network Protocol; use the jsbc command instead. This means that you cannot use sbc to specify a secure connection with -u sbs://. To connect using sbs, use the jsbc -u command, which takes the following form: jsbc -u"sbs://proxyhost:port;user=sbuser;password=secret" enq InputStream.

-w waitMS, -w waitMS:retryMS

Specifies a number of milliseconds, waitMS, to wait before starting this sbc command. Use -w to start sbc enqueue and sbc dequeue commands in advance while testing, before you start your sbd command to run StreamBase Server. This allows your enqueue or dequeue commands to begin queueing immediately, as soon as the server starts. Once the specified wait time elapses, sbc attempts to connect to the specified server, and continually re-attempts to connect every retryMS milliseconds until connected.

If left unspecified, retryMS is 250 milliseconds, which specifies reconnection attempts four times a second. To change the default retryMS value, use the second form of this option, with both waitMS and retryMS values with a colon separator without spaces. The following example waits 20 seconds before starting to connect to the server, and then retries the connection every half second until successful: sbc -w 20000:500 dequeue

--version

Prints version information and exits.

COMMANDS

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

--timestamp [="format-string"]

Output the current timestamp, optionally formatted according to a quoted format string. If the format string is omitted, format-string defaults to "YYYY-MM-DD HH:mm:ss.SSS[+/-]TTTT" (for example, 2014-09-02 13:50:50.8-0400).

When this command is invoked as sbc, the allowable format strings are based on the ISO C standard strftime API for UNIX platforms and on the Microsoft strftime API for Windows platforms.

When invoked as jsbc, The allowable string formats are the same as those accepted by the expression language's format_time() function, which are based on the java.text.SimpleDateFormat class.

-v

Output human-readable tuples, showing the stream name, a tuple ID number, then each field name and value. By default, tuple IDs are all 0. To obtain zero-based sequence numbers for tuple IDs, set the Java system property streambase.appgen.tupleid to sequential. The sequence of IDs resets for each new sbd server instance. 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)

You can also set streambase.appgen.tupleid=hash. Doing so reports hashed values instead of sequential values. Hashed values are not guaranteed to be unique or repeatable. Use the --json option to output tuples in JSON format.

-w | --where "condition"

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

The --where clause can contain the name of a named schema, such as when specifying the schema of a field of type tuple. For example, for a stream whose field named Bids is defined as having type Transaction:

sbc deq outstream --where "Bids=Transaction(1000,'IBM',243.32)" 
describe name [name ...]

Returns the EventFlow XML description of one or more components in the running application. For streams, the command returns the schema of the specified streams. Specify each component name separated by spaces. You can use container-qualified and module-qualified names. You cannot specify a Query Table as a 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.

If the name you specify is the name of a Module Reference, the command returns module-reference name="name", because the describe command cannot look inside a Module Reference to describe the module components inside. If the name you specify is the name of a Decision Table operator (which is implemented internally as a Module Reference), the command returns:

module-reference name="name-of-decision-table" refers-to="decision-table"
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:

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.

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

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. To enqueue a no-fields tuple with sbc enqueue, send the following commands:

  • On Windows: echo. | sbc enq InputStream

    Do not insert any white space between "echo" and "."

  • On Linux:

    $ sbc enq InputStream
    (type a space and then Return
    ^C
    
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

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] [-m] [-C container-name] [container-connections] type...

Lists entities available on the running sbd server. type can 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.

container-connections

Shows all container connections.

The type argument can be in the form operator:operator-type where operator-type is the name of a StreamBase operator as shown in the Studio Palette view. For example, sbc list operator:union shows all Union operators in the currently running application.

You can spell or abbreviate the operator-type argument in reasonable ways, and can use any letter case. For example, for the Module Reference type, you can enter: module-ref, moduleref, Module-Reference, modulereference, and so on.

There are two exceptions:

  • The Decision Table (DT) operator is not handled directly by sbc list operator. That is, no response is defined for sbc list operator:decision-table. However, you can locate the DT operators in a running application in two steps as follows: Since DT operators are implemented internally as Module References, first get a list of all Module References in your application. Second, run sbc describe on the likely candidates. For example, for the Decision Table operator named analyzeCredit:

    > sbc list module-ref
    module-ref    calcInterest
    module-ref    analyzeCredit
    > sbc describe analyzeCredit
    <module-reference name="analyzeCredit" refers-to="decision-table"/>
    

    The refers-to attribute serves to distinguish Decision Table operators from other Module Reference operators in a large application.

  • The Extension Point operator is not handled by sbc list operator at all. You can find Extension Point operators with sbc list -m, looking for a pattern like the following where the same-named operator (such as Multiply) has several sub-operators, streams, and schemas of its own:

    operator  Multiply.double.Double
    operator  Multiply.double.Union
    operator  Multiply.triple.Triple
    operator  Multiply.triple.Union
    
readTable [OPTIONS] table-path [-w | --where predicate]

Notice the uppercase T in this command, which dumps the contents of Query Tables 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.

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. The -v option cannot be used with --header.

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

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 StreamBase 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 server 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.

ENVIRONMENT

STREAMBASE_SERVER

Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default StreamBase URI for certain StreamBase commands that take the -u option. For example, sbc status honors the variable, but sbc list does not. If set, commands use the URI in this variable. If this variable is set, you must use the -u option to communicate with any server other than the one specified in this variable. You can set a comma-separated list of URIs in the variable, and commands such as sbc status returns status for all listed servers. However, sbc list returns information only for the first listed server. See the sburi(5) 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.