StreamBase Environment Variables

StreamBase recognizes a set of environment variables that affect the behavior of StreamBase Server; some variables affect StreamBase Studio. You can define StreamBase environment variables using any of the methods native to your system. Environment variables control and take precedence over certain properties defined in StreamBase Server configuration files.

Environment variable expansion in StreamBase Server configuration files is not limited to the variables on this page. The values of all variables in the environment that starts the StreamBase Server instance can be used, as described in Using Environment Variables in Configuration Files.

The environment variables on this page affect:

  • The behavior of the next StreamBase Server instance or client you start. That is, a change in an environment variable setting does not affect a currently running server or client.

  • The behavior of clients built with the StreamBase C++ or .NET APIs. (Java clients use Java properties instead of environment variables, as described in StreamBase Java Properties.)

The environment variables are:

Notes

  • On Windows, environment variables that you explicitly set take precedence over any corresponding StreamBase keys in the Windows registry. For further information, see Running StreamBase Server as a Windows Service, in the Administration Guide.

  • The StreamBase installer does not set the STREAMBASE_HOME or PATH environment variables, which allows support for installing multiple versions of StreamBase. See StreamBase Command Prompt for details.

SB_CLIENT_CLASSPATH

Use this variable in conjunction with the STREAMBASE_USE_CUSTOM_LOGGING variable. When setting that variable to true, set SB_CLIENT_CLASSPATH to the full, absolute path to sbclient.jar or one of its alternatives (sbclient-no-logging-backend.jar or sbclient-no-logging.jar). See Using StreamBase Logging to understand these alternatives.

STREAMBASE_APPGEN_ERROR_SCHEMA_VERSION

Set to 1 to emit error tuples using the pre-7.1 schema, with the orginalTuple field emitted as a blob. Set to 2 (the default in StreamBase 7.1.0 or later) to emit error tuples using the 7.1+ schema, with originalTuple emitted as a JSON object string. This variable is also available as a Java system property, streambase.appgen.error-schema-version. See Schema of the StreamBase Error Tuple for more on this subject.

STREAMBASE_CODEGEN_TRACE_TUPLES

When set to true, you can use the runtime tracing features of StreamBase Server, as described in Runtime Tracing and Creating Trace Files. You can make the same setting with the -Dstreambase.codegen.trac-tuples=true system property.

STREAMBASE_CRASH_HANDLER

When set to yes (the default), the StreamBase Server process can create a crash dump in the event of a segmentation fault.

STREAMBASE_CRASH_QUIET

When set to yes (the default), the StreamBase Server process can create the crash dump without having to launch a dialog box. The no setting may be appropriate in development, but should not be used in production, or when you are starting the StreamBase Server as a service.

STREAMBASE_CRASH_TRACE

Available on Linux only. If the STREAMBASE_CRASH_HANDLER value is yes (the default), STREAMBASE_CRASH_TRACE=yes causes the crash handler to print a stack trace.

STREAMBASE_DATA

Sets the directory to be used for persistent data when using disk-based Query Tables (if your license enables their use). The precedence order is:

  1. If present on the sbd command line, the path specified in the --datadir option.

  2. The path specified with this STREAMBASE_DATA environment variable, if present.

  3. In the server configuration file, the value of the datadir parameter in the <server> section.

  4. On Windows only, the path specified in the Windows Registry at the following location:

    HKEY_LOCAL_MACHINE\SOFTWARE\StreamBase Systems\StreamBase.n.m\DataDir

  5. If not specified, or if the special value +TEMP+ is used, a temporary directory is created on server startup and deleted on shutdown.

For more information, see Using the Query Table Data Construct in the Authoring Guide.

STREAMBASE_HOME

Specifies the directory in which StreamBase was installed. On UNIX, set this variable before running StreamBase commands. For example:

export STREAMBASE_HOME=/opt/tibco/sb-cep/n.m

The recommended method to set StreamBase environment variables on UNIX, and an essential method if you use the tar.gz installation method, is to use sb-config --env, as shown in this example:

