Using the External Process Operator

Select either CommandLine or Arguments to specify how you will enter the command to be run by this operator. Select CommandLine to enter the command as a StreamBase expression. Specify Arguments to enter the command in table form, with one row for each command, switch, and option.

If you selected CommandLine as the Operator Type, use this field to specify the full command to be run, expressed in the form of a StreamBase expression. You must surround the entire command line with single quotes to ensure that the expression is evaluated as an expression, even if your expression contains only literal strings.

The command expression can contain the name of one or more fields in the incoming command tuple on the input port. In this case, the value of each specified field is substituted when the command is run.

Using an expression to specify the command to be run allows you to evaluate variables at runtime, instead of passing the variables to the operator in the input command tuple.,

When the command line you want to run contains single quotes, escape them with backslash-double-quote to prevent their interpretation as the end of the expression.

If you select this check box, the schema sent to the output port is extended with a field containing the exact command line run, with all variables resolved. Use this check box for debugging while developing your operator.

Specify either blob or string (the default). This setting specifies the data type of three fields of the output tuple: stdout, stderr, and (if enabled) cmdline.

If you selected Arguments as the Operator Type, use the Command Arguments table to specify the command to be run and its arguments. Specify the command name in row 1, using a relative or absolute path to the command. In subsequent rows, you can optionally add the exact switches and arguments with which to run the command, split into separate rows on whitespace boundaries. That is, if you want to run the command sbadmin setLeadershipStatus NON_LEADER, specify the three parts of the command on three rows. To run the same command except specifying a StreamBase URI, use five rows as shown in this example:

sbadmin
-u
sb://remotesbhost:10001/appcontainer
setLeadershipStatus
LEADER

Any row of the Command Arguments section can contain the name of a field in the incoming input tuple. In this case, the contents of that field are substituted when the command is run. For example, your input command tuple might contain a field named serverURI that contains the programmatically determined URI of one member of a StreamBase Server cluster. In this case, specify five rows in the Arguments section, containing:

sbadmin
-u
serverURI
setleadershipStatus
NON_LEADER

If you have a name collision with a field in the input tuple, you can use quotes to escape the interpretation as a field name. For example, if you wanted the operator to run the command cat file1, but there happens to be a field in the input tuple also named file1, enter the following in the command arguments table:

cat
"file1"

If you selected Arguments as the Operator Type, and if you enable the Include arguments and environment variables in output option on the Advanced tab, then the string you specify in this field is prepended to the contents of any command argument fields sent to the output port. The default value is arg_.

Use the Environment table to specify any environment variables needed by the command you want to run, that are not already in the environment of the containing StreamBase Server, or whose values you want to change for the purpose of running the specified command. For each row, specify the variable name, an equals sign, and value. For example:

If you specify any environment variables, and if you enable the Include arguments and environment variables in output option on the Advanced tab, then the string you specify in this field is prepended to the contents of any environment variable fields sent to the output port. The default value is env_.

If you select this check box, the schema sent to the output port is extended with the fields of the command tuple received at the input port.

If you use the check box above, the string you specify in this field is prepended to the contents of each input tuple field sent to the output port. The default value is input_.

If you select this check box, the schema sent to the output port is extended with fields containing the path of the command run, the switches and arguments run, and any environment variables specified in the operator.

Use this field to specify a working directory for the command to be run. The default working directory is that of the StreamBase Server that runs this operator. Specify as a StreamBase expression the full absolute path, or a path relative to the working directory of the StreamBase Server that runs this operator. You must surround the entire expression with single quotes to ensure that the expression is evaluated as an expression, even if your expression contains only literal strings.

Select this check box to run the specified command without holding any locks. This allows you to call sbadmin shutdown and other such commands that attempt to place locks, without causing a deadlock situation. With this option enabled, this operator's output tuple occurs asynchronously, similar to marking the operator to run in parallel threads in the Concurrency tab. The difference is that with the parallel threads setting, the operator's command can still place a lock.

This option is enabled when the previous option is selected. The default value of 1 means that the operator's commands are performed serially. This is ideal behavior when using the operator to perform commands that must be run in sequence, such as Add Container, then Modify Container. Positive values specify a limit on the number of threads to spawn to perform the operator's requested operations. Negative or 0 means the operator spawns an unlimited number of threads.