Lime Citrius Quote Input Adapter

Contents

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

This adapter is part of the TIBCO StreamBase CEP Connectivity Package.

Introduction

The TIBCO StreamBase® Adapter for Lime Citrius Market Data allows a StreamBase application to subscribe to and receive market data from Lime Brokerage's Citrius Quote delivery system. The adapter is embedded within the StreamBase application, and provides access to equity, derivative, and index market data from any Lime Citrius-provided data source.

The adapter sends subscription requests received on its subscription input port to the Lime Citrius Quote server and asynchronously and continuously receives and converts the resulting response or market update messages into StreamBase tuples, which it sends downstream.

The adapter emits market data tuples on four separate output ports. The fields that appear in each output port's output schema are predetermined by the adapter and closely correspond to the parameters to the various onX callback functions of the Lime Citrius Quote API. See below for the description of each output port as well as the name, type, and description of each field emitted by each output port. Since the Citrius schemas are very small, the adapter always includes all possible values in the relevant tuple's schemas — unlike many other StreamBase market data adapters, the user does not get the opportunity to select which fields the adapter will output. The application is expected to ignore or remove any unwanted fields.

In general, the philosophy of this adapter is to perform minimal event processing beyond handling Quote API callbacks and translating each callback occurrence into an output tuple. The semantics of the output tuple fields are for the most part direct mappings into tuple fields — the adapter user should be familiar with the Lime Citrius Quote API documentation in order to make the best semantic use of the output.

The adapter provides a status event output port to convey status and error information to the StreamBase application. For example, when the state of a connection to the Lime Citrius Quote server changes, a connection event tuple is emitted from the status event output port.

Subscriptions are submitted for a specific symbol on a specific data source. It is possible to subscribe to all symbols available from a data source by specifying the special symbol ___ALL___ (three underscore characters before and after ALL).

The adapter is configured through several properties set in the adapter's Properties view within StreamBase Studio. Login- and subscription-related properties contain default values that can be overridden through corresponding fields of login and subscribe tuples.

Adapter Properties

The tables in this section describe the properties of the Lime Citrius Quote adapter in the various views of the adapter's Properties view.

Login Properties Tab

Property Description
Host Name The hostname or IP address of the quote server. This field normally specifies a port number as well. For example, x.y.z.a:12345. The value of this property is used if a login tuple's hostName has a null value or if the Login at Startup property is enabled.
User Name The user name used to log in to the quote server. The value of this property is only used if a login tuple's username field has a null value or if the Login at Startup property is enabled.
Password The password used to login to the quote server. The value of this property is only used if a login tuple's password field has a null value or if the Login at Startup property is enabled.
Login at Startup When enabled, the adapter attempts to log in to the Citrius Quote server when it starts using the values from the Host Name, User Name, and Password properties, rather than waiting for a login tuple.
Reconnect Interval The time, in seconds, to wait between attempts to reconnect to the Citrius Quote server after a failed connection attempt or after the connection is lost (a disconnect).
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.

Subscription Properties Tab

Property Description
Quote Source The quote source used to subscribe or unsubscribe if a subscribe tuple's quoteSource field has a null value or if the Subscribe at Startup property is enabled.
Symbols A comma-separated list of symbols used if a subscribe tuple's symbol field has a null value or if the Subscribe at Startup property is enabled.
Subscribe at Startup When enabled, the adapter attempts to subscribe when it starts using the values from the Quote Source and Symbols properties, rather than waiting for a subscribe tuple. Additional subscriptions can be made after startup by enqueuing subscribe tuples to the adapter.
Enable Aggregate by Price Combine all quotes at a given price into a single quote with an aggregated quantity.
Enable Snapshot Book Request books but no streaming quotes or trades.
Enable Top of Book Enables the top-of-book view for all subscriptions. Note that in "Top of Book" mode, no book is maintained. Instead, the most recent bid or ask for any symbol replaces all previous bids or asks.
Enable Trade Replay For each symbol, emit all trade data since market open prior to emitting the rebuild complete tuple.

Output Ports Tab

