C++ Native Functions: spl.utility

This page documents native functions that can be invoked from SPL, including the SPL interfaces that can be used to invoke each of the native functions.

Functions

public uint64 PEID()

Return the PE ID for the current processing element that this operator is executing in.


Returns: The PE ID for the current processing element.

public stateful void abort()

Abort program execution.

<string T> public void appLog(enum {error, warn, info} logLevel, T message)

Log a message in the logging system.

Parameters

logLevel: Classification of the log level (as error, warn, or info). Use the Level enumeration in the spl::Log to specify the log level.
message: Message to be logged.

<string T> public void appLog(enum {error, warn, info} logLevel, T message, T aspect)

Log a message in the logging system.

Parameters

logLevel: Classification of the log level (as error, warn, or info). Use the Level enumeration in the spl::Log to specify the log level.
message: Message to be logged.
aspect: Message category (can be used for filtering when inspecting messages).

<string T> public void appTrc(enum {error, warn, info, debug, trace} traceLevel, T message)

Log a message in the tracing system.

Parameters

traceLevel: Classification of the trace level (as error, warn, info, debug or trace). Use the Level enumeration in the spl::Trace to specify the trace level.
message: Message to be logged.

<string T> public void appTrc(enum {error, warn, info, debug, trace} traceLevel, T message, T aspect)

Log a message in the tracing system.

Parameters

traceLevel: Classification of the trace level (as error, warn, info, debug or trace). Use the Level enumeration in the spl::Trace to specify the trace level.
message: Message to be logged.
aspect: Message category (can be used for filtering when inspecting messages).

public void assert (boolean condition)

Check assertion at runtime in non-optimized code.

Parameters

condition: If false, print a message to the standard output, stdout, log a message, and abort.

<string T> public void assert (boolean condition, T msg)

Check assertion at runtime in non-optimized code (with a specified message).

Parameters

condition: If false, print a message to the standard output, stdout, log a message, and abort.
msg: Message to be printed.

public void assert (list<boolean> condition)

Check assertion at runtime in non-optimized code.

Parameters

condition: List of conditions. If any are false, print a message to the standard output, stdout, log a message, and abort.

[N] public void assert (list<boolean>[N] condition)

Check assertion at runtime in non-optimized code.

Parameters

condition: List of conditions. If any are false, print a message to the standard output, stdout, log a message, and abort.

<any T> public void assert (map<T, boolean> condition)

Check assertion at runtime in non-optimized code.

Parameters

condition: Map of conditions. If any are false, print a message to the standard output, stdout, log a message, and abort.

<any T>[N] public void assert (map<T, boolean>[N] condition)

Check assertion at runtime in non-optimized code.

Parameters

condition: Map of conditions if any are false, print a message to the standard output, stdout, log a message, and abort.

<tuple T1, tuple T2> public void assignFrom (mutable T1 lhs, T2 rhs)

Assign matching attributes of a tuple from another one. An attribute matches if the name is the same, and the type is either the same, or the type to be copied from is T and the type to be copied to is optional<T>.

Parameters

lhs: Destination tuple.
rhs: Source tuple.

public stateful void block(float64 time)

Block until shutdown is requested, or the specified amount of time has elapsed, whichever comes first.

Parameters

time: Maximum wait time in seconds (fractional values are allowed).

public stateful void createCustomMetric(rstring name, rstring description, enum{Gauge,Counter,Time} kind, int64 value)

Create the specified custom metric for the current operator and set its initial value. If Metric name already exists, does nothing starting with IBM Streams v4.3.0 and throws SPLRuntimeInvalidMetricException for versions prior to 4.3.0.

Parameters

name: The name of the metric.
description: A description of the metric.
kind: The kind of the metric (value of enum{Gauge,Counter,Time}).
value: The initial value for the metric.

Throws

SPLRuntimeInvalidMetricException: If the metric already exists (prior to IBM Streams v4.3.0).

public stateful void createCustomMetric(ustring name, ustring description, enum{Gauge,Counter,Time} kind, int64 value)

Parameters

name: The name of the metric.
description: A description of the metric.
kind: The kind of the metric (value of enum{Gauge,Counter,Time}).
value: The initial value for the metric.

Throws

SPLRuntimeInvalidMetricException: If the metric already exists (prior to IBM Streams v4.3.0).

public rstring dataDirectory()

Return the absolute pathname to the runtime location of the data directory for the SPL application. To use this function you must define a data directory for the application.


Returns: Data directory (an absolute path).

public rstring domainID()

Return the domain ID for the domain that the PE is running in.


Returns: The domain ID for the current processing element, or, if running in standalone mode, the name of the user running the PE.

