Reuters RMDS Subscribing Input Adapter

Contents

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

Introduction

The StreamBase Reuters RMDS Subscribing Adapter allows a StreamBase application to receive market data from Reuters RMDS 5 and 6 servers. This adapter supersedes the Reuters OMM Subscribing (RMDS 6) adapter and is intended to replace the Reuters Subscribing (RMDS 5) adapter, which is being phased out.

Note

The adapter described on this page supports both RMDS 5 and RMDS 6. By contrast, the older Reuters Subscribing Input Adapter supports RMDS 5 only. This Reuters Subscribing Adapter remains supported for existing projects, but new StreamBase applications should take advantage of the new adapter described on this page.

This adapter supports the following Reuters message models:

  • MarketFeed (RMDS 5)

  • MarketPrice

  • MarketByOrder

  • MarketByPrice

  • MarketMaker

  • SymbolList

The MarketFeed and MarketPrice models consist of a flat set of key/value pairs. The adapter emits a tuple on its market data output port for each MarketFeed or MarketPrice message received. The other models are hierarchical, containing an arbitrary number of elements, each consisting of a fixed set of key/value pairs. For these models, the adapter emits a tuple for each element affected (added, removed, or modified) by a Reuters message.

The adapter supports both initial (static) and dynamic subscriptions. Initial subscriptions are specified within an optional initial subscriptions file, which is processed when the adapter starts. Later, items can be subscribed to, or unsubscribed from, by enqueuing tuples to the adapter's dynamic subscription input port. Snapshots, which return an image but no subsequent updates, can be requested either statically or dynamically.

The adapter's set of active subscriptions can be retrieved by enqueuing a tuple to the adapter's information query input port. When queried, the adapter emits a stream of tuples representing the set of active subscriptions on its information query output port. For RMDS 6, the info query mechanism can be used to retrieve the set of fields in the loaded data dictionary.

The adapter emits tuples on its event output port to convey important events to the StreamBase application, such as login success or failure, dictionary loading activity, connection and service up/down events, and item status messages. Event tuples contain fields that specify the event type, object, action, status, and description.

The adapter is configured through a collection of properties set in the adapter's Properties view within StreamBase Studio. Properties specify, among other things, the Reuters message model being used by the adapter instance, the RFA session name, optional RFA configuration and initial subscription files, and dictionary and login information.

The optional RFA configuration (preferences) file defines RFA namespaces, sessions, and connections. It can be created using the StreamBase RFA/Java Configuration Wizard provided with StreamBase Studio or the Reuters Configuration Editor shipped with the Reuters Foundation API - Java Edition SDK. If a preferences file is provided, its contents are imported into the Java preferences database and subsequently accessed by the RFA/Java library. If other RFA client applications have been used on the system, it may be possible to reuse the existing preferences, in which case the preferences file name can be left blank.

Properties

Property Description
Reuters Message Model The Reuters Message Model to be used by this instance of the adapter: MarketFeed (RMDS 5), MarketPrice, MarketByOrder, MarketByPrice, MarketMaker, and SymbolList.
RFA Configuration File The name of the RFA configuration (preferences) file. This file may not be required if the preferences from another RFA client application are being reused. If specified, the contents of this file is imported into the Java preferences database when the adapter starts.
RFA Session Name The session name within the Java preferences database to use in accessing the Reuters RMDS server. The session name must include a namespace prefix and a double colon delimiter (::).
Download Data Dictionary (RMDS 6 only)

When set, data dictionaries are downloaded from the Reuters server. Dictionaries are downloaded from all available Reuters services that supply them. Later, when processing an OMM message containing market data, the adapter uses the "best available" dictionary, prioritized as follows: 1) dictionary downloaded from the same Reuters service as the OMM message; 2) dictionary loaded from the local file system; 3) dictionary downloaded from a different Reuters service than the OMM message.

Note

When using MarketFeed (RMDS 5), dictionary downloading is controlled by downloadDataDict Java preference.

Field Dictionary File Name The file name of the field data dictionary. For RMDS 6 message models, a locally-loaded dictionary is used only when a dictionary has not been downloaded for the Reuters service from which the OMM message was received.