eval `/opt/tibco/sb-cep/n.m/bin/sb-config --env`

On Windows, before release 5.0, this and the PATH environment variable were set by the StreamBase installer. Beginning in release 5.0, StreamBase does not set these variables, because you can now install multiple versions of StreamBase on Windows. StreamBase instead provides the StreamBase Command Prompt in the Start menu. For StreamBase 5.0 and later, run StreamBase utilities and start the sbd server process from a StreamBase Command Prompt, not an ordinary Windows command prompt.

If you have a single StreamBase installation on a Windows machine, you may prefer to set STREAMBASE_HOME and PATH in the global environment with sb-config --setenv . If you have a mixed installation of StreamBase 3.x and 6.x, do not use --setenv, as explained in StreamBase Command Prompt.

The first command below sets the global environment for the currently logged-in Windows user. The second command does the same for all users.

"C:\TIBCO\sb-cep\n.m\bin\sb-config" --setenv
"C:\TIBCO\sb-cep\n.m\bin\sb-config" --setsysenv

STREAMBASE_HOME is referenced in the template sbd.sbconf configuration file for the StreamBase Server. The following is an example of STREAMBASE_HOME used in sbd.sbconf:

<authentication>
     <param name="enabled" value="true"/>
     <param name="type" value="sb-password-file"/>
     <param name="filepath" value="${STREAMBASE_HOME}/etc/sbpasswd"/>
 </authentication>

STREAMBASE_LICENSE

Specifies an alternate path to the StreamBase license file. The default file name is streambase_license.xml and the default location is STREAMBASE_HOME/etc, and these names do not need the environment variable. If you place the license file in any other location, use this variable to point to the full, absolute path to the file. The license file must be in the XML format delivered with the StreamBase installers, but does not need to have the default name if you point to another file name with STREAMBASE_LICENSE.

STREAMBASE_LOG_LEVEL

Sets the level of information, warning, and debug messages emitted by StreamBase Server. For all supported platforms, the log levels are integers from -2 to 3, inclusive. See the table in Log Levels to understand the log level meanings.

Note that setting the STREAMBASE_LOG_LEVEL variable is only useful when running sbd interactively in StreamBase Command Prompts or in UNIX terminal windows. When you run sbd in background mode with the -b flag, it is configured by default to write messages to syslog instead of to stdout. See Server Background Mode and Logging for more information.

STREAMBASE_JVM_ARGS

The variable is largely superseded by the -J option, which is honored by the same set of commands listed below. For more on the -J option, see the reference page for any of those commands.

Use STREAMBASE_JVM_ARGS to specify one or more arguments to append to the default arguments for the JVM that will run a StreamBase command. For example, set STREAMBASE_JVM_ARGS=-Xms1024M to specify a minimum of one gigabyte of RAM. Remember that if you change any of the primary memory-setting JVM arguments (-Xms or -Xmx), then the StreamBase Server defaults for those settings no longer apply. Thus, if you set one of these settings with this variable, set them all.

The following commands from the base StreamBase kit check for and append the contents of this variable to their startup routines: jsbadmin, jsbc, jsbclientgen, sbargen, sbbundle, sbcipher, sbd, sbfeedsim, sbprofile, sbproxy, sbrecord, and sbtest. The following commands from external adapter kits also respond to this variable: sb-ems-* and sb-jdbc.

Because so many commands are affected by this variable, it is unwise to export this variable to the global environment, because the JVM settings for one command are not likely to be appropriate for all commands. Instead, use it for ad hoc adjustments to the JVM arguments per invocation. For the Bash shell on UNIX, use syntax like the following:

STREAMBASE_JVM_ARGS=settings sbbundle sbbundle-args

For Windows, you can configure per-invocation usage by wrapping the command of interest in a batch script, surrounded by setlocal and endlocal commands.

STREAMBASE_MAX_INPUT_PACKET_SIZE

