sbc
StreamBase Client — starts the StreamBase client to send commands to a running server
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 onlocalhost
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
, anddequeue
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 usingsbs
, 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 yourenqueue
ordequeue
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 everyretryMS
milliseconds until connected.If left unspecified,
retryMS
is 250 milliseconds, which specifies reconnection attempts four times a second. To change the defaultretryMS
value, use the second form of this option, with bothwaitMS
andretryMS
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
- 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 nameddefault
. 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 nameddefault
. This option takes the same=input
and=output
modifiers as--all
. -d
delim
-
Use
delim
(a single character, or the literal stringtab
) 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 defaultquotechar
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 namedoutstream
that has a field namedsymbol
: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="
, 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:name
"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 tostream-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 stringtab
) 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 isnull
. -q
quotechar
-
Use
quotechar
(a single character) as a quotation mark. The defaultquotechar
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 bestreams
,schemas
,operators
,input-streams
,output-streams
,container-connections
, ortables
(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 formoperator:
whereoperator-type
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 | --wherepredicate
] -
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.
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 thetable-path
. For example, for table namedSimpleTable
that contains a field namedcity
: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 stringtab
) 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 defaultquotechar
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 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 issb://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).