<tuple T> public boolean evalPredicate (rstring splExpr, T tup, mutable int32 error)

Evaluates an SPL predicate expression, represented as an rstring, using the given tuple. The predicate expression has the same syntax and limitations as the filter parameter to the Import operator.

Parameters

splExpr: The SPL predicate expression to evaluate, in rstring form. For example: (a == "hi") && ("x" in b || g[4] > 6.7 || id % 8 == 3).
tup: The tuple to use in the evaluation.
error: 0 for success, or greater than 0 if there is an error parsing the predicate expression.

Returns

The result of evaluating the predicate expression.

public void flushStdio()

Flush all stdio output streams. This will ensure that printString and other print output is flushed and written to the standard output, stdout.

public rstring formatNumber(float64 value)

Format a float using locale specific format. The number is returned as a string with the locale specific grouping and decimal point.

Parameters

value: Value to be formatted.

Returns

The input value as a string using locale specific number format.

public rstring formatNumber(float64 value, uint32 width, uint32 precision, boolean scientific)

Format a float using locale specific format. The number is returned as a string with the locale specific grouping and decimal point. If scientific form is specified, there is one digit before the decimal point and a two-digit exponent following the letter 'e'.

Parameters

value: Value to be formatted.
width: Minimal field width.
precision: Number of digits of precision.
scientific: Set to true if scientific form should be used.

Returns

The input value as a string using locale specific number format.

public rstring formatNumber(int64 value)

Format an integer using locale specific format. The number is returned as a string with the locale specific grouping.

Parameters

value: Value to be formatted.

Returns

The input value as a string using locale specific number format.

public rstring formatNumber(int64 value, uint32 width)

Format an integer using locale specific format. The number is returned as a string with the locale specific grouping.

Parameters

value: Value to be formatted.
width: Minimal field width.

Returns

The input value as a string using locale specific number format.

public list<int32> getAllChannels()

Get the parallel channel indexes for all nested parallel regions.


Returns: The indexes of the nested parallel channels.

public list<int32> getAllMaxChannels()

Get the maximum number of parallel channels for all nested parallel regions.


Returns: The maximum number of parallel channels for all nested parallel regions.

public stateful int32 getApplicationConfiguration(mutable map<rstring, rstring> properties, rstring name)

Get the application configuration with the given name. The application configuration is a set of properties where each key and its value in the property set is a string. This method copies all the properties from the configuration into the properties output map.

Parameters

properties: Output map where the configuration properties are to be inserted.
name: Application configuration name.

Returns

0 if the configuration specified by name was found; otherwise -1.

public stateful rstring getApplicationConfigurationProperty(rstring configName, rstring propertyName, mutable int32 errorCode)

Get the value associated with the given configuration property propertyName from the configuration identified by configName. An empty string is returned if there is no value associated with propertyName in the configuration, or the configuration does not exist.

Parameters

configName: Application configuration name.
propertyName: Configuration property name. configuration specified by configName could not be found, -2 if the configuration property specified by propertyName could not be found.
errorCode: Output parameter, set to 0 for success, -1 if the configuration specified by configName could not be found, -2 if the configuration property specified by propertyName could not be found.

Returns

The value associated with the property name or an empty string if the configuration or the property does not exist.

public stateful rstring getApplicationConfigurationProperty(rstring configName, rstring propertyName, rstring defaultValue)

Get the value associated with the given configuration property propertyName from the configuration identified by configName. The defaultValue is returned if there is no value associated with propertyName in the configuration, or the configuration does not exist.

Parameters

configName: Application configuration name.
propertyName: Configuration property name.
defaultValue: Default value for the configuration property.

Returns

The value associated with the property name or defaultValue if the associated value or the configuration does not exist.

public rstring getApplicationDir()

Return the runtime location of the full path to the SPL application directory.


Returns: Path of the application directory.

public rstring getApplicationName()

Return the name of the application that is executing this operator.


Returns: The name of the application.

public int32 getChannel()

Get the parallel channel index. Note that in the context of a nested parallel region the range of indexes considers replicated nested regions.


Returns: The index of the parallel channel.

public list<rstring> getCompileTimeListValue(rstring name)

Return the named compiler invocation argument list value (name="value0,value1"). It is an error if the name is not specified on the compiler invocation.

Parameters

name: The name of the argument time value.

Returns

The value as a list of rstrings.

public rstring getCompileTimeValue(rstring name)

Return a named compiler invocation argument value (name=value). It is an error if the name is not specified on the compiler invocation.

Parameters

name: Desired argument name.

Returns

String value of the named compiler argument.

