Error Streams Sample

The dividemodule application uses both error ports and error streams features.

DoDivision: Notice that the bottom output port of this Map operator is red. This indicates that this operator has its error output port enabled. This port outputs a tuple for every error that occurs during processing inside this operator.

UnhandledErrors: This component is this application's error input stream, and is used to catch unexpected errors that occur anywhere in this module.

ErrorOutputStream: This component is a special output stream that works much like a throw mechanism for this application. It allows the application to pass errors up the chain to be handled elsewhere. Errors are passed to a parent module or to StreamBase Server for handling.

This sample walks you through an interactive session demonstrating:

During processing of tuple data, operators may occasionally trigger an error. Errors occurring in an operator might be due to data (such as a division by zero), or due to external resources (such as attempting to open an unavailable file).

To provide custom handling for errors that occur within an operator, enable that operator's error output port. Studio draws a red output port, always in the last port position, that allows you to connect other components to that output stream, just as you already connect data streams together.

In StreamSQL, use the ERROR INTO clause of a statement to enable the error port.

DoDivision is an operator in the dividemodule application that has its error output port enabled.

Select this operator and observe the General tab in the Properties view. Notice that the Enable Error Output Port option is selected.

Notice in the Output Settings tab that this Map operator divides two incoming data. This expression has a potential for generating an error if the divisor field is ever zero.

Error Input Streams handle any otherwise unhandled error in the current module. Handled errors are those caught at the operator level and sent out that operator's error output port. All other errors in the module are unhandled and are caught by the Error Input Stream.

For each unhandled error, a tuple appears on the Error Input Stream, and flows through the application as data that you can manipulate. The schema for error tuples is standardized.

There can be only one Error Input Stream per module. Renaming the Error Input Stream is allowed.

If you do not place an Error Input Stream in a module, then any errors in that module are automatically passed up to the parent module's Error Input Stream (if any). This process repeats until reaching StreamBase Server's error handler.

UncheckedDivision is a Map operator that has the same expression settings as DoDivision, but it does not have its error output port enabled. This means a divide-by-zero error in UncheckedDivision will stop processing of the tuple that triggers the error.

UnhandledErrors is this module's Error Input Stream. Errors from UncheckedDivision cause a tuple to appear here.

Error Output Streams provide a throw mechanism for the application or module. You can use them to ensure that errors you handle locally continue up to the next level of error handling.

There can be many Error Output Streams in a module, but the schema is fixed for each Error Output Stream. This schema is the same as that of an Error Input Stream and also that of any error output port, as these are typically on the same path.

In StreamSQL, define an Error Output Stream for a module using CREATE ERROR OUTPUT STREAM (stream-name).

ErrorOutputStream is the name of the only Error Output Stream in the dividemodule application. It is there to ensure that all the paths that provide error handling are propagated for handling to a parent module or to StreamBase Server. (Paths that handle errors are the one that begins with UnhandledErrors, and the one that begins with DoDivision's error output port.)

What each error processing path does to error tuples can dramatically change the behavior of the application. We will learn more about this in the next steps.

Run the dividemodule.sbapp application again. This time, we will cause the division-by-zero error to occur in the DoDivision Map operator, which has an error output port.

Stop the application from the previous demonstration. Find and open the dividetoplevel.sbapp application file. This simple application contains a module reference to the first application, dividemodule.sbapp.

Notice that the module reference has a red port. This is its error output port for the inner module, enabled the same way for module references as for any operator. This error port emits tuples for any error that was generated inside the inner module during processing.

As an exercise for further learning, open the outoforder.sbapp module. Run the module and send data through it manually to learn about using an Error Output Port with Aggregates.

It may be instructive to run these samples with intermediate stream dequeuing enabled so that you can use the Application Output view to see the tuples that exit the error streams. See Intermediate Stream Dequeuing in the StreamBase Help system for instructions.

Error handling is a required portion of the development effort when developing mission critical, real-time production applications. Error ports and error streams provide a level of error-handling richness in StreamBase applications equivalent to that available in modern programming languages. These features are added without compromising the ease of use that Studio, EventFlow, and StreamSQL offer to StreamBase application authors.