Exegy Input Adapter

Contents

Introduction
Exegy Input Adapter Properties
Adapter Ports
Using the Adapter in a StreamBase Application
Typechecking and Error Handling
Suspend and Resume Behavior
Related Topics

Introduction

The TIBCO StreamBase® Adapter for Exegy allows a StreamBase application to receive and process real-time market data from the Exegy Ticker Plant.

The adapter supports Level 1 and 2 market data for equities and commodities. It supports key lists, allowing the StreamBase application to define and store customized instrument lists (keylists) on the Exegy Ticker Plant, and to modify existing keylists. It also supports baskets, which allows a StreamBase application to define customized groupings of financial instruments called baskets, load them onto the Exegy Ticker Plant, then subscribe to the real-time flow of Net Asset Value (NAV) updates for each active basket.

The adapter is embedded in the StreamBase application and has several input and output ports, some of which are always present, and others whose presence is configurable.

The adapter can be configured to connect to the Exegy Ticker Plant when it starts or later, in response to a connect tuple on its Admin input port. The Subscribe, KeyList, Basket, and HalterdPrice input ports expose the adapter's core functions. Section Input Ports describes the adapter's input ports in more detail.

Some of the adapter's output ports, such as Status, Dictionary, and KeyListDef, have fixed schemas defined by the adapter, while others, such as Equities, Commodities, and PriceBook, have schemas defined by the user via the adapter's Edit Schema tab. Section Output Ports describes the adapter's output ports in more detail.

The set of StreamBase data types supported by the adapter is dictated by the Exegy dictionary, which can be retrieved by enqueuing a dumpDict tuple to the adapter's Admin input port or by enabling the adapter's Dump Dictionary on Startup property.

The adapter is configured through properties set in the adapter's Properties view in StreamBase Studio. The properties are organized across several tabs and include check boxes that determine the set of optional input and output ports present, connection parameters for the Exegy Ticker Plant, subscription properties for controlling the subscription rate and maximum available subscriptions, and properties for setting the schemas of various adapter output ports.

Exegy Middleware Dependencies

The StreamBase Exegy adapter relies on version 3.5.0 or later of the JAR file that implements the Exegy Client API, XCAPI.jar. This file is supplied as part of your Exegy installation and is not shipped with StreamBase. If you get an error message whose text refers to NoClassDefFoundError: com/exegy/xcapi/XCException, make sure this JAR file is locatable by the adapter on the path specified in the CLASSPATH environment variable.

The StreamBase Exegy adapter also relies on version 3.5.0 or later of the native library that implements the Exegy Client API, libjnixcapi64.so on Linux and jnixcapi64.DLL on Windows. This file is supplied as part of your Exegy installation and is not shipped with StreamBase. If you get an error message whose text refers to Failed to load Java XCAPI library (jnixcapi64), make sure this file is locatable by the adapter on the path specified in the LD_LIBRARY_PATH environment variable on Linux or in the PATH environment variable on Windows.

The Exegy API implementation described in this section is a product of a third party, and its specifications and file names are subject to change by Exegy. See your Exegy documentation for the latest information.

Exegy Input Adapter Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.

General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Adapter: A read-only field that shows the formal name of the adapter.

Class: A field that shows the fully qualified class name that implements the functionality of this adapter. Use this class name when loading the adapter in StreamSQL programs with the APPLY JAVA statement. You can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start with application: If this field is set to Yes or to a module parameter that evaluates to true, an instance of this adapter starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the adapter does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Adapter Properties Tab

Property Description
Price Book Depth

The maximum number of bids and asks present in each tuple emitted on the PriceBook output port. The default value is 5.