Use STREAMBASE_MAX_INPUT_PACKET_SIZE to increase the maximum size of packets used by C++ clients when communicating with StreamBase Server. If unspecified, the default is 1 megabyte.

STREAMBASE_QUIESCENT_LIMIT

This environment variable controls how many milliseconds a C++ StreamBase dequeuing client will tolerate not receiving anything from the StreamBase Server to which it is connected. The default value is 120 seconds (120000). By default, StreamBase Servers emit client heartbeats every 10 seconds, so that StreamBase applications have no requirement to send data regularly.

StreamBase Servers can be configured to send heartbeats faster, slower, or not at all. The quiescent timer only starts after the first heartbeat is received; so if a server never sends a heartbeat, clients will not have quiescent protection.

STREAMBASE_RECONNECT_SLEEP

When designing a high availability StreamBase cluster, you can use this environment variable for clients, to set how often the client should try to reconnect to the primary or secondary machine when the connection to the server is dropped. The value is in milliseconds. The default is 5000 (5 seconds). This environment variable is useful with C++ clients. By contrast, Java clients can use the streambase.reconnect-sleep system property as described in StreamBase Java Properties.

STREAMBASE_RETITLE_TERMINALS

If set to any value, StreamBase programs assign a terminal window title to match the name of the executable being run. By default, terminal titles are not affected. On UNIX, this can be helpful if you have many terminal windows open for sbd, sbfeedsim, sbc dequeue, sbmonitor, and so on.

STREAMBASE_SERVER

The URI for StreamBase Server. The default is sb://localhost:10000. You can set this environment variable if the Server is on another node or listening on another port. For example, if the Server is running on host server.example.com at port 20000, set the STREAMBASE_SERVER value as sb://server.example.com:20000. This environment variable can be read by C++ clients, adapters, and most StreamBase command-line utilities (such as sbc) to determine a non-default StreamBase Server location or port.

STREAMBASE_STUDIO_VMARGS

Specifies a list of arguments for the JVM that runs StreamBase Studio. This variable should only be necessary on rare occasions, usually under the direction of TIBCO Technical Support.

Important

Using this variable overrides and replaces the default vmargs passed to Studio. If you use the variable for any purpose, you MUST include the default values like the following.

STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx768M

On 64-bit platforms with physical RAM of 4 GB or more, you can set the –Xmx setting to a larger value, such as –Xmx1024m or even –Xmx2048m.

To use this environment variable correctly, set the default values, then add your setting at the end:

STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx768M \
    -Dyour-setting

For example:

STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx768M \
    -Dstreambase.tuple-charset=UTF-8

You may also want to re-specify the default GC settings as described in Garbage Collection Policy Settings

STREAMBASE_TCP_NODELAY

Set STREAMBASE_TCP_NODELAY to true to disable the Nagle algorithm on network connections. In addition, for Java clients, you can set the system property streambase.tcp.nodelay to true. While it is best to set STREAMBASE_TCP_NODELAY on both the client and server, setting it on the server is often more important than setting it on the client.

Note

Disabling the Nagle algorithm can improve latency characteristics, but it can also make network utilization less efficient. This may reduce the maximum throughput rates for a given network interface.

STREAMBASE_TUPLE_CONNECTION_QUIESCENT_LIMIT

When designing a high availability StreamBase cluster, you can use this environment variable in conjunction with client dequeue heartbeats to set the timeout for dequeues. The value is in milliseconds, and the default is 120000 (120 seconds). By default, StreamBase Servers emit client heartbeats every 10 seconds, so that StreamBase applications have no requirement to send data regularly. StreamBase Servers can be configured to send heartbeats faster, slower, or not at all. The quiescent timer only starts after the first heartbeat is received. Thus, if a server never sends a heartbeat, clients will not have quiescent protection.

This environment variable is useful with C++ clients. By contrast, Java clients can use the streambase.tuple-connection-quiescent-limit system property as described in StreamBase Java Properties.

STREAMBASE_TUPLE_CONNECTION_TIMEOUT

