Bloomberg Server API Input Adapter

Contents

Introduction
Adapter Ports
Adapter Properties
Suspend and Resume Behavior

Introduction

The TIBCO StreamBase® Adapter for Bloomberg Server API is an embedded adapter that can connect to a Bloomberg Server API process to subscribe to and get data from the process.

Configuration

The adapter can be configured to connect to a Bloomberg service that supports subscriptions to receive subscription data and send it downstream. The service name and connection details can be configured in the adapter properties.

The adapter can be configured to connect to the server two ways:

  • It can connect at startup time.

  • It can connect to the server only when it receives a connect command through its input port.

If the adapter is configured to connect on startup, it attempts to establish server connection when it starts up. If the server is down or if the adapter cannot establish a connection for other reasons, it keeps retrying until it succeeds. Once the connection is established, it proceeds to connect to the required services and subscribe for data, if configured to do so. If the server goes down or if the adapter otherwise loses the connection afterwards, it keeps trying to reestablish the connection until it succeeds. A connect command does not have any effect at this time. A disconnect command disconnects from the server, if it is currently connected, and does not attempt to reconnect until it receives a connect command. If the adapter receives a disconnect command when it is not connected to the server, it stops trying to establish a connection, until it receives a further connect command.

If the adapter is not configured to connect on startup, it waits to receive a connect command on its input port before it attempts to establish connection with the server. Once it receives the connect command, it keeps trying to establish the connection until it succeeds or until it receives a disconnect command.

Adapter Ports

The adapter has one input port and five output ports with two being optional, as shown in the diagram below.

Input Ports

The Commands input port is used to send commands to the adapter to connect to or disconnect from the server, subscribe or unsubscribe for data, or to request metadata, including information about Bloomberg data fields.

The Command input port has the following schema:

  • Command, string

  • SubscriptionParameters, tuple

    • Topics, list<string>

    • Options, string

  • FieldParameters, tuple

    • Id, string

    • SearchSpec, string

    • ProductType, string

    • FieldType, string

  • ReferenceDataParameters, tuple

    • Securities, list(string)

    • Overrides, list(tuple(string FieldId, string Value)) - This field is optional and allows you to specify override field parameters for reference data requests.

  • MarketListSnapshotParameters, tuple

    • Topic, string

SubscriptionParameters contain fields that you use when subscribing or unsubscribing for data. FieldParameters contain fields that you use when requesting information about Bloomberg data fields.

Supported commands are:

  • Connect: Connects to the Bloomberg server. This command does not take any additional parameters.

  • Disconnect: Disconnects from the Bloomberg server. This command does not take any additional parameters.

  • Subscribe: Subscribes to the specified topics. A Topics value must be specified with the Subscribe command, and its values must conform to a topic as specified in Bloomberg API Developer's Guide. If an Options value is specified, it is used to override any default options specified in the adapter properties tab. If the adapter is already subscribed to any of the specified topics, a resubscribe is issued for that topic to avoid losing any updates.

  • Unsubscribe: Unsubscribes from the specified topics. The Topics field must be specified with the Unsubscribe command.

  • ListSubscriptions (or ListSub): Lists the currently active subscriptions. This command does not take any additional parameters. The subscriptions are output through the Metadata output port.

  • FieldInfo: This command can be used to get more information about Bloomberg data fields. Field information is output through the Metadata output port. Id or SearchSpec must be specified when using this command. Multiple values may be specified for Id, separated by commas. If an Id value is specified, a list of Bloomberg fields whose mnemonic or alphanumeric IDs exactly match the specified values is output. If SearchSpec is specified, a list of fields matching the SearchSpec value is output. The value is used to search across mnemonics, descriptions, and definitions. The field search may be further narrowed by specifying ProductType and/or FieldType. For more information, please refer to API Field Information Service section of Bloomberg's BLPAPI Developer's Guide.

  • ReferenceData: This command may be used to request reference data. Field information will be output through the Reference data output port if enabled. One or more Securities must be supplied as part of this request.

  • MarketListSnapshot: This command may be used to request market list snapshot data. Field information will be output through the Market List Snapshot output port if enabled. A single Topic must be supplied with this request.

Output Ports

