Component blpapi_subscriptionlist [Package blpapi]

Provide a list of subscriptions. More...

Namespaces
namespace	blpapi

---

Detailed Description

Provide a list of subscriptions.

Outline

• Purpose
• Classes
• Description
  • Structure of Subscription String
  • Qualifying Subscription Strings
  • Use of SubscriptionList

Purpose:

Provide a list of subscriptions.

Classes:

blpapi::SubscriptionList

Represents a list of subscriptions.

Description:

This component provides a structure to hold the data used (and returned) by the Session::subscribe, Session::resubscribe, and Session::unsubscribe methods. This structure comprises a list in which each list entry contains two primary fields: a CorrelationId associated with the subscription, and a string, called a subscription string, describing the data to be delivered as a part of the subscription.

Structure of Subscription String:

The simplest form of a subscription string is a fully qualified subscription string, which has the following structure:

 "//blp/mktdata/ticker/IBM US Equity?fields=BID,ASK&interval=2"
  \-----------/\------/\-----------/\------------------------/
        |          |         |                  |
     Service    Prefix   Instrument           Suffix

Such a fully-qualified string is composed of:

Service Identifier: a string matching the expression ^//[-_.a-zA-Z0-9]+/[-_.a-zA-Z0-9]+$, e.g. //blp/mktdata. See blpapi_abstractsession for further details.

Prefix: a string matching the expression /([-_.a-zA-Z0-9]+/)?, often used as a symbology identifier. Common examples include /ticker/ and /cusip/. Not all services make use of prefixes. Note than an "empty" topic prefix consists of the string "/", so the topic prefix always separates the service string from the instrument string.

Instrument: a non-empty string that does not contain the character ? (i.e. a string matching [^?]+) e.g. "IBM US Equity", or "SPX Index". The service, prefix, and instrument together uniquely identify a source for subscription data.

Suffix: a suffix contains a question mark followed by a list of options which can affect the content delivery. The format of these options is service specific, but they generally follow URI query string conventions: a sequence of "key=value" pairs separated by "&" characters. Further, many common services follow the convention that the value given for the fields key is formatted as a comma-separated list of field names. BLPAPI provides several convenience functions to assist in formatting subscription strings for services that make use of these conventions; see the SubscriptionList::add methods for details.

Subscription strings need not be fully qualified: BLPAPI allows the service and prefix to be omitted from subscription strings, and automatically qualifies these strings using information stored in a Session object.

Qualifying Subscription Strings:

The subscription strings passed to Session::subscribe and Session::resubscribe are automatically qualified if the service identifier is missing (i.e. if the subscription string does not start with "//"). The subscription parameters (i.e. the optional part after instrument identifier) are never modified. The rules for qualifying the subscription string are:

• If the subscription string begins with // then it is assumed to be a a fully qualified subscription string including service identifier, prefix, and instrument. In this case the string will not be modified and session options defaults have no affect on the subscription.
• If the subscription string begins with a / and the second character is not /, then the string is assumed to begin with the topic prefix, but no service identifier. In this case the string is qualified by prepending the SessionOptions::defaultSubscriptionService() to the specified string.
• If the subscription string does not begin with a / it is assumed to begin with an instrument identifier. In this case the string is qualified by prepending the SessionOptions::defaultSubscriptionService() followed by SessionOptions::defaultTopicPrefix() to the specified string. If the defaultTopicPrefix is empty or null, then the prefix used is /. Otherwise (in the case of a nontrivial prefix) if the separator / is not specified at the beginning or the end of the defaultTopicPrefix, then it will be added.

Use of SubscriptionList:

A SubscriptionList is used when calling Session::subscribe(), Session::resubscribe() and Session::unsubscribe(). The entries can be constructed in a variety of ways.

The two important elements when creating a subscription are:

Subscription String: A subscription string represents a topic whose updates user is interested in. A subscription string follows the structure specified above.

CorrelationId: the unique identifier to tag all data associated with this subscription.

The following table describes how various operations use the above elements:

 +----------------------------------------------------------------------+
 | OPERATION   |  SUBSCRIPTION STRING  |       CORRELATION ID           |
 |-------------|-----------------------+--------------------------------|
 | 'subscribe' |Used to specify the    |Identifier for the subscription.|
 |             |topic to subscribe to. |If uninitialized correlationid  |
 |             |                       |was specified an internally     |
 |             |                       |generated correlationId will be |
 |             |                       |set for the subscription.       |
 |-------------+-----------------------+--------------------------------|
 |'resubscribe'|Used to specify the new|Identifier of the subscription  |
 |             |topic to which the     |which needs to be modified.     |
 |             |subscription should be |                                |
 |             |modified to.           |                                |
 |-------------+-----------------------+--------------------------------|
 |'unsubscribe'|        NOT USED       |Identifier of the subscription  |
 |             |                       |which needs to be canceled.     |
 +----------------------------------------------------------------------+