When designing a high availability StreamBase cluster, you can use this environment variable for clients, to set a timeout value on reads and writes between the client and server. This timeout is used by the client to recognize failure of the server. Consider carefully when using this property. A timeout value that is too long may cause the client to hang for that period before it fails over to the other server. Too short of a value may cause the client to disconnect prematurely from the server if the server is busy. The value is in milliseconds, and the default is 15000 (15 seconds). A value of 0 disables the timeout (some operations will block forever). For further information, see Creating C++ Clients.

This environment variable is useful with C++ clients. By contrast, Java clients can use the streambase.tuple-connection-timeout system property as described in StreamBase Java Properties.

STREAMBASE_UNIT_TEST_SERVER_CONF

Path to and name of the StreamBase Server configuration file used for conducting unit tests, which must contain the path to the directory containing your JUnit test class file (usually the java-bin folder of the Studio workspace). Can be specified or overridden using the streambase.unit-test.server-conf system property or the sbunit command.

STREAMBASE_USE_INTERNAL_JDK

If set to true (the default value), or if not set, StreamBase uses its internal JDK installed in streambase-install-dir/jre, and ignores any setting of the JAVA_HOME environment variable. This applies to both StreamBase Studio and StreamBase Server run independently of Studio with the sbd command.

If set to false, Studio and sbd use the external JDK defined in the JAVA_HOME environment variable. JAVA_HOME must be set to the full, absolute path to the top-level directory containing your JDK.

If set to false, but no JAVA_HOME is defined, StreamBase searches the system PATH for a JDK. If not found, StreamBase looks in standard installation locations for a JDK. If still not found, neither Studio nor sbd will start.

STREAMBASE_USE_CUSTOM_LOGGING

If set to true, StreamBase automatically calls sbclient-no-logging-backend.jar wherever sbclient.jar would be used. This allows you to use an alternative Java logging system as described on Using StreamBase Logging. When set to true, the JAR files that support your alternative logging system must be specified on the Server's classpath, or in a <jar> child element of the <java-vm> element of the server configuration file. You can also specify the path to sbclient.jar (and its embedded Logback logging) or to one of its alternatives with the SB_CLIENT_CLASSPATH environment variable described above in SB_CLIENT_CLASSPATH.

STREAMBASE_XMLRPC_TIMEOUT

Specify a timeout value in milliseconds that clients built with the StreamBase Client Library will wait for a response from StreamBase Server. This setting applies in the rare case when the server is alive and listening, but not responding.

STUDIO_BOOT_CLASSPATH

Use this environment variable to place Java code in the classpath of StreamBase Studio, and of StreamBase Server as launched from Studio. For example, set STUDIO_BOOT_CLASSPATH, pointing to the full, absolute path to a database vendor's JDBC JAR file in order to use a JDBC database as the data source for a feed simulation. See Feed Simulation with a JDBC Data Source for details.

TMP

StreamBase Server writes internally generated temporary files to a temporary directory. The location of the temporary directory used is the first valid directory path found in the following search sequence:

—Specified with the streambase.tmpdir Java system property
—The value of the TMP environment variable
—Specified with the java.io.tmpdir system property (Windows only)
/var/tmp on UNIX or C:\Windows\Temp on Windows

Because the TMP environment variable is used before java.io.tmpdir, on Windows, make sure that any TMP environment variable you use specifies a path with no spaces in any path element. If another program requires a TMP path with spaces, then use the streambase.tmpdir property to override the temporary directory location for StreamBase Server.

The java.io.tmpdir system property uses a platform-specific algorithm to identify a temporary directory. On Windows, this search calls the Windows API GetTempPath(), which searches the TMP, TEMP, and USERPROFILE environment variables in that order. In Windows domain login environments, it is possible that your USERPROFILE directory is on a network share, and it is also possible that TMP or TEMP variables point to a subdirectory of your USERPROFILE directory on a network share. In these cases, explicitly set streambase.tmpdir or explicitly set TMP in the environment that runs StreamBase Server to avoid writing temporary files to a network location.