public rstring getCompileTimeValue(rstring name, rstring defaultValue)

Return a named compiler invocation argument value (name=value). If the named argument is not found, use the default value.

Parameters

name: Desired argument name.
defaultValue: Value to be used if the named argument is not found.

Returns

String value of the named compiler argument if present, or default value.

public stateful rstring getConfiguredHostName()

Get the hostname used by the streams instance for this host. This returns the full hostname (with domain) for the interface configured for use by the streams instance for this host. This may differ from the IP address for the name returned from getHostName() if there are multiple network interfaces on this host.

Returns

The hostname for the configured streams interface for this host representation.

Throws

SPLRuntimeException: If unsuccessful.

public int32 getConsistentRegionIndex()

Gets the index of the consistent region.


Returns: Index of the consistent region, or -1 if the operator is not in a consistent region.

public stateful list<rstring> getCustomMetricNames()

Return the names of the custom metrics for the current operator.


Returns: List of names of custom metrics.

public stateful void getCustomMetricValue(rstring name, mutable int64 value)

Get the specified custom metric value for the current operator.

Parameters

name: The name of the metric.
value: Value of the specified custom metric for the current operator.

Throws

SPLRuntimeInvalidMetricException: If the metric does not exist.

public stateful void getCustomMetricValue(ustring name, mutable int64 value)

Get the specified custom metric value for the current operator.

Parameters

name: The name of the metric.
value: Value of the specified custom metric for the current operator.

Throws

SPLRuntimeInvalidMetricException: If the metric does not exist.

public float64 getDrainTimeout()

Gets the drain timeout of a consistent region.


Returns: The drain timeout in seconds, or -1 if the operator is not in a consistent region.

public stateful rstring getEnvironmentVariable(rstring name)

Get the value of an environment variable.

Parameters

name: Environment variable name.

Returns

The value for the environment variable, or an empty string if the environment variable is not set.

public stateful rstring getEnvironmentVariable(rstring name, mutable boolean isSet)

Get the value of an environment variable.

Parameters

name: Environment variable name.
isSet: This parameter is set to true if the environment variable is found, otherwise to false. This parameter can be used to differentiate between an empty value and an unset variable.

Returns

The value for the environment variable, or an empty string if the environment variable is not set.

public stateful rstring getEnvironmentVariable(rstring name, rstring defaultValue)

Get the value of an environment variable.

Parameters

name: Environment variable name.
defaultValue: Default value for the environment variable.

Returns

The value for the environment variable if set, otherwise the default value.

public int32 getExceptionPortExportProperties(mutable list<tuple<rstring name, rstring value, rstring typ>> properties, uint32 port)

Get the export properties for an output port that produces a stream that is exported with properties.

Parameters