Enable Dynamic Key List Definition If enabled (not the default), the adapter includes an input port for configuring and querying key list definitions and an output port for receiving key list definition changes.
Enable Baskets If enabled (not the default), the adapter includes an input port for configuring, subscribing to, and querying baskets and a second input port for setting custom halted prices, and output ports for receiving basket activity and the real-time flow of Net Asset Value (NAV) updates for each active basket.
Include Basket Pass-Thru Field When set, a field named PassThru is expected in the schema of the Basket input port, and a field of the same type is added to the BasketUpdates and BasketNav output ports. There are no constraints on the PassThru field's type. The value received in this field from the subscription tuple is placed in each output tuple emitted as a result of that subscription.
Dump Dictionary on Startup If enabled (the default), the adapter emits a tuple on its Dictionary output port when it starts.
Include Callback Nanotime If enabled (not the default), the adapter includes an XC_ADAPTER_CALLBACK_NANOTIME field of type long in its Equities, Commodities, and PriceBook output ports that indicates the nanotime at which a message was received from the XCAPI library.
Include Adapter Latency If enabled (not the default), the adapter includes an XC_ADAPTER_LATENCY_NANOS field of type long in its Equities, Commodities, and PriceBook output ports that tracks the number of nanoseconds spent within the adapter processing each incoming message.
Include Ticker Plant Latency If enabled (not the default), the adapter includes an XC_TICKER_PLANT_LATENCY_NANOS field of type long in its Equities, Commodities, and PriceBook output ports that tracks the latency in nanoseconds between the receipt of a message by the ticker plant from the exchange and the receipt of the message by the adapter from the ticker plant.
Include Subscribe Pass-Thru Field When set, a field named PassThru is expected in the schema of the Subscribe input port, and a field of the same type is added to the Equity, PriceBook, and Commodities output ports. There are no constraints on the PassThru field's type. The value received in this field from the subscription tuple is placed in each output tuple emitted as a result of that subscription.
Maximum quote rate The maximum rate, in quotes per second, for 'metered quote delivery' for subscribed equity and commodity symbols if no maximum quote rate is defined in the subscription stream. Valid for Edge-Cache connected applications only. 0 means default (unlimited) Note that setting the field does not change the quote delivery rate in effect for previously existing subscriptions.
Log Level Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.

Connection Properties Tab

Property Description
Exegy Server Host The host name or IP address of the Exegy Ticker Plant.
Login Username The username used in connecting to the Exegy Ticker Plant.
Login Password The password used in connecting to the Exegy Ticker Plant.
Connect on Startup If enabled (the default), the adapter connects to the Exegy Ticker Plant when it starts. If the adapter is configured to not connect on startup, a connect tuple can be enqueued to the adapter's Admin port to connect to the Exegy Ticker Plant.

Subscription Properties Tab

Property Description
Maximum Subscription Symbols The maximum allowable subscription requests that can be passed to the adapter.
Throttle Subscriptions If enabled (the default), the adapter limits the rate at which subscription requests are passed to the Exegy Ticker Plant based to the value of the Symbols Per Second property.
Symbols Per Second The maximum rate at which subscription requests are passed to the Exegy Ticker Plant. If the rate of incoming subscription tuples exceeds this rate, the adapter throttles the requests by enqueuing them internally and passing them to the Ticker Plant at the specified rate.
Refresh/Snapshot Only - No Updates If enabled (not the default), the adapter does not emit tuples for update events.

Edit Schemas Tab

Use the Edit Schemas tab to specify the schemas for three of this adapter's output ports:

Level 1 Equity Schema

Specifies the schema to appear on the Equities output port.

Level 1 Commodity Schema

Specifies the schema to appear on the Commodities output port.

Price Level Schema

Specifies the schema of the bids and asks fields of the PriceBook output port. The schema of the PriceBook output port is set by the adapter.

For general instructions on using the Edit Schema tab, see the Properties: Edit Schema Tab section of the Defining Input Streams page.

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Adapter Ports