Note

When using MarketFeed (RMDS 5), the local dictionary file is specified by masterFidFile Java preference.

Enumeration Dictionary File Name The file name of the enumeration data dictionary. For RMDS 6 message models, a locally-loaded dictionary is used only when a dictionary has not been downloaded for the Reuters service from which the OMM message was received.

Note

When using MarketFeed (RMDS 5), the local enumeration file is specified by enumTypeFile Java preference.

Initial Subscription File Name The name of the file containing zero or more subscription requests processed when the adapter starts. An example initial subscription file is provided with the adapter sample. The example file explains the syntax of a subscription request and contains several commented-out subscriptions.
Username The username value used to log in to the Reuters server and/or enforce entitlements.
Position The position value used to log in to the Reuters server and/or enforce entitlements.
Login Application The application value used to log in to the Reuters server and/or enforce entitlements.
Send Unchanged Fields As Null When set, fields not present in a MarketFeed or MarketPrice update message are sent as null in the resulting market data tuple. Otherwise, the previous value of that field is sent in the tuple.
Send Image on Duplicate Subscribe When set, the adapter emits an image tuple when a subscription is received for an item that has already been subscribed to.
Auto Resubscribe (RMDS 5 only) When set, the adapter explicitly resubscribes to all items after a Reuters RMDS 5 service down/up event. This is normally not necessary, but in some Reuters environments subscriptions have been observed to get lost when a service restarts.
Display Reuters Messages Sent This property is primarily a diagnostic feature. When set, the adapter displays the contents of messages it sends to the Reuters server.
Display Reuters Messages Received This property is primarily a diagnostic feature. When set, the adapter displays the contents of messages it receives from the Reuters server.
Reuters Message Display Filter This property is primarily a diagnostic feature. If blank, every Reuters message is subject to display based on the setting of the previous two properties. Otherwise, the filter is a set of message model names delimited with the pipe symbol ( | ). Valid values include: LOGIN, DIRECTORY, DICTIONARY, MARKET_FEED, MARKET_PRICE, MARKET_BY_ORDER, MARKET_BY_PRICE, MARKET_MAKER, and SYMBOL_LIST. Thus, for example, to see all Login and MarketPrice OMM messages received, set this property to LOGIN|MARKET_PRICE and set Display Reuters Messages Received to true.

Using the Adapter in a StreamBase Application

This section demonstrates how to use the Reuters RMDS subscribing adapter within a StreamBase application and describes the use of the adapter's ports. As shown in the EventFlow diagram below (from this adapter's sample application), the adapter uses two input ports and three output ports to communicate with the surrounding application. As with other StreamBase adapters and operators, you can optionally enable an Error Output Port, as described in Using Error Ports and Error Streams.

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.

Description of This Adapter's Ports

