blpapi.SessionOptions

class blpapi.SessionOptions

Options which the user can specify when creating a session.

To use non-default options on a Session, create a SessionOptions instance and set the required options and then supply it when creating a Session.

The class attributes represent the possible options for how to connect to the API.

AUTO = 0

Automatic (desktop if available otherwise server)

DAPI = 1

Always connect to the desktop API

SAPI = 2

Always connect to the server API

__init__()

Create a SessionOptions with all options set to the defaults

allowMultipleCorrelatorsPerMsg()
Returns

The value of the allow multiple correlators per message option.

Return type

bool

authenticationOptions()
Returns

Authentication options in a string.

Return type

str

autoRestartOnDisconnection()
Returns

Whether automatically restart connection if disconnected.

Return type

bool

clientMode()
Returns

The value of the client mode option.

Return type

int

connectTimeout()
Returns

The value of the connection timeout option.

Return type

int

defaultKeepAliveInactivityTime()
Returns

The interval (in milliseconds) a connection has to remain inactive (receive no data) before a keep alive probe will be sent.

Return type

int

defaultKeepAliveResponseTimeout()
Returns

The time (in milliseconds) the library will wait for response to a keep alive probe before declaring it lost.

Return type

int

defaultServices()
Returns

All default services in one string.

Return type

str

defaultSubscriptionService()
Returns

The default subscription service.

Return type

str

defaultTopicPrefix()
Returns

The default topic prefix.

Return type

str

destroy()

Destroy this SessionOptions.

flushPublishedEventsTimeout()
Returns

The timeout, in milliseconds, for ProviderSession to flush published events before stopping. The default value is 2000.

Return type

int

getServerAddress(index)
Returns

Server name and port indexed by index.

Return type

(str, int)

keepAliveEnabled()
Returns

True if the keep-alive mechanism is enabled; otherwise return False.

Return type

bool

maxEventQueueSize()
Returns

The value of maximum outstanding undelivered events that the session is configured with.

Return type

int

maxPendingRequests()
Returns

The value of the maximum pending request option.

Return type

int

numServerAddresses()
Returns

The number of server addresses.

Return type

int

numStartAttempts()
Returns

The maximum number of attempts to start a session.

Return type

int

recordSubscriptionDataReceiveTimes()
Returns

Whether the receipt time (accessed via Message.timeReceived()) should be recorded for subscription data messages.

Return type

bool

removeServerAddress(index)

Remove the server address at the specified index.

Parameters

index (int) – Index to remove the address at

serverAddresses()
Returns

Iterator over server addresses for this SessionOptions.

serverHost()
Returns

The server host option in this SessionOptions

instance.

Return type

str

serverPort()
Returns

The server port that this session connects to.

Return type

int

serviceCheckTimeout()
Returns

The value of the service check timeout option in this SessionOptions instance in milliseconds.

Return type

int

serviceDownloadTimeout()
Returns

The value of the service download timeout option in this SessionOptions instance in milliseconds.

Return type

int

setAllowMultipleCorrelatorsPerMsg(allowMultipleCorrelatorsPerMsg)

Associate more than one CorrelationId with a Message.

Parameters

allowMultipleCorrelatorsPerMsg (bool) – Value to set the option to

Set whether the Session is allowed to associate more than one CorrelationId with a Message to the specified allowMultipleCorrelatorsPerMsg. The default is False. This means that if you have multiple subscriptions which overlap (that is a particular Message is relevant to all of them) you will be presented with the same message multiple times when you use the MessageIterator, each time with a different CorrelationId. If you specify True for this then a Message may be presented with multiple CorrelationId’s.

setAuthenticationOptions(authOptions)

Set the specified authOptions as authentication option.

setAutoRestartOnDisconnection(autoRestart)

Set whether automatically restarting connection if disconnected.

Parameters

autoRestart (bool) – Whether to automatically restart if disconnected

setClientMode(clientMode)

Set how to connect to the API. The default is AUTO.

Parameters

clientMode (int) – The client mode

Set how to connect to the API. The default is AUTO which will try to connect to the desktop API but fall back to the server API if the desktop is not available. DAPI always connects to the desktop API and will fail if it is not available. SAPI always connects to the server API and will fail if it is not available.

