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 TIBCO recommends migrating to deployment files for this purpose.

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

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

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"

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)