The Reuters RMDS subscribing adapter's ports are used as follows:

  • DynamicSubscribe (input): Tuples enqueued on this port cause the adapter to subscribe to, or unsubscribe from, items after the adapter has started. Initial subscriptions (those processed during startup from entries in the intial subscriptions file) can later be unsubscribed from using this port. The schema of the DynamicSubscribe port is derived from the upstream operator or stream and must have the following fields:

    • Subject, string(40), MarketFeed only: specifies the Reuters 4-part subject name to subscribe to or unsubscribe from. When subscribing by 4-part subject, leave the service and item fields null.

    • Service, string(20): specifies the Reuters service to subscribe to or unsubscribe from.

    • Item, string(20): specifies the item to subscribe to or unsubscribe from.

    • Subscribe, bool: if true, results in a new subscription. Note that the adapter treats bool fields containing null as false. If both Subscribe and Snapshot are false, unsubscribes.

    • Snapshot, bool: if true and Subscribe is false, requests an image with no subsequent updates.

  • InfoQueryIn (input): Tuples enqueued on this port request information from the adapter. The adapter provides the requested information by emitting tuples on its InfoQueryOut port. The InfoQueryIn port has the following fields:

    • Command, string(40): accepts a command specifying the type of metadata being requested. Valid commands include:

      • ListSubscriptions: returns the current set of active subscriptions.

      • DumpDictionary: for RMDS 6 only, returns the contents of the loaded field dictionary. If multiple dictionaries are loaded, use the Param field to specify the Reuters service name used to load the dictionary, or null to dump the dictionary loaded from the local file system.

    • Param, string(40): accepts a command-specific parameter value. Currently, only the DumpDictionary command uses a parameter, which provides the service name used to download the dictionary, or null to dump a locally-loaded dictionary.

    • Tag, string(40): this value is echoed in each tuple emitted from the information query output port in response to a command, allowing responses to be matched with commands.

  • MarketData (output): This is the adapter's primary output port. The adapter emits tuples on this port when it receives Reuters market data messages. This section describes the schema usage for the market data port, and describes how and when the adapter emits market data tuples.

    The market data port's schema consists of both market data and metadata fields. Market data fields are entered via Studio's Edit Schema tab, and their names must match those in the data dictionary. The adapter adds the following metadata fields to the market data output schema:

    • MessageType, string(20): contains IMAGE (MarketFeed only), REFRESH (non-MarketFeed only), UPDATE, or STATUS, depending upon the type of Reuters message that generated the tuple.

    • Subject, string(20), MarketFeed only: contains the Reuters 4-part subject name.

    • Service, string(20): contains the Reuters service name.

    • Item, string(20): contains the item name.

    • RefreshComplete, boolean, MarketByOrder, MarketByPrice, and MarketMaker only: set to true in an item's last refresh tuple, false in all other refresh tuples, and null for non-refresh tuples.

    • Action, string(10), MarketByOrder, MarketByPrice, and MarketMaker only: contains ADD, DELETE, or UPDATE to indicate the action occurring for the specific entry in the order book, market depth, or market maker table.

    • Key, string(20), for MarketByOrder, MarketByPrice, and MarketMaker only: contains a unique identifier for the entry in the order book, market depth, or market maker table.

    • State, string(20), MarketFeed only: for status and image messages, contains one of the following values to convey the item's state:

      • OK

      • CLOSED

      • CLOSED_RECOVER

      • STALE

      • NO_CHANGE

    • StreamState, string(20), non-MarketFeed only: for status and refresh messages, contains one of the following values to convey the item's current stream state:

      • UNSPECIFIED

      • OPEN

      • NONSTREAMING

      • CLOSED_RECOVER

      • CLOSED

      • REDIRECT

    • DataState, string(20), non-MarketFeed only: for status and refresh messages, contains one of the following values to convey the item's current data state:

      • UNSPECIFIED

      • OK

      • SUSPECT

    • StatusCode, string(30): contains one of the following values to convey the item's current status:

      • NONE

      • NOT_FOUND

      • TIMEOUT

      • NOT_ENTITLED

      • INVALID_ARGUMENT

      • USAGE_ERROR

      • PREEMPTED

      • JIT_CONFLATION_STARTED

      • REALTIME_RESUMED

      • FAILOVER_STARTED

      • FAILOVER_COMPLETED

      • GAP_DETECTED

      • NO_RESOURCES

      • TOO_MANY_ITEMS

      • ALREADY_OPEN

      • SOURCE_UNKNOWN

      • NOT_OPEN

    • StatusText, string(120): contains a human-readable description of a item's current status.

    The market data fields present in the market data schema, and the frequency and method with which the adapter emits tuples on this port, vary with the message model the adapter is configured for.

    • MarketFeed is used by RMDS 5 Reuters servers to provide access to trades and quotes from exchanges. The data is structured as field-value pairs, and the adapter emits a single tuple for each MarketFeed message it receives. The first tuple emitted for an item contains the item's initial image (MessageType=IMAGE). The adapter subsequently emits update tuples (MessageType=UPDATE) as market information for that item changes. The adapter can be configured to set unchanged fields in update tuples to null or to the field's previous value.

    • MarketPrice is used by RMDS 6 Reuters servers to provide access to trades and quotes from exchanges. The data is structured as field-value pairs, and the adapter emits a single tuple for each OMM message it receives. The first tuple emitted for an item contains the item's initial image (MessageType=REFRESH). The adapter subsequently emits update tuples (MessageType=UPDATE) as market information for that item changes. The adapter can be configured to set unchanged fields in update tuples to null or to the field's previous value.

    • MarketByOrder provides access to full order books. An order book consists of summary information, such as currency, which applies to all orders in the book, along with a set of zero or more orders. When an application subscribes to a new item, the adapter retrieves the initial order book contents through a set of OMM refresh messages. Upon retrieving the entire order book, the adapter emits a set of refresh tuples (MessageType=REFRESH), one for each order in the book. The adapter then processes OMM messages containing changes to orders in the book, each of which results in an update tuple (MessageType=UPDATE). The specific action — ADD, DELETE, or UPDATE — is conveyed in the Action metadata field. An order's unique identifier is conveyed in the Key metadata field. Summary information appears in every refresh and update tuple.

      The MarketByOrder data fields typically available are:

      • Permission information (PROD_PERM)

      • Currency of the orders (CURRENCY)

      • Trade Units for the precision for which order prices are set (TRD_UNITS)

      • Market State (MKT_ST_IND)

      • Exchange Identifier on which the orders were placed (RDN_EXCHD2)

      • Price Ranking Rules (PR_RNK_RUL)

      • Order Ranking Rules (OR_RNK_RUL)

      • Order Price and Side (BID and ASK, or ORDER_PRC and ORDER_SIDE)

      • Order Size (BIDSIZE, ASKSIZE, or ORDER_SIZE)

      • Price Qualifiers (PRC_QL_CD, PRC_QL2)

      • Market Maker Identifier (MKT_MKR_ID or MMID)

      • Quote Time (QUOTIM_MS)

    • MarketByPrice provides access to market depth information — that is, to Level II data that is aggregated by price and side. The mechanics of tuple emission is identical to that for MarketByOrder. The adapter processes a set of OMM refresh messages to retrieve the full market depth information for an item, emits a refresh tuple (MessageType=REFRESH) for each order, then emits update tuples (MessageType=UPDATE) as market depth changes for that item. The Action and Key metadata fields work identically as for the MarketByOrder message model, and summary information appears in all tuples.

      The MarketByPrice data fields typically available are:

      • Permission information (PROD_PERM)

      • Currency of the orders (CURRENCY)

      • Trade Units for the precision for which order prices are set (TRD_UNITS)

      • Market State (MKT_ST_IND)

      • Exchange Identifier on which the orders were placed (RDN_EXCHD2)

      • Price Ranking Rules (PR_RNK_RUL)

      • Order Price and Side (BID and ASK, or ORDER_PRC and ORDER_SIDE)

      • Order Size (BIDSIZE, ASKSIZE, or ORDER_SIZE)

      • Number of aggregated orders (NO_ORD)

      • Quote Time (QUOTIM_MS)

    • MarketMaker provides access to market maker quotes and trade information. The mechanics of tuple emission is identical to that for MarketByOrder and MarketByPrice.

      The MarketMaker data fields typically available are:

      • Permission information (PROD_PERM)

      • Currency of the orders (CURRENCY)

      • Trade Units for the precision for which order prices are set (TRD_UNITS)

      • Market State (MKT_ST_IND)

      • Exchange Identifier on which the orders were placed (RDN_EXCHD2)

      • Price Ranking Rules (PR_RNK_RUL)

      • Bid (BID)

      • Ask (ASK)

      • Bid Size (BIDSIZE)

      • Ask Size (ASKSIZE)

      • Market Source (MKT_SOURCE)

      • Market Maker Name (MKT_MKR_NM)

      • Price Qualifiers (PRC_QL_CD and PRC_QL2)

      • Quote Time (QUOTIM_MS)

    • Symbol List provides a mechanism to retrive all the symbols available on an exchange. For example, you can subscribe to 0#ARCA to retrieve the set of symbols available on the ARCA exchange.

      The Symbol List data fields typically available are:

      • Permission information (PROD_PERM)

      • The symbol provided by the exchange (PROV_SYMB)

  • Events (output): The adapter emits tuples from this port when significant events occur, such as when a login succeeds or fails, when a data dictionary is loaded, when Reuters connections and services go up and down, and when the adapter is told an item is closed. The schema for this port has the following fields:

    • EventType, string(50): returns one of the following values to convey the type of event:

      • Connection

      • Dictionary

      • Directory

      • Item

      • Login

      • Service

      • Suspend/Resume

      • UserInput

    • Object, string(500): returns an event type-specific value, such as the connection or service name that went up or down, the dictionary file name that was loaded, or the user input that was rejected.

    • ConnectionType, string(20), MarketFeed only: contains the type of RMDS 5 connection, such as SSLED, that went up or down.

    • Action, string(50): returns an action associated with the event Type and Object, such as Loaded or Failed to load after a dictionary load attempt.

    • State, string(20), MarketFeed only: returns the state of an RMDS 5 connection, service, or item. Refer to the description of the State field in the Market Data port for a list of the possible values.

    • StreamState, string(20), non-MarketFeed only: returns the stream state returned in an OMM message. Refer to the description of the StreamState field in the Market Data port for a list of the possible values.

    • DataState, string(20), non-MarketFeed only: returns the data state returned in an OMM message. Refer to the description of the DataState field in the Market Data port for a list of the possible values.

    • StatusCode, string(30): returns a code to convey status about the event. Refer to the description of the StatusCode field in the Market Data port for a list of the possible values.

    • StatusText, string(120): contains a human-readable description of a connection, service or item's current status.

    • ItemEventType, string(20), MarketFeed only: returns the type of item event:

      • IMAGE

      • UNSOLICITED_IMAGE

      • UPDATE

      • CORRECTION

      • CLOSING_RUN

      • STATUS

      • RENAME

      • PERMISSION_DATA

      • GROUP_CHANGE

    • ItemName, string(20): returns the item name associated with the event.

    • SubjectName, string(40), MarketFeed only: returns the 4-part subject name associated with the event.

    • NewItemName, string(20, MarketFeed only): on item rename events, returns an item's new name.

    • NewSubjectName, string(40), MarketFeed only: on item rename events, returns an item's new 4-part subject name.

    • Info, string(500): Returns a human-readable description of the event.

  • InfoQueryOut (output): The adapter emits tuples on this port in response to information query commands. The InfoQueryOut port has the following schema:

    • Done, bool: Set to false for all but the last tuple emitted in response to a specific command. The final (marker) tuple has Done set to true and all other fields set to null.

    • Command, string(40): returns the command value specified in the corresponding information query request tuple.

    • Param, string(40): returns the param value specified in the corresponding information query request tuple.

    • Tag, string(40): returns the tag value specified in the corresponding information query request tuple.

    • Info1-Info5, string(100): returns one or more command-specific values. The description of the InfoQueryIn stream above lists the information returned for each command.

