- Index

< Previous |  | Next >

# Intermediate Stream Dequeuing

## Introduction

For debugging purposes only, you can dequeue data from intermediate streams in your application, not only from output streams. This debugging feature allows you to examine the value of a tuple at an intermediate point in the stream of tuples flowing left to right, before that tuple has been fully processed, and before it has arrived on an output stream. This feature is not to be used for inserting new data into the middle of an application.

### Caution

When intermediate stream dequeuing is enabled, the StreamBase Server instance hosting your application consumes considerably more memory, to the point that you might not be able to successfully launch large applications.

Intermediate stream dequeuing (ISD) is disabled by default. You can enable it for a particular run or debug session as described below in Enabling Full ISD.

## ISD Compared to Other Features

Do not confuse intermediate stream dequeuing with the always expose feature of input and output streams.

Always Expose Stream Feature

  The General tab of the Properties view for input and output streams has a check box labeled Always expose stream for enqueue or dequeue, respectively. This feature is an attribute of explicit input and output streams that allows you to designate a stream to be enqueueable or dequeuable no matter how deeply its containing module is nested. This feature only affects input and output streams.

Intermediate Stream Dequeue

  ISD is a property setting of the hosting server, and affects all modules in an application. This feature allows you to dequeue not only from output streams, but from the output ports of Map, Filter, Union, or other operators in any module. You can limit the number of operators exposed for dequeuing by specifying a regular expression to match against the names of intermediate streams.

For another debugging approach, consider using runtime tracing in place of, or in addition to, ISD. Runtime tracing is described in Interpreting Trace Files, and includes a comparison table in Tracing Versus Dequeuing.

## What Streams Are Exposed

The following table clarifies what streams are exposed for dequeuing for various settings of intermediate stream dequeuing.

ISD Setting | Regular Expression Setting | Dequeuable Streams
--- | --- | ---
ISD disabled (the default for run and debug modes) | N/A | For the top-level module only: All explicit output streams. Any sub-module output stream individually exposed for dequeuing in its Properties view.
ISD enabled | None specified. | For the top-level module and all sub-modules: All explicit input and output streams. All explicit error input and error output streams. All intermediate streams in all modules.
ISD enabled | Regular expression substring specified. | For the top-level module: All explicit input and output streams. All explicit error input and error output streams. For all sub-modules: Any input, output, error, or intermediate stream whose name matches the supplied regular expression substring. Any sub-module output stream individually exposed for dequeuing in its Properties view.

### Note

Error output streams are considered intermediate streams for purposes of dequeuing. To allow dequeuing directly from an error output stream, you must enable ISD. Note that this is useful only for debugging: in a well-designed application, your application does not need to read the tuples output on error streams, which are passed automatically to the next higher module, or to the hosting Server.

## Enabling Full ISD

Enable intermediate stream dequeuing by setting the `streambase.codegen.intermediate-stream-dequeue` property in a HOCON configuration file of type c.t.e.streambase.c.sbengine, in the StreamBaseEngine root object.

If you set that property `= "true"`, you enable full ISD, where all available intermediate streams are enabled for dequeuing. For example:

    name = "sbengine"
    version = "1.0.0"
    type = "com.tibco.ep.streambase.configuration.sbengine"
    configuration = {
      StreamBaseEngine = {
        systemProperties =
        {
         "streambase.codegen.intermediate-stream-dequeue" = "true"
        }
      }
    }

## Enabling Partial ISD

You can restrict ISD to the components that match a regular expression you specify with the `streambase.codegen.intermediate-stream-dequeue-regex` system property.

For example, the normal output of sbc list stream without ISD for the StreamBase Best Bids and Asks sample is as follows:

    stream  BestAsks
    stream  BestBids
    stream  NYSE_Feed

If you enable full ISD with the configuration file from the previous section, the same command emits the following:

    stream  BestAsks
    stream  BestBids
    stream  NYSE_Feed
    stream  out:IsNewBestAsk_1
    stream  out:IsNewBestBid_1
    stream  out:Update_Bids_and_Asks_1

Now use the following configuration file to restrict ISD to the streams that match the regular expression `.IsNew.:`

    name = "sbengine"
    version = "1.0.0"
    type = "com.tibco.ep.streambase.configuration.sbengine"
    configuration = {
      StreamBaseEngine = {
        systemProperties =
        {
         "streambase.codegen.intermediate-stream-dequeue" = "true"
         "streambase.codegen.intermediate-stream-dequeue-regex" = ".IsNew."
        }
      }
    }

The results from sbc list stream are now:

    stream  BestAsks
    stream  BestBids
    stream  NYSE_Feed
    stream  out:IsNewBestAsk_1
    stream  out:IsNewBestBid_1

## Intermediate Stream Naming Convention

With intermediate stream dequeuing enabled, you can dequeue data from any output port of any operator using a stream name of the form:

    out:operatorName_N

where `operatorName` is the name of the operator and `N` is the number of the output port for that operator.

Consider the `Split.sbapp` application, which is one of the `operator` samples installed with the StreamBase kit:

To verify the intermediate stream names, run sbc list when the application is running with ISD enabled. The following example shows the intermediate streams in boldface:

    container   default
    container   system
    stream      INTRUSION_TooManyIPsForUser
    stream      INTRUSION_TooManyUsersForIP
    stream      IPandUserLogin
    stream      out:CheckIPsForAUser_1
    stream      out:CheckUsersInAnIP_1
    stream      out:ProcessIPFirst_1
    stream      out:ProcessIPFirst_2
    schema      schema:IPandUserLogin
    operator    CheckIPsForAUser
    operator    CheckUsersInAnIP
    operator    IPCountExceeded
    operator    ProcessIPFirst
    operator    UserCountExceeded

You can also run epadmin display stream with a --servicename or --adminport global parameter to see the intermediate streams in a fragment running with ISD enabled. The output of this command is verbose, with several lines of information per stream. Intermediate streams are marked as such in the Type line. For example:

    [sample_operator_Split.sbuser] Engine = com_tibco_sb_sample_operator_Split2
    [sample_operator_Split.sbuser] Path = default.out:CheckIPsForAUser_1
    [sample_operator_Split.sbuser] Type = intermediate
    [sample_operator_Split.sbuser] Enqueue = true
    [sample_operator_Split.sbuser] Dequeue = true
    [sample_operator_Split.sbuser] Total Tuples = 0
    [sample_operator_Split.sbuser] Schema = (UserID int, CountOfIPs int)

## Unconventional Intermediate Stream Names

Intermediate stream names can be found that do not appear to follow the naming convention described in the previous section. When determining the name of intermediate streams from which to dequeue, you must confirm the names as actually used in your application. Confirm with an sbc list or epadmin display stream command.

In some cases, the name of an intermediate stream can vary from the default convention, depending on the history of edits to the application.

## Related Topics

For related information, see:

- Editing EventFlow Run Configurations

- Interpreting Trace Files

Back to top ^