properties: Output list of tuples of type tuple<rstring name, rstring value, rstring typ> representing the current export properties for the stream output by this port, where name is the name of the property. value is the value of the property as a literal value of the type for the property, and typ is the type of the property (one of: int64, float64, rstring, list<int64>, list<float64>, list<rstring>.
port: Exception port index.

Returns

Error return code: 0 for success, or 1 for an invalid port or a port that does not produce a stream that is exported with properties.

public stateful void getExceptionPortMetricValue(uint32 port, enum {nTuplesSubmitted, nWindowPunctsSubmitted, nFinalPunctsSubmitted} name, mutable int64 value)

Get the specified exception port metric value for the current operator.

Parameters

port: Exception port index.
name: The name of the metric.
value: Value of the specified exception port metric for the current operator.

Throws

SPLRuntimeInvalidIndexException: If the port index is out of bounds.

public stateful rstring getHostName()

Get the host name.

Returns

Full host name (with the domain) of the node running this operator as returned by the system call gethostname().

Throws

SPLRuntimeException: If unsuccessful.

public stateful rstring getIPAddress()

Get the IP address for the current host.


Returns: The IP address as a string.

public rstring getInputPortImportFilterExpression(uint32 port, mutable int32 error)

Get the filter expression for an input port that receives a stream that is imported.

Parameters

port: Input port index.
error: Return code: 0 for success, 1 for an invalid port or a port that does not receive a stream that is imported.

Returns

The filter expression for the port, or an empty string if the filter expression is empty or there is an error.

public rstring getInputPortImportSubscription(uint32 port, mutable int32 error)

Get the import subscription for an input port that receives a stream that is imported by subscription.

Parameters

port: Input port index.
error: Return code: 0 for success, 1 for an invalid port or a port that does not receive a stream that is imported by subscription.

Returns

The subscription for the port, or an empty string on error.

public stateful void getInputPortMetricValue(uint32 port, enum {nTuplesProcessed, nTuplesDropped, nTuplesQueued, nWindowPunctsProcessed, nFinalPunctsProcessed, nWindowPunctsQueued, nFinalPunctsQueued, queueSize, maxItemsQueued, recentMaxItemsQueued, recentMaxItemsQueuedInterval, nEnqueueWaits} name, mutable int64 value)

Get the specified input port metric value for the current operator.

Parameters

port: Input port index.
name: The name of the metric.
value: Value of the specified input port metric for the current operator.

Throws

SPLRuntimeInvalidIndexException: If the port index is out of bounds.

public rstring getJobGroup()

Return the name of the job group for the current job that this operator is executing in.


Returns: The name of the job group.

public rstring getJobName()

Return the name of the current job that this operator is executing in.


Returns: The name of the current job.

public int32 getLocalChannel()

Get the parallel channel index. Note that in the context of nested parallel regions the returned index does not consider replicated nested regions.


Returns: The index of the parallel channel.

public int32 getLocalMaxChannels()

Get the maximum number of parallel channels. Note that in the context of nested parallel regions the returned index does not consider replicated nested regions.


Returns: The maximum number of parallel channels.

public rstring getMainCompositeName()

Return the name of the main composite.


Returns: A string containing the expanded main composite name.

public int32 getMaxChannels()

Get the maximum number of parallel channels. Note that in the context of a nested parallel region the range of indexes considers replicated nested regions.


Returns: The maximum number of parallel channels.

public stateful void getOperatorMetricValue(enum {relativeOperatorCost} name, mutable int64 value)

Get the specified system metric value for the current operator.

Parameters

name: The name of the metric.
value: Value of the specified system metric for the current operator.

public int32 getOutputPortCongestionFactor(uint32 port)

Return the maximum congestion factor for all the connections from an output port that connect to another PE.

Parameters

port: Output port index.

Returns

-1 for an invalid port, or the congestion factor (0 to 100).

public int32 getOutputPortExportProperties(mutable list<tuple<rstring name, rstring value, rstring typ>> properties, uint32 port)

Get the export properties for an output port that produces a stream that is exported with properties.

Parameters

properties: Output list of tuples of type tuple<rstring name, rstring value, rstring typ> representing the current export properties for the stream output by this port, where name is the name of the property. value is the value of the property as a literal value of the type for the property, and typ is the type of the property (one of: int64, float64, rstring, list<int64>, list<float64>, list<rstring>.
port: Output port index.

Returns

Error return code: 0 for success, or 1 for an invalid port or a port that does not produce a stream that is exported with properties.

public stateful void getOutputPortMetricValue(uint32 port, enum {nTuplesSubmitted, nWindowPunctsSubmitted, nFinalPunctsSubmitted} name, mutable int64 value)

Get the specified output port metric value for the current operator.

Parameters

port: Output port index.
name: The name of the metric.
value: Value of the specified output port metric for the current operator.

Throws

SPLRuntimeInvalidIndexException: If the port index is out of bounds.

public int32 getPEOutputPortConnections (uint32 port, mutable list<tuple<int64 pe, int64 port, uint8 congestionFactor, uint64 nTuplesFilteredOut>> connections)

Return the connection information for an output port that connects to another PE.

For example, in SPL: mutable Sys.PEConnections conns; int32 ret = getPEOutputPortConnections(0, conns);

Parameters

port: Output port index.
connections: Output list of tuples containing information for each output connection.

Returns

Error return code: 0 for success, -1 for an invalid port index, -2 for an invalid list.

public uint32 getRelaunchCount()

Return the number of times the PE that the operator is executing in has been relaunched.


Returns: The relaunch count of the PE.

public int32 getResetAttempt()

If the operator is in a consistent region, this function returns the number of attempts made to reset the consistent region to a consistent state. This function returns the current number of reset attempts if the region is resetting, or the number of reset attempts made for the last reset.


Returns: The number of reset attempts, or -1 if the operator is not in a consistent region, or has not yet reset after an operator restart.

public float64 getResetTimeout()

Gets the reset timeout of a consistent region.


Returns: The reset timeout in seconds, or -1 if the operator is not in a consistent region.

public int64 getSequenceId()

Gets the current sequence identifier of a consistent region. This is the identifier that a consistent region drain or reset is associated with. Immediately after operator startup, this function returns 1. On operator restart, this function returns -1 until the operator has reset.


Returns: The current sequence identifier for a drain or reset, or -1 if the operator is not in a consistent region or has not yet reset after an operator restart.

public stateful rstring getShortHostName()

Get the short host name.

Returns

Short host name (without the domain) of the node running this operator.

Throws

SPLRuntimeException: If unsuccessful.

public list<rstring> getSubmissionTimeListValue(rstring name)

Return the named submission time list value (name="value0,value1"). This function can appear only in a composite operator scope.

Parameters

name: The name of the submission time value.

Returns

The submission time value (submission fails if the argument is not present).

public list<rstring> getSubmissionTimeListValue(rstring name, list<rstring> default)

Return the named submission time list value (name="value0,value1"). This function can appear only in a composite operator scope.

Parameters

name: The name of the submission time value.
default: Value to be returned if the submission time value is not present.

Returns

The submission time value, or the default value if it is not present.

public rstring getSubmissionTimeValue(rstring name)

Return the named submission time value (name="value"). This function can appear only in a composite operator scope.

Parameters

name: The name of the submission time value.

Returns

The submission time value (submission fails if the argument is not present).

public rstring getSubmissionTimeValue(rstring name, rstring default)

Return the named submission time value (name="value"). This function can appear only in a composite operator scope.

Parameters

name: The name of the submission time value.
default: Value to be returned if the submission time value is not present.

Returns

The submission time value, or the default value if it is not present.

public rstring getThisCompositeInstanceName()

Return the name of the current composite instance. For example, this may be used to assure a unique name generation for parameters and files.

Note: This function may not be used in the config clause of a composite or within a static type definition.


Returns: A string containing the expanded composite instance name.

public rstring getThisFileDir()

Return the full pathname of the runtime location of the directory containing the current SPL file as an rstring.


Returns: Path name of the directory containing the current SPL file.

public rstring getThisFileName()

Return the current SPL file name as an rstring.


Returns: File name of the current SPL file.

public rstring getThisFilePath()

Return the full pathname of the runtime location of the current SPL file as an rstring.


Returns: Path name for the current SPL file.

public int32 getThisLine()

Return the current line number as an int32.


Returns: Line number for the current line in the SPL file.

public rstring getThisOperatorLogicalName()

Get the logical name of the operator.


Returns: The logical name of the operator.

public rstring getThisOperatorName()

Get the physical name of the operator.


Returns: The physical name of the operator.

public rstring getThisToolkitDir()

Return the full path to the runtime location of the root directory of the toolkit containing the current SPL file.


Returns: Path to the toolkit root directory.

public stateful boolean hasCustomMetric(rstring name)

Check if the specified custom metric exists.

Parameters

name: The name of the metric.

Returns

The value true if the custom metric exists, otherwise false.

public stateful boolean hasCustomMetric(ustring name)

Check if the specified custom metric exists.

Parameters

name: The name of the metric.

Returns

The value true if the custom metric exists, otherwise false.

<any T> public uint64 hashCode (T v)

Compute the hash of a value.

The hash function is designed to return a fixed output value for a given input value, and to reduce the likelihood of returning the same output value for different input values. The hash function can be used to map a set of input values to a smaller range of output values, for example, by performing a modulo operation on the returned hash value and the size of the desired range. In cases where there may be patterns in the input values (such as all even numbers), a more even distribution of output values may be possible by using a prime number as the modulus.

The current hash function uses the C++ standard library std::hash function.

Parameters

v: Value.

Returns

Hash of the value.

<list L> public list<uint64> hashCodeForEach (L l)

Compute hashes of a list of values, using the same hashing method as hashCode().

Parameters

l: List of values.

Returns

List of the hashes of the values.

<tuple T> public int32 inputPort(T inputStream)

Return the index corresponding to an input port.

Parameters

inputStream: Stream name, port name or alias.

Returns

Index of the input port.

public rstring instanceID()

Return the Streams instance ID that the PE is running in.


Returns: The Streams instance ID for the current processing element (or the username if running in standalone mode).

public boolean isConsistentInputPort(uint32 port)

Check if the input port is consistent. An input port is consistent if all its input streams are produced by operators that belong to the same consistent region.

Parameters

port: Input port index.

Returns

The value true if the input port is consistent, false otherwise.

public boolean isControlInputPort(uint32 port)

Check if the input port is a control port.

Parameters

port: Input port index.

Returns

The value true if the port is a control port, false otherwise.

public boolean isEndOfConsistentRegion()

Check if the operator is an end operator of a consistent region.


Returns: The value true if the operator is an end operator in a consistent region, false otherwise.

public boolean isInConsistentRegion()

Check if the operator is in a consistent region.


Returns: The value true if the operator is in a consistent region, false otherwise.

public boolean isLoggable(enum {error, warn, info} logLevel)

Determine whether a message at the given level would be logged.

Parameters

logLevel: Classification of the log level (as error, warn, or info). Use the Level enumeration in the spl::Log to specify the log level.

Returns

The value true if a message at the given logLevel would be logged.

public stateful boolean isShutdown()

Check if shutdown is requested.


Returns: The value true if the system is shutting down.

public boolean isStartOfConsistentRegion()

Check if the operator is a start operator of a consistent region.


Returns: The value true if the operator is a start operator of a consistent region, false otherwise.

public boolean isTraceable(enum {error, warn, info, debug, trace} traceLevel)

Determine whether a message at the given level would be traced.

Parameters

traceLevel: Classification of the trace level (as error, warn, info, debug or trace). Use the Level enumeration in the spl::Trace to specify the trace level.

Returns

The value true if a message at the given traceLevel would be traced.

public boolean isTriggerOfConsistentRegion()

Check if the operator is the trigger operator of an operator-driven consistent region.


Returns: The value true if the operator is the trigger operator of a consistent region, false otherwise.

public uint64 jobID()

Return the Job ID for the current job that this operator is executing in.


Returns: The job ID for the current job.

public rstring loadAndFormatResource(rstring toolkitName, rstring bundleName, rstring resourceID)

Loads a string from a toolkit resource using the execution locale.

Parameters

toolkitName: The name of the toolkit that owns the resource.
bundleName: The name of the resource bundle within the toolkit.
resourceID: The ID of the resource to load.

Returns

The requested string.

<tuple T> public rstring loadAndFormatResource(rstring toolkitName, rstring bundleName, rstring resourceID, T substitutionValues)

Loads and formats a string from a toolkit resource using the execution locale.

Parameters

toolkitName: The name of the toolkit that owns the resource.
bundleName: The name of the resource bundle within the toolkit.
resourceID: The ID of the resource to load.
substitutionValues: A tuple containing substitution values. Note that the types and values of the attributes in the tuple are important. The attribute names are used only for error reporting.

Returns

The formatted string.

Throws

SPLRuntimeUnsupportedSubstitutionTypeException: If the type of a substitution variable is not supported.

<tuple T> public rstring loadAndFormatResource(rstring toolkitName, rstring bundleName, rstring resourceID, T substitutionValues, rstring locale)

Loads and formats a string from a toolkit resource using the specified locale.

Parameters

toolkitName: The name of the toolkit that owns the resource.
bundleName: The name of the resource bundle within the toolkit.
resourceID: The ID of the resource to load.
substitutionValues: A tuple containing substitution values. Note that the types and values of the attributes in the tuple are important. The attribute names are used only for error reporting.
locale: The locale the message should be formatted in. For example, "en_US.UTF-8".

Returns

The formatted string.

Throws

SPLRuntimeUnsupportedSubstitutionTypeException: If the type of a substitution variable is not supported.

public rstring loadAndFormatResource(rstring toolkitName, rstring bundleName, rstring resourceID, rstring locale)

Loads a string from a toolkit resource using the specified locale.

Parameters

toolkitName: The name of the toolkit that owns the resource.
bundleName: The name of the resource bundle within the toolkit.
resourceID: The ID of the resource to load.
locale: The locale the message should be formatted in. For example, "en_US.UTF-8".

Returns

The requested string.

<string T> public void log(enum {error, info, debug, trace} logLevel, T message)

Log a message in the tracing system.

Note: Deprecated - use appTrc instead.

Parameters

logLevel: Classification of the log level (as error, info, debug, or trace).
message: Message to be logged.

<string T> public void log(enum {error, info, debug, trace} logLevel, T message, T aspect)

Log a message in the tracing system.

Note: Deprecated - use appTrc instead.

Parameters

logLevel: Classification of the log level (as error, info, debug, or trace).
message: Message to be logged.
aspect: Message category (can be used for filtering when inspecting messages).

public stateful rstring mktemp(rstring templat)

Return the name of a temporary file created using a template. The POSIX mkstemp function is used to create the file, and the file is closed.

Parameters

templat: A pathname for the temporary file. The last six characters of templat must be "XXXXXX", and those characters will be replaced by a string to make the name unique.

Returns

The generated temporary file name, or the empty string if there were errors. Note that since the file is closed before returning, there is a brief window that another process might use to create the same file.

<tuple T> public int32 outputPort(T outputStream)

Return the index corresponding to an output port.

Parameters

outputStream: Stream name or alias.

Returns

Index of the output port.

public int32 parseNumber(mutable float64 number, rstring text)

Parse a string that represents a number, using the current locale.

Note: This function is implemented using ICU and does not accept 'e' as the exponent character. Use 'E' instead (e.g. 1.05E+3).

Parameters

number: Variable to store the result.
text: String to parse.

Returns

The number of bytes read on success, -1 otherwise.

public int32 parseNumber(mutable float64 number, ustring text)

Parse a string that represents a number, using the current locale.

Note: This function is implemented using ICU and does not accept 'e' as the exponent character. Use 'E' instead (e.g. 1.05E+3).

Parameters

number: Variable to store the result.
text: String to parse.

Returns

The number of bytes read on success, -1 otherwise.

public int32 parseNumber(mutable int64 number, rstring text)

Parse a string that represents a base 10 number, using the current locale.

Parameters

number: Variable to store the result.
text: String to parse.

Returns

The number of bytes read on success, -1 otherwise.

public int32 parseNumber(mutable int64 number, rstring text, int32 base)

Parse a string that represents a number of the specified base, using the current locale.

Parameters

number: Variable to store the result.
text: String to parse.
base: Base to use for conversion. Set to 0, or a number between 2 and 36 inclusive. If set to 0, the leading characters will determine the base. See the POSIX strtoll routine for more details.

Returns

The number of bytes read on success, -1 otherwise.

public int32 parseNumber(mutable int64 number, ustring text)

Parse a string that represents a number, using the current locale.

Parameters

number: Variable to store the result.
text: String to parse.

Returns

The number of bytes read on success, -1 otherwise.

<any T> public void print (T t)

Write any SPL type to the standard output stdout as an SPL literal. For example, strings are quoted, and special characters are escaped. If you want to print strings without using the string literal format, use the printString function instead. The output is not flushed.

Parameters

t: Value to print.

<string T> public void printString (T s)

Write a string to the standard output, stdout. The output is not flushed.

Parameters

s: String to print.

<string T> public void printStringLn (T s)

Write a string to the standard output, stdout, followed by a newline, then flush the output.

Parameters

s: String to print.

<any T> public void println (T t)

Write any SPL type to the standard output, stdout, in serialized form, followed by a newline. For example, strings are quoted, and special characters are escaped. The output is then flushed.

Parameters

t: Value to print.

public void resetConsistentRegion()

This function requests the ConsistentRegionControllerMXBean to restore the consistent region to the last established consistent state. This function can be used by operators when detecting an operator-specific transient failure. If the region is already being reset, a new reset attempt is triggered. If the operator is not in a consistent region, this function has no effect.

public stateful void setCustomMetricValue(rstring name, int64 value)

Set the specified custom metric value for the current operator.

Parameters

name: The name of the metric.
value: Value to use.

Throws

SPLRuntimeInvalidMetricException: If the metric does not exist.

public stateful void setCustomMetricValue(ustring name, int64 value)

Set the specified custom metric value for the current operator.

Parameters

name: The name of the metric.
value: Value to use.

Throws

SPLRuntimeInvalidMetricException: If the metric does not exist.

<tuple T> public stateful int32 setExceptionPortExportProperties(T properties, uint32 port)

Set the export properties for an output port that produces a stream that is exported with properties. See the Export operator for details of valid export properties.

For example, in SPL: setExceptionPortExportProperties({a = "hi", b = [ 4l, -8l]}, 0u);

Parameters

properties: A tuple representing the new export properties for the stream output by this port.
port: Exception port index.

Returns

Error return code: 0 for success, 1 for an invalid port or a port that does not produce a stream that is exported with properties, 2 for an invalid type used in the properties tuple, or 3 for a failure to set the properties.

public stateful int32 setExceptionPortExportProperties(list<tuple<rstring name, rstring value, rstring typ>> properties, uint32 port)

Set the export properties for an output port that produces a stream that is exported with properties. See the Export operator for details of valid export properties.

For example, in SPL: setExceptionPortExportProperties([{name = "a", value = ""string value"", typ = "rstring"}], 0u);

Parameters

properties: A list of tuples of type tuple<rstring name, rstring value, rstring typ> representing the new export properties for the stream output by this port, where name is the name of the property. value is the value of the property as a literal value of the type for the property, and typ is the type of the property (one of: int64, float64, rstring, list<int64>, list<float64>, list<rstring>. For string literals, use double quotes to specify the value.
port: Exception port index.

Returns

Error return code: 0 for success, 1 for an invalid port or a port that does not produce a stream that is exported with properties, 2 for invalid properties, or 3 for a failure to set the properties.

public stateful int32 setInputPortImportFilterExpression(rstring filter, uint32 port)

Set the filter expression for an input port that receives a stream that is imported. See the Import operator for details of valid filter expressions. Note: Setting a import subscription removes any existing filter expression in the same input port.

Parameters

filter: A string representing the filter expression for this port. An empty string removes the filter.
port: Input port index.

Returns

Error return code: 0 for success, 1 for an invalid port or a port that does not receive a stream that is imported, 2 for an invalid filter expression, or 3 for a failure to set the filter.

public stateful int32 setInputPortImportSubscription(rstring subscription, uint32 port)

Set the import subscription for an input port that receives a stream that is imported by subscription. See the Import operator for details of valid subscription expressions. Note: Setting a import subscription removes any existing filter expression in the same input port.

Parameters

subscription: A string representing the import subscription expression for this port.
port: Input port index.

Returns

Error return code: 0 for success, 1 for an invalid port or a port that does not receive a stream that is imported by subscription, 2 for an invalid subscription expression, or 3 for a failure to set the subscription.

<tuple T> public stateful int32 setOutputPortExportProperties(T properties, uint32 port)

Set the export properties for an output port that produces a stream that is exported with properties. See the Export operator for details of valid export properties.

For example, in SPL: setOutputPortExportProperties({a = "hi", b = [ 4l, -8l]}, 0u);

Parameters

properties: A tuple representing the new export properties for the stream output by this port.
port: Output port index.

Returns

public stateful int32 setOutputPortExportProperties(list<tuple<rstring name, rstring value, rstring typ>> properties, uint32 port)

Set the export properties for an output port that produces a stream that is exported with properties. See the Export operator for details of valid export properties.

For example, in SPL: setOutputPortExportProperties([{name = "a", value = ""string value"", typ = "rstring"}], 0u);

Parameters

properties: A list of tuples of type tuple<rstring name, rstring value, rstring typ> representing the new export properties for the stream output by this port, where name is the name of the property. value is the value of the property as a literal value of the type for the property, and typ is the type of the property (one of: int64, float64, rstring, list<int64>, list<float64>, list<rstring>. For string literals, use double quotes to specify the value.
port: Output port index.

Returns

Error return code: 0 for success, 1 for an invalid port or a port that does not produce a stream that is exported with properties, 2 for invalid properties, or 3 for a failure to set the properties.

public stateful void shutdownPE ()

Shutdown the current processing element (PE).

public rstring strerror(int32 errnum)

Convert an errno value to a string for intelligent printing.

Parameters

errnum: Error number to convert to a string description.

Returns

String description of errnum.

public float64 strtod (rstring value)

Convert a string to a floating point number. See the POSIX strtod routine for details.

Parameters

value: String to convert.

Returns

String converted to a float64.

public float64 strtod (rstring value, mutable int32 numCharsProcessed)

Convert a string to a floating point number. See the POSIX strtod routine for details.

Parameters

value: String to convert.
numCharsProcessed: Number of characters consumed from value during the conversion, or -1 if the conversion failed (result out of range).

Returns

String converted to a float64.

public int64 strtoll (rstring value, int32 base)

Convert a string in base 2 to 36 to an signed number.

Parameters

value: String to convert.
base: Base to use for conversion. Set to 0, or a number between 2 and 36 inclusive. If set to 0, the leading characters will determine the base. See the POSIX strtoll routine for more details.

Returns

String converted to an int64.

public int64 strtoll (rstring value, int32 base, mutable int32 numCharsProcessed)

Convert a string in base 2 to 36 to an signed number.

Parameters

value: String to convert.
base: Base to use for conversion. Set to 0, or a number between 2 and 36 inclusive. If set to 0, the leading characters will determine the base. See the POSIX strtoll routine for more details.
numCharsProcessed: Number of characters consumed from value during the conversion, or -1 if the conversion failed (invalid base or result out of range).

Returns

String converted to a int64.

public uint64 strtoull (rstring value, int32 base)

Convert a string in base 2 to 36 to an unsigned number.

Parameters

value: String to convert.
base: Base to use for conversion. Set to 0, or a number between 2 and 36 inclusive. If set to 0, the leading characters will determine the base. See the POSIX strtoll routine for more details.

Returns

String converted to a uint64.

public uint64 strtoull (rstring value, int32 base, mutable int32 numCharsProcessed)

Convert a string in base 2 to 36 to an unsigned number.

Parameters

value: String to convert.
base: Base to use for conversion. Set to 0, or a number between 2 and 36 inclusive. If set to 0, the leading characters will determine the base. See the POSIX strtoll routine for more details.
numCharsProcessed: Number of characters consumed from value during the conversion, or -1 if the conversion failed (invalid base or result out of range).

Returns

String converted to a uint64.

<any T> public void swap (mutable T s1, mutable T s2)

Swap any two SPL values

Parameters

s1: Value to swap.
s2: Value to swap.