Adding the Adapter to an EventFlow Application

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

  1. Within StreamBase Studio, create a project, including an empty StreamBase EventFlow Application file, which will host the adapter.

  2. Import into the project the sample RFA configuration file, rfa-config.xml, which is located in streambase-install-dir/sample/adapter/embedded/reuters-rmds-sub. Edit this file and change the P2PS (serverList and portNumber) or RTIC (daemon, network, and service) parameters to match the Reuters infrastructure at your site. Take note of the namespace and session names, as they will be used below. In the configuration file shipped with the sample, these values are SBSubscribeNamespace and SBSubscribeRFA6Session (SBSubscribeSession for MarketFeed), respectively.

  3. From the Global Adapters drawer of the Palette view, drag a ReutersRMDSSubscribe component to the canvas.

  4. Double-click the adapter icon, and in the Properties view, select the Adapter Settings tab.

  5. Select a Reuters Message Model from the drop-down.

  6. In the RFA Configuration File field's dropdown list, select the RFA Configuration File you imported into the project above.

  7. In the RFA Session Name field, enter the namespace and session names, delimited by a double colon (::) in the RFA Session Name text entry box. For example, enter SBSubscribeNamespace::SBSubscribeSession.

  8. If you will be downloading data dictionaries from the Reuters server, mark the Download Data Dictionary checkbox (for MarketFeed, you must edit the RFA preferences file, e.g., rfa-config.xml to enable dictionary downloading). If not downloading, enter the names of the Field and Enumeration dictionary files. Note that sample versions of these files are shipped with the adapter in streambase-install-dir/sample/adapter/embedded/reuters-rmds-sub/RDMFieldDictionary (appendix_a for MarketFeed) and streambase-install-dir/sample/adapter/embedded/reuters-rmds-sub/enumtype-rmds6.def (enumtype-rmds5.def for MarketFeed), which you can import into your project and select from the drop-downs.

  9. If you wish to have the adapter subscribe to one or more items when it starts, you can specify an Initial Subscriptions File Name in the drop-down. A sample file is available for import into your project in streambase-install-dir/sample/adapter/embedded/reuters-rmds-sub/initial_subscriptions.txt.

  10. Enter Username, Position, and Application values as necessary for accessing the Reuters server at your site. Note that at many sites one or more of these parameters are optional and can be left blank.

  11. By default, the adapter, in processing Market Price update messages, sends null in unchanged tuple fields. Uncheck Send Unchanged Fields as Null to have the adapter send the previous value of such fields.

  12. The last three adapter properties — Display OMM Messages Sent and Received, and OMM Message Display Filter — are used for debugging and should typically be left with their default, empty values.

  13. Connect Input and Output Streams to the adapter's two input and three output ports.

  14. Configure the schemas of the two input ports and add market data fields to the adapter's primary (MarketData) output port. (The schemas of the Events and InfoQueryOut output ports are set automatically by the adapter, as are the metadata fields of the MarketData output port.) The specific fields required in the two input schemas are specified above in the descriptions of the DynamicSubscribe and InfoQueryIn ports. The adapter guides you through this process, displaying Typecheck Errors when an expected field is missing or of the wrong type or length, or if an unexpected field is present in the schema.