As shown in the diagram below (depicting the adapter's sample application), the Exegy adapter, when configured with all ports enabled, has five input ports and eight output ports to communicate with the surrounding application.

Note

In this adapter's sample application, the adapter's input and output ports are connected directly to externally-visible input and output streams. However, in more complex applications these ports will typically be connected to internal StreamBase operators.

The Exegy Input Adapter's ports are used as follows:

Input Ports

  • Admin: This input port receives tuples used to connect to, and disconnect from, the Exegy Ticker Plant and to retrieve the Exegy data dictionary. The Admin port has the following schema:

    • command, string: Contains the administrative command to execute:

      • connect — connect to the Exegy Ticker Plant.

      • disconnect — disconnect from the Exegy Ticker Plant.

      • dumpDict — emit a tuple on the Dictionary output port containing a list of tuples, one per Exegy field.

  • Subscribe: This input port receives tuples used to subscribe to, and unsubscribe from, Level 1 and 2 market data. The Subscribe port has the following schema:

    • command, string: Contains the subscription command to execute:

      • subscribe — subscribe to market data.

      • unsubscribe — unsubscribe from market data.

    • symbol, string: The Exegy symbol to subscribe to, such as US:N:IBM.

    • subscriptionType, string: The type of subscription:

      • level_one — Level 1 market data.

      • price_book — Level 2 market data.

    • containerType, string: The Exegy container type:

      • equity

      • commodity

    • isAggregated, boolean: True to subscribe to aggregated Level 2 data and false otherwise. Ignored for Level 1 subscriptions.

    • includeImplied, boolean: True to include Level 2 commodity quotes and false otherwise. Ignored for all Level 1 subscriptions and Level 2 equity subscriptions.

    • PassThru, any type: must be present when the Include Subscribe Pass-Thru Field property is enabled. A corresponding field is added to the schema of the Equities, PriceBook, and Commodities output ports. The value received in this field is placed in each tuple emitted as a result of that subscription.

    • maxQuoteRate, int: The maximum rate, in quotes per second, for 'metered quote delivery' for this subscription. 0 or null means use the global Maximum quote rate from the adapters properties.

  • KeyList: This optional input port receives tuples used to create, modify, or retrieve keylists. The KeyList port has the following schema:

    • command, string: Contains the keylist command to execute:

      • refresh — request a tuple containing the contents of the specified keylist be emitted on the KeyListUpdates port.

      • save — create a new keylist or update an existing keylist.

    • key, string: The name of the keylist to retrieve, create, or update.

    • values, list<string>: When creating or updating keylists, the new values associated with the keylist.

  • Basket: This optional input port receives tuples used to create, modify, delete, or retrieve baskets, and to subscribe to or unsubscribe from defined baskets. The Basket port has the following schema:

    • command, string: Contains the basket command to execute:

      • refresh — request a tuple containing the contents of the specified subscribed basket be emitted on the BasketUpdates port.

      • save — create a new basket or update an existing basket.

      • delete — delete an existing basket.

      • subscribe — subscribe to an existing basket (one created with a previous save command).

      • subscribeAll — subscribe to all baskets.

      • unsubscribe — unsubscribe from a basket.

      • subscribeNav — subscribe to the real-time flow of Net Asset Value (NAV) updates for an existing basket (one created with a previous save command).

      • unsubscribeNav — unsubscribe from the real-time flow of Net Asset Value (NAV) updates for a basket.

    • basketName, string: The name of the basket to retrieve, create, update, subscribe to, or unsubscribe from.

    • divisor, double: The divisor to use for NAV calculations.

    • cashPosition, double: Cash position of the basket.

    • constituents, list<tuple>: The constituents instrument in the basket. The constituent tuple field has two sub-fields:

      • symbol, string: The symbol of the instrument.

      • weight, int: The weight of that instrument within the basket.

    • PassThru, any type: must be present when the Include Basket Pass-Thru Field property is enabled. A corresponding field is added to the schema of the BasketUpdates and NavUpdate output ports. The value received in this field is placed in each tuple emitted as a result of that subscription.

  • HaltedPrice: This optional input port receives tuples used to override the halted price of a constituent instrument for which trading is halted in calculating last-NAV values for the basket. The HaltedPrice port has the following schema:

    • symbol, string: The symbol of the constituent instrument.

    • haltedPrice, double: The price to use for the instrument in calculating last-NAV values for the instrument's basket.

Output Ports

  • Status: The adapter emits tuples on this port when significant events occur, such as when the state of the connection to the Exegy Ticket Plant changes, a subscription is processed, or a basket event occurs. The Status port has the following schema:

    • Type, string: The type of event:

      • Connection — the state of the connection to the Exegy Ticket Plant changes.

      • Subscription — a subscription request was processed.

      • Basket — a basket event was received from the Exegy Ticker Plant.

    • Object, string: a string representation of the subscription for Subscription events or the basket name for Basket events.

    • Action, string: Connected or Disconnected for Connection events, Subscribed or SubscribeFailed for Subscription events, and Saved, SaveFailed, Deleted, DeleteFailed, Subscribed, SubscribeFailed, NavSubscribed, or NavSubscribeFailed for Basket events.

    • Message, string: A human-readable description of the event, if applicable.

    • Time, timestamp: The time of the event.

  • Dictionary: The adapter emits a tuple on this port when starting up if its Dump Dictionary on Startup property is enabled and in response to dumpDict tuples received on its Admin port. The Dictionary port has the following schema:

    • dataType, string: The name of the StreamBase data type to use for the field.

    • inLevelOneEquity: True if the field is available for use in Level 1 equity tuples and false otherwise.

    • inLevelOneCommodity: True if the field is available for use in Level 1 commodity tuples and false otherwise.

    • inPriceBookTop: True if the field is available for use in Level 2 tuples and false otherwise.

    • inPriceBookSubLevel: True if the field is available for use in bid and ask subtuples of Level 2 tuples and false otherwise.

  • Equities: The adapter emits a tuple on this optional port when a Level 1 equity event is received. The Equities port schema is derived from the adapter's Level 1 Equity Schema property on the Edit Schema tab. Use the tuple emitted on the Dictionary output port to determine the fields available for the Equities port and their types. If the Add Performance Trace property is set, the adapter adds a XC_ADAPTER_LATENCY_MICROS field to the Equities port that contains the time, in microseconds, to process the Level 1 equity event.

    The XC_MESSAGE_TYPE field, if present, contains one of the following values:

    • 0: Refresh

    • 1: Snapshot

    • 2: Quote

    • 3: Trade

    • 5: Trading action

  • Commodities: The adapter emits a tuple on this optional port when a Level 1 commodity event is received. The Commodities port schema is derived from the adapter's Level 1 Commodity Schema property on the Edit Schema tab. Use the tuple emitted on the Dictionary output port to determine the fields available for the Commodities port and their types. If the Add Performance Trace property is set, the adapter adds a XC_ADAPTER_LATENCY_MICROS field to the Commodities port that contains the time, in microseconds, to process the Level 1 commodity event.

    The XC_MESSAGE_TYPE field, if present, contains one of the following values:

    • 0: Refresh

    • 1: Snapshot

    • 2: Quote

    • 3: Trade

    • 5: Trading action

  • PriceBook: The adapter emits a tuple on this optional port when a Level 2 (price book) event is received. The PriceBook port has the following schema:

    • Symbol, string: the symbol associated with the Level 2 event.

    • XC_MESSAGE_TYPE, int: The type of event:

      • 0: Refresh

      • 1: Snapshot

      • 4: Book update

    • bids, list<tuple>: The list of bids associated with the Level 2 event. Each bid tuple has the schema specified in the Price Level Schema property.

    • asks, list<tuple>: The list of asks associated with the Level 2 event. Each ask tuple has the schema specified in the Price Level Schema property.

    • isAggregated, boolean: True if the price book is aggregated and false otherwise.

    • includeImplied, boolean: True if the price book includes implied quotes and false otherwise.

    • containerType, string: equity or commodity.

    • XC_ADAPTER_LATENCY_MICROS, long: Present in the schema if the Add Performance Trace property is enabled. Contains the time, in microseconds, spent in the adapter processing the Level 2 event.

  • KeyListUpdates: The adapter emits a tuple on this optional port when a keylist is updated or a refresh tuple is enqueued to the KeyList port. The KeyListUpdates port has the following schema:

    • key, string: The keylist name.

    • values, list<string>: The new values associated with the keylist.

  • BasketUpdates: The adapter emits a tuple on this optional port when basket events occur. The BasketUpdates port has the following schema:

    • updateType, int: The type of basket event:

      • 0 — refresh

      • 6 — delete

    • basketName, string: The basket name.

    • divisor, double: The basket divisor.

    • cashPosition, double: The basket cash position.

    • constituents, list<tuple>: The constituents instrument in the basket. The constituent tuple field has two sub-fields:

      • symbol, string: The symbol of the instrument.

      • weight, int: The weight of that instrument within the basket.

  • NavUpdate: The adapter emits tuples on this optional port to provide real-time flow of Net Asset Value (NAV) updates. The NavUpdate port has the following schema:

    • basketName, string: The basket name.

    • momentum, int: The basket momentum value.

    • last, double: The NAV calculated using the last price (that is, the most recent price at which the instrument was traded).

    • bid, double: The NAV calculated using the bid price.

    • bidAway, double: The NAV calculated using the one-tick-away-from-bid price.

    • ask, double: NAV calculated using the ask price.

    • askAway, double: The NAV calculated using the one-tick-away-from-ask price.

Using the Adapter in a StreamBase Application

Add an instance of the adapter to a new StreamBase application as follows:

  1. In StreamBase Studio, create a project, and create an EventFlow application file to host the adapter.

  2. Drag the Input Adapter icon from the Operators & Adapters drawer in the Palette view to the canvas. Select the Exegy Input Adapter from the list and click OK.

  3. Select the adapter icon, and in the Properties view, select Adapter Properties, and enable one or more optional ports, if desired.

  4. Select Connection Properties, and enter site-specific values for the Exegy server, login username, and password.

  5. Connect input streams to each adapter input port, and configure the schema of each with the fields described above. The adapter generates a typecheck error if a required field is missing or of the wrong type, or if an unexpected field is present.

  6. Connect output streams to each adapter output port.

  7. Run the application and enqueue a dumpDict command to the Admin port.

  8. Use the resulting tuple emitted by the adapter on the Dictionary port to determine the fields available for the Equities, Commodities, and PriceBook ports.

  9. Stop the application, select the adapter icon, and in the Properties view, select Edit Schemas. Add fields to the Level 1 Equity, Level 1 Commodity, and Price Level Schema properties.

Typechecking and Error Handling

The Exegy Input adapter uses typecheck messages to help you configure the adapter in your StreamBase application. In particular, the adapter generates typecheck messages when:

  • A required field is missing or of the wrong type, or if an unexpected field is present, in an input port schema.

  • Values for the Exegy Server Host, Login Username, or Login Password properties have not been entered.

  • The Maximum Subscription Symbols or Symbols Per Second properties are not within their required ranges.

The adapter emits warnings and errors messages on the status port and/or stderr during runtime under various conditions, including:

  • The Level 1 Equity, Level 1 Equity Commodity, and/or Price Level Schema properties are configured with an invalid Exegy field name.

  • A missing or invalid value is detected in an input tuple, such as an invalid Admin, Subscribe, or Basket command.

  • A Subscribe, Keylist, or Basket command is requested when disconnected from the Exegy Ticker Plant.

  • The Exegy Ticker Plant session disconnects.

  • An error is returned from the Exegy Client API.

  • A Level 1 or 2 event field cannot be processed due to a data type mismatch.

Suspend and Resume Behavior

When suspended, the Exegy Input Adapter stops emitting tuples on its output ports.

When resumed, the adapter begins emitting tuples on its output ports once again.

Related Topics