- Index

< Previous |  | Next >

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

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

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

  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:

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

## SEE ALSO

sbd(1)
sbadmin
Using EventFlow Containers
syslog(3)