The adapter has three output ports and two optional ports:

  • Status: Output is produced on this port to notify of changes in connection and subscription status and to indicate error in input commands. Status output port has the following schema:

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

      • Session

      • Service

      • Subscription

      • User Input

      • Suspend/Resume

    • object, string: the object associated with the event, such are connection destination or subscription string.

    • action, string: the action associated with the event, such as Connected, Disconnected or Subscription Failed.

    • message, string: a human readable message string.

  • Metadata: This output port is used to emit output for ListSubscriptions and FieldInfo commands. This output port has the following schema:

    • Subscriptions, tuple

      • SubscriptionString, string

      • CorrelationID, string

    • FieldsResult, tuple

      • FinalResult, boolean

      • FieldsResult

        • Id, string

        • Mnemonic, string

        • DataType, string

        • Description, string

        • Category, string

        • FieldError, string

    Subscriptions field in the schema is used to list the active subscriptions. FieldsResult field is used to list the Bloomberg fields that the user searched for. The boolean FinalResult is used to indicate if this is the final set of results of the fields search request.

  • MarketData: This output port emits the data that the user subscribed for. The schema of this port will contain SubscriptionString and CorrelationID fields, in addition to the fields specified by the user using Edit Schema tab. An additional field, named FieldPresence, is used to track whether the aforementioned user fields were present in the update message. This is necessary to properly apply successive updates to the original snapshot of the instrument to maintain its current state. Value fields in the incoming update message can have 3 distinct states:

    1. The value is set and non-null, meaning the field's value has changed and should be updated

    2. The value is null, meaning any cached value for this field should be invalidated and flushed

    3. The field is absent from the incoming message, meaning the previous value remains unchanged

    It is this third state that the FieldPresence field tracks, by presenting a tuple with a similar structure and field names as the user-specified fields, but with their data types set to boolean values used to indicate whether the field was present in the message or not. For example, if the user fields are defined as:

    • BID (double)

    • BID_SIZE (int)

    • ASK (double)

    • ASK_SIZE (int)

    • LAST_PRICE (double)

    • HIGH (double)

    • LOW (double)

    ...then the FieldPresence field will be automatically set to contain a tuple with the following fields:

    • BID (boolean)

    • BID_SIZE (boolean)

    • ASK (boolean)

    • ASK_SIZE (boolean)

    • LAST_PRICE (boolean)

    • HIGH (boolean)

    • LOW (boolean)

    During execution, if an incoming subscription update message has the following fields and values:

    • BID: 100.1

    • BID_SIZE: 10000

    • LAST_PRICE: <null>

    ...then the resulting tuple on the adapter's MarketData port will be as follows:

    • SubscriptionString: ...

    • CorrelationID: ...

    • Token: ...

    • PresenceField:

      • BID: true

      • BID_SIZE: true

      • ASK: false

      • ASK_SIZE: false

      • LAST_PRICE: true

      • HIGH: false

      • LOW: false

    • BID: 100.1

    • BID_SIZE: 10000

    • ASK: <null>

    • ASK_SIZE: <null>

    • LAST_PRICE: <null>

    • HIGH: <null>

    • LOW: <null>

    Any fields present in the incoming Bloomberg message not also specified on the adapter's Edit Schema tab will be ignored.

  • ReferenceData (Optional): This output port emits the data for reference data requests. The schema of this port will contain a Security field, in addition to the fields specified by the user using Edit Schema the tab under the Reference Data section.

  • MarketListSnapshotData (Optional): This output port emits the data for market list snapshot requests. The schema of this port follows the Bloomberg field list for market list snapshot data.

Adapter Properties

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

The tables in this section have a Property column that shows each property name as found in the one or more adapter properties tabs of the Properties view.

General Tab

Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. 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 name: Shows the fully qualified class name that implements the functionality of this adapter. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this adapter starts.

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 to learn about Error Ports.

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

Adapter Properties Tab

Property Data Type Default Description
Connect on Startup check box Selected

Leave this selected if you would like the adapter to connect to the Bloomberg server when the adapter starts up. Clear this if the adapter should connect to the Bloomberg server only on receiving a connect command on its input port.

Enable command input port check box Selected

Clear this if the input port will not be used at all. In this case, all subscriptions must be made using Initial Subscriptions property.

Enable reference data output port check box Cleared

Select this if the adapter should enable reference data requests.

Enable market list snapshot output port check box Cleared

Select this if the adapter should enable market list snapshot data requests.

Bloomberg Server Host string None

The host name of the Bloomberg server. Multiple server hosts can be specified by using a semicolon separated list such as 'localhost;host2;host3'

Bloomberg Server Port int None

The port number of the Bloomberg server.

UUID string None

The universally unique ID used to log into the Bloomberg service. To determine this value, log into your Bloomberg terminal, type IAM, and press Enter. The displayed value is the UUID for that terminal. Enter the same value in this adapter properties field.

Service Name string None

The name of the service that the adapter should use to subscribe for data.

Default Topic Prefix string None

The default topic prefix that should be used in subscriptions when no prefix is specified by user while subscribing.

Default Subscription Options string None

The default options to be used in subscriptions when no options are specified by user while subscribing.

Max Event Queue Size int 10000

The maximum number of events that can be buffered by the session.

Slow Consumer High Water Mark double 0.75

Set the fraction (0.0 to 1.0] of the event queue size at which 'slow consumer' events will be generated.

Slow Consumer Low Water Mark double 0.5

Set the fraction [0.0 to 1.0) of the event queue size at which 'slow consumer cleared' events will be generated.

Log Missing Output Fields check box Cleared

If the subscription data received from Bloomberg contains fields other than the ones specified by the user using Edit Schema tab, a warning log message can be logged. Select this option if a warning message should be logged about missing output fields.

Log Level drop-down list INFO 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 will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

Initial Subscriptions Tab

Property Data Type Default Description
Initial Subscriptions map of (string, string) None Specify the subscriptions to process at start up time. Zero or more subscriptions can be specified. Topic must be specified. Options is optional.

Edit Schema Tab

Property Data Type Default Description
Subscription Output Schema schema None The fields that should be included in the output produced by the adapter must be specified here. These fields are used by the adapter as the fields of interest at subscription time.
Reference Data Output Schema schema None The fields that should be included in the reference data request. These fields are used by the adapter as the fields of interest at the time a reference data command is received.

The StreamBase field types specified for the fields must be compatible with the Bloomberg field type. If a Bloomberg field cannot be converted to the specified type, a warning message is logged at startup. However, the adapter still tries to process the subscriptions to the best it can. See the table below for the valid conversions. Bloomberg types that are not listed in the table are not allowed.

Bloomberg Type Valid StreamBase Types
BOOL boolean, int, long, double, string
CHAR int, long, double, string
DATE timestamp, string
DATETIME timestamp, string
FLOAT32 double, string
FLOAT64 double, string
INT32 int, long, double, string
INT64 long, string
STRING string
TIME timestamp, string
SEQUENCE list<tuple>

Cluster Aware Tab

Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

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.

Suspend and Resume Behavior

On suspend, the adapter stops processing any subscription data that it receives from the Bloomberg server. However, the events stay in the queue, so that they can be output by the adapter when it resumes.

On resumption, the adapter continues to process the events in its event queue.