setConnectTimeout(timeoutMilliSeconds)

Set the connection timeout in milliseconds.

Parameters

timeoutMilliSeconds (int) – Timeout threshold in milliseconds

Set the connection timeout in milliseconds when connecting to the API. The default is 5000 milliseconds. Behavior is not defined unless the specified timeoutMilliSeconds is in range of [1 .. 120000] milliseconds.

setDefaultKeepAliveInactivityTime(inactivityMsecs)

Set the amount of time that no traffic can be received before the keep-alive mechanism is triggered.

Parameters

inactivityMsecs (int) – Amount of time in milliseconds

Set to the specified inactivityMsecs the amount of time that no traffic can be received on a connection before the ping-based keep-alive mechanism is triggered; if no traffic is received for this duration then a keep-alive ping is sent to the remote end to solicit a response. If inactivityMsecs == 0, then no keep-alive pings will be sent. The behavior of this function is undefined unless inactivityMsecs is a non-negative value. The default value is 20,000 milliseconds.

Note

Not all back-end connections provide ping-based keep-alives; this option is ignored by such connections.

setDefaultKeepAliveResponseTimeout(timeoutMsecs)

Set the timeout for terminating the connection due to inactivity.

Parameters

timeoutMsecs (int) – Timeout threshold in milliseconds

When a keep-alive ping is sent, wait for the specified timeoutMsecs to receive traffic (of any kind) before terminating the connection due to inactivity. If timeoutMsecs == 0, then connections are never terminated due to the absence of traffic after a keep-alive ping. The behavior of this function is undefined unless timeoutMsecs is a non-negative value. The default value is 5,000 milliseconds.

Note

that not all back-end connections provide support for ping-based keep-alives; this option is ignored by such connections.

setDefaultServices(defaultServices)

Set the default service for the session.

Parameters

defaultServices ([str]) – The default services

DEPRECATED

Set the default service for the session. This function is deprecated; see setDefaultSubscriptionService().

setDefaultSubscriptionService(defaultSubscriptionService)

Set the default service for subscriptions.

Parameters

defaultSubscriptionService (str) – Identifier for the service to be used as default

Set the default service for subscriptions which do not specify a subscription server to the specified defaultSubscriptionService. The behavior is undefined unless defaultSubscriptionService matches the regular expression ^//[-_.a-zA-Z0-9]+/[-_.a-zA-Z0-9]+$. The default is //blp/mktdata.

setDefaultTopicPrefix(prefix)

Set the default topic prefix.

Parameters

prefix (str) – The topic prefix to set

Set the default topic prefix to be used when a subscription does not specify a prefix to the specified prefix. The default is /ticker/.

setFlushPublishedEventsTimeout(timeoutMsecs)
Parameters

timeoutMsecs (int) – Timeout threshold in milliseconds

Set the timeout, in milliseconds, for ProviderSession to flush published events before stopping. The behavior is not defined unless the specified timeoutMsecs is a positive value. The default value is 2000.

setKeepAliveEnabled(isEnabled)

Set whether to enable keep-alive pings.

Parameters

isEnabled (bool) – Whether to enable keep-alive pings

If the specified isEnabled is False, then disable all keep-alive mechanisms, both from the client to the server and from the server to the client; otherwise enable keep-alive pings both from the client to the server (as configured by setDefaultKeepAliveInactivityTime() and setDefaultKeepAliveResponseTimeout() if the connection supports ping-based keep-alives), and from the server to the client as specified by the server configuration.

setMaxEventQueueSize(eventQueueSize)

Set the maximum number of outstanding undelivered events per session.

Parameters

eventQueueSize (int) – Maximum number of outstanding undelivered events

Set the maximum number of outstanding undelivered events per session to the specified eventQueueSize. All subsequent events delivered over the network will be dropped by the session if the number of outstanding undelivered events is eventQueueSize, the specified threshold. The default value is 10000.

setMaxPendingRequests(maxPendingRequests)

Set the maximum number of requests which can be pending.

Parameters

maxPendingRequests (int) – Maximum number of pending requests