Typechecking and Error Handling

The Reuters RMDS subscribing adapter uses typecheck messages to help you configure the adapter within your StreamBase application. In particular, the adapter generates typecheck messages for the following reasons:

  • A Reuters Message Model has not been selected from the drop-down.

  • An invalid RFA configuration file name has been entered.

  • An invalid RFA session name has been entered. Session names must be of the form namespace::session.

  • Dictionary downloading is disabled and no field or enumeration dictionary file name has been provided.

  • An invalid initial subscription file name has been entered.

  • One or more required fields in the two input schemas or primary output schema is missing or is of the wrong type or size.

The adapter generates warning messages during runtime under various conditions, including:

  • The adapter fails to log in to the Reuters server.

  • The adapter is unable to read a local data dictionary file.

  • An unexpected or malformed Reuters message is received.

  • In processing an Reuters message, a string is truncated to fit in an output tuple.

  • The data type for a field in the market data schema is incompatible with the data type in the Reuters message.

  • A field in the market data output schema is not present in the data dictionary.

  • A string field in the market data output schema is shorter than the field length specified in the data dictionary.

  • A field in an Reuters message is not present in the data dictionary.

  • A field in the market data output schema is not present in a Reuters refresh (image) message.

  • The adapter is configured with an invalid Reuters Message Display Filter.

  • An invalid line is detected in the initial subscription file.

  • A dynamic subscription input tuple contains a null or empty server or item name.

  • A request is made to unsubscribe from an item that is not currently subscribed to.

  • An information query input tuple contains a null or empty command or tag value or an unrecognized command.

  • An information query input tuple requests a dump of the data dictionary before it has been loaded.

Suspend/Resume Behavior

When suspended, the adapter continues to receive and process Reuters messages, but no longer emits tuples on its primary output port.

When resumed, the adapter once again starts emitting tuples on its primary output port.

Related Topics