Property Description
Enable Status Adds an output port for emitting status tuples.
Enable Quotes Adds an output port for emitting quote and quote rebuild tuples.
Enable Trades Adds an output port for emitting trade tuples.
Enable Market Imbalance Adds an output port for emitting market imbalance tuples.

Using the Adapter in a StreamBase Application

This section discusses how to use the Lime Citrius Quote input adapter within a StreamBase application. As shown in the diagram below depicting the adapter's sample application, the adapter has two input ports and up to four output ports to communicate with the surrounding application.

The Lime Citrius Quote Input Adapter's ports are used as follows:

  • Input Port 1, Login: Tuples processed from this input port attempt to log into, or log out from, a quote server. Attempts to log out if not logged in result in no action.

    • login, boolean:

      • true - log in

      • false - log out

    • hostName, string: The hostname or IP address of the quote server. This field normally specifies a port number as well. For example, x.y.z.a:12345.

    • username, string: The user name used to login to the quote server.

    • password, string: The password used to login to the quote server.

  • Input Port 2, Subscribe: Tuples enqueued on this port cause the adapter to subscribe to, or unsubscribe from, symbols after the adapter has started. The schema of the subscription port is derived from the upstream operator or stream and must have the following fields.

    • subscribe, boolean:

      • true - subscribe

      • false - unsubscribe

    • quoteSource, string: the Lime Citrius quote source name. If null, the value of this field is taken from the adapter's Quote Source property. The special value ___ALL___ (that is, ALL preceded and followed by three underscore characters) may be used when requesting unsubscription from all symbols from all quote sources that currently have active subscriptions from this instance of the adapter. Using ___ALL___ when subscribing has no meaning.

    • symbols, string: a comma-separated list of symbols to subscribe to or unsubscribe from. If null, the value of this field is taken from the adapter's Symbols property. The special value ___ALL___ (that is, ALL preceded and followed by three underscore characters) may be used to request subscription to or unsubscription from all symbols from the specified quote source.

  • Output Port 1, Status: This output port emits status, information, and error tuples. Specifically, all QuoteAlert, QuoteStreamConnectionStatus, QuoteSystemAPIError messages received by their respective API callbacks generate a tuple out this port. In addition, the adapter itself generates internal adapter error tuples on this port. The Status port has the following schema:

    • type, string: Contains one of the following values describing the type of event that occurred:

      • Quote alert

      • Connection status

      • API error

      • Login succeeded

      • Login failed

      • Logout succeeded

      • Logout failed

      • Subscribe failed

      • Unsubscribe failed

    • code, string: The numeric and translated version of the status code returned from Lime Citrius API

    • message, string: A human-readable message string

    • quoteSource, string

    • symbol, string

    • inputTuple, string: If available, a string representation of the tuple enqueued to the adapter that resulted in the status tuple

  • Output Port 2, Quotes: This output port emits Quote, QuoteBookRebuildStarted, and QuoteBookRebuildComplete tuples. Quote tuples are emitted when a subscribed-to security quote changes. Each Quote tuple represents a single-sided order or quote from a quote source for a symbol and possibly a market maker. A QuoteBookRebuildStarted tuple indicates the book for a symbol should be cleared and subsequent Quote tuples used to rebuild the book for that symbol. After all the quotes for the current book are delivered, a QuoteBookRebuildComplete tuple is emitted. The Quotes port has the following schema:

    • rebuild, string: null, "Started", or "Complete" for Quote, QuoteBookRebuildStarted, and QuoteBookRebuildComplete tuples, respectively.

    • side, string: B = buy (or bid), S = sell (or ask)

    • symbol, string: The security symbol representing this quote.

    • id, long: A unique id to identify this particular quote

    • quoteSize, int: The quantity offered for this security. Zero means removed.

    • price, double: The price offered or asked for this security.

    • mmId, string. The firm or exchange initiating the quote.

    • quoteSource, string. The source of this quote.

    • quoteTime, long. The number of milliseconds since midnight in exchange timezone.

    • quoteProperties, int. Conveys SIAC or NYSE quote conditions and INET additional properties.

    • isTopOfBook, boolean. True if quote is the top of the quote server's quote book and false otherwise.

    • isNBBO, boolean. True if quote is designated as the NBBO by the venue and false otherwise. This field is null when running against pre-2.0.x Lime servers.

    • isAggregateByPrice, boolean. True if quote is part of a price-aggregated view of the quote server's quote book and false otherwise.

  • Output Port 3, Trades: This output port emits a tuple for a trade print on a security subscribed to. The Trades port has the following schema:

    • symbol, string: The security symbol representing this trade.

    • tradeSize, int: The quantity that traded.

    • price double: The price that it traded at.

    • totalVolume, int: The total volume traded for this security.

    • exchangeId, string: The exchange code for the exchange on which this trade occurred. This field is null if this information is unavailable.

    • quoteSource, string: The source of this trade tick.

    • tradeTime, long: The time stamp of this trade — the number of milliseconds since midnight in the exchange's time zone.

    • tradeType, string: Order type of the aggressive party (liquidity remover). Only set for INET and BRUT. Values are BUY, SELL or null (if not present).

  • Output Port 4, MarketImbalance: This output conveys raw Market Imbalance data and has the following schema:

    • exchangeId, string: The exchange code.

    • feedSpecificData, int:

      • Arca - least significant two bytes equal the projected auction time as binary integer in hhmm format, so if for example if the opening auction is scheduled at 4:30 AM, a binary value of 430 would be stored in this field.

      • NYOU - least significant byte is the Imbalance Indicator. For opening imbalance, if this field is 1, it indicates that the stock is open and no more imbalance messages would be sent after this. For closing imbalance if this field is one it indicates that the imbalance is regulatory otherwise it is informational. A space indicates that it is not applicable.

      For more information on this field, please refer to the individual market specifications.

    • imbalanceType, string:

      • unknown (ARCA, NYSE)

      • open (ARCA, NYSE)

      • market (ARCA)

      • halt (ARCA)

      • close (ARCA, NYSE)

      • no imbalance (NYSE)

    • marketImbalance, int: The total imbalance between market orders

    • totalImbalance, int: The total number of shares paired at the reference price

    • pairedShares, int: The total number of shares paired at the reference price

    • price, double: The imbalance price

    • quoteSource, string: Lime-specific quote source

    • side, string: B = buy (or bid), S = sell (or ask), U = unknown

    • symbol, string: The security symbol

    • imbalanceTime, long: The market venue timestamp expressed as milliseconds since midnight

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

  1. Within StreamBase Studio, create a project, including a StreamBase EventFlow diagram, that will host the adapter

  2. Drag an instance of the Lime Citrius Quote adapter from the Project Adapters drawer in the Palette view to the canvas.

  3. Connect Input and Output streams to the adapter's two input and four output ports. Configure the schema of the input stream as defined in the descriptions of the login and subscription ports above. The adapter informs you of any missing fields in the input port and any type-conflicts in output data ports.

  4. Select or double-click the adapter icon, and in the Properties view, click Adapter Settings and fill in any desired properties. There are no required properties.

Typechecking and Error Handling

The Lime Citrius Quote Input adapter uses typecheck messages to help you configure the adapter within your StreamBase application. In particular, the adapter generates typecheck messages when one or more required fields in the input schema are missing or an invalid property value is entered Note that the Lime Citrius Quote input adapter status port is distinct from the Error Port mechanism. The adapter may cause errors to be raised when it encounters exceptions at runtime that it does not otherwise handle.

The adapter generates messages on the status port during runtime under various conditions, including:

  • A login or logout attempt to the quote server fails or causes an exception.

  • A symbol subscription or unsubscription request fails or causes an exception.

  • A tuple received on the subscription port contains a null quote source value.

Suspend and Resume Behavior

When suspended, the Lime Citrius Quote input adapter logs out from the Lime quote server, if it had been logged in, and stops emitting quote and trade tuples.

When resumed, the adapter logs in to Lime quote server, if it had been logged in at the time of suspension, re-subscribes to the quote sources and symbols it had been subscribed to, and begins emitting quote and traded tuples.

Related Topics