Set the maximum number of requests which can be pending to the specified maxPendingRequests. The default is 1024.

setNumStartAttempts(numStartAttempts)

Set the maximum number of attempts to start a session.

Set the maximum number of attempts to start a session by connecting a server.

setRecordSubscriptionDataReceiveTimes(shouldRecord)
Parameters

shouldRecord (bool) – Whether to record the receipt time

Set whether the receipt time (accessed via Message.timeReceived()) should be recorded for subscription data messages. By default, the receipt time for these messages is not recorded.

setServerAddress(serverHost, serverPort, index)

Set the server address at the specified index.

Parameters
  • serverHost (str) – Server host

  • serverPort (int) – Server port

  • index (int) – Index to set the address at

Set the server address at the specified index using the specified serverHost and serverPort.

setServerHost(serverHost)

Set the API server host to connect to when using the server API.

Parameters

serverHost (str) – Server host

Set the API server host to connect to when using the server API to the specified serverHost. The server host is either a hostname or an IPv4 address (that is, a.b.c.d). The default is 127.0.0.1.

setServerPort(serverPort)

Set the port to connect to when using the server API.

Parameters

serverPort (int) – Server port

Set the port to connect to when using the server API to the specified serverPort. The default is 8194.

setServiceCheckTimeout(timeoutMsecs)
Parameters

timeoutMsecs (int) – Timeout threshold in milliseconds

Set the timeout, in milliseconds, when opening a service for checking what version of the schema should be downloaded. The behavior is not defined unless timeoutMsecs is a positive value. The default timeout is 60,000 milliseconds.

setServiceDownloadTimeout(timeoutMsecs)
Parameters

timeoutMsecs (int) – Timeout threshold in milliseconds

Set the timeout, in milliseconds, when opening a service for downloading the service schema. The behavior is not defined unless the specified timeoutMsecs is a positive value. The default timeout is 120,000 milliseconds.

setSlowConsumerWarningHiWaterMark(hiWaterMark)

Set the point at which “slow consumer” events will be generated.

Parameters

hiWaterMark (float) – Fraction of maxEventQueueSize()

Set the point at which “slow consumer” events will be generated, using the specified hiWaterMark as a fraction of maxEventQueueSize(); the default value is 0.75. A warning event will be generated when the number of outstanding undelivered events passes above hiWaterMark * maxEventQueueSize(). The behavior of the function is undefined unless 0.0 < hiWaterMark <= 1.0. Further, at the time that Session.start() is called, it must be the case that slowConsumerWarningLoWaterMark() * maxEventQueueSize() < slowConsumerWarningHiWaterMark() * maxEventQueueSize().

setSlowConsumerWarningLoWaterMark(loWaterMark)

Set the point at which “slow consumer cleared” events will be generated

Parameters

loWaterMark (float) – Fraction of maxEventQueueSize()

Set the point at which “slow consumer cleared” events will be generated, using the specified loWaterMark as a fraction of maxEventQueueSize(); the default value is 0.5. A warning cleared event will be generated when the number of outstanding undelivered events drops below loWaterMark * maxEventQueueSize. The behavior of the function is undefined unless 0.0 <= loWaterMark < 1.0. Further, at the time that Session.start() is called, it must be the case that slowConsumerWarningLoWaterMark() * maxEventQueueSize() < slowConsumerWarningHiWaterMark() * maxEventQueueSize().

setTlsOptions(tlsOptions)

Set the TLS options

Parameters

tlsOptions (TlsOptions) – The TLS options

slowConsumerWarningHiWaterMark()
Returns

The fraction of maxEventQueueSize() at which “slow consumer” event will be generated.

Return type

float

slowConsumerWarningLoWaterMark()
Returns

The fraction of maxEventQueueSize() at which “slow consumer cleared” event will be generated.

Return type

float

toString(level=0, spacesPerLevel=4)

Format this SessionOptions to the string.

Parameters
  • level (int) – Indentation level

  • spacesPerLevel (int) – Number of spaces per indentation level for this and all nested objects

Returns

This object formatted as a string

Return type

str

If level is negative, suppress indentation of the first line. If spacesPerLevel is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by level).