EMA C++ Configuration Guide : 3 Configuration Groups : 3.1 ConsumerGroup : 3.1.4 Consumer Entry Parameters
 
3.1.4 Consumer Entry Parameters
Use the following parameters when configuring a Consumer.
 
Table 4: Consumer Group Parameters  
Parameter
Type
Default
Description
CatchUnhandledException
UInt64
1
Specifies whether the Enterprise Message API catches unhandled exceptions thrown from methods executed on the Enterprise Message API's thread or whether the Enterprise Message API lets the application handle them. Available values include:
0 (false): the Enterprise Message API passes unhandled exceptions to the operating system.
1 (true): Whenever the Enterprise Message API catches unhandled exceptions in its thread, the Enterprise Message API logs an error message and then terminates the thread.
CatchUnknownJsonFids
UInt64
1
Specifies whether the RWF/JSON conversion catches unknown JSON field IDs. Possible values are:
0 (false): Do not catch unknown JSON field IDs.
1 (true): Catch unknown JSON field IDs.
CatchUnknownJsonKeys
UInt64
0
Specifies whether the RWF/JSON conversion catches unknown JSON keys. Possible values are:
0 (false): Do not catch unknown JSON keys.
1 (true): Catch unknown JSON keys.
Channel
EmaString
N/A
Specifies the channel that the Consumer component should use. This channel must match the Name parameter from the appropriate <Channel> entry in the ChannelGroup configuration.
If Channel is not specified, the Enterprise Message API resorts to default channel behavior when needed. For further details on the <Channel> entry and default behaviors, refer to Section 3.4.
ChannelSet
EmaString
N/A
Specifies a comma-separated set of channels names. Each listed channel name should have an appropriate <Channel> entry in the ChannelGroup. Channels in the set will be tried with each reconnection attempt until a successful connection is made.
For further details refer to Section 3.4.9.
NOTE: If both Channel and ChannelSet are configured, then the Enterprise Message API uses the parameter that is configured last in the file. For example, if <Channel> is configured after <ChannelSet> then the Enterprise Message API uses <Channel>, but if <ChannelSet> is configured after <Channel> then the Enterprise Message API uses <ChannelSet>.
CloseChannelFromConverterFailure
UInt64
1
Specifies that the Enterprise Message API should close the channel if the Enterprise Message API fails to parse JSON messages or if the Enterprise Message API receives JSON error messages. Possible values are:
0 (false): Do not close the channel.
1 (true): Close the channel.
DefaultServiceID
UInt64
1
Specifies a default service ID for RWF/JSON conversion if both service name and ID are missing. The maximum allowable value is 65535.
Dictionary
EmaString
N/A
Specifies how the consumer should access its dictionaries (it must match the Name parameter from the appropriate <Dictionary> entry in the DictionaryGroup configuration).
If Dictionary is not specified, the Enterprise Message API uses the channel’s dictionary when needed. For further details on this default behavior, refer to Section 3.9.
DictionaryRequestTimeOut
UInt64
45,000
Specifies the amount of time (in milliseconds) the application has to download dictionaries from a provider before the OmmConsumer throws an exception.
If set to 0, the Enterprise Message API will wait for a response indefinitely.
NOTE: If ChannelSet is configured:
The Enterprise Message API honors DictionaryRequestTimeOut only on its first connection.
If the channel supporting the first connection goes down, the Enterprise Message API does not use DictionaryRequestTimeOut on subsequent connections.
DirectoryRequestTimeOut
UInt64
45,000
Specifies the amount of time (in milliseconds) the provider has to respond with a source directory refresh message before the OmmConsumer throws an exception.
If set to 0, the Enterprise Message API will wait for a response indefinitely.
NOTE: If ChannelSet is configured:
The Enterprise Message API honors DirectoryRequestTimeOut only on its first connection.
If the channel supporting the first connection goes down, the Enterprise Message API does not use DirectoryRequestTimeOut on subsequent connections.
DispatchTimeoutApiThread
Int64
-1
Specifies the duration (in microseconds) for which the internal Enterprise Message API thread is inactive before going active to check whether a message was received.
If set to less than zero, the Enterprise Message API internal thread goes active only if it gets notified about a received message.
EnableRtt
UInt64
0
Specifies whether the OmmConsumer supports gathering RoundTripLatency statistics. If enabled, the Watchlist handles automatic processing of RTT requests sent by the provider. EnableRtt expresses the consumer's consent to process RTT requests. The provider may choose either to send or not to send the requests at its own discretion.
Available values include:
0 (false)
Any value > 0 (true)
ItemCountHint
UInt64
100,000
Specifies the number of items the application expects to request. If set to 0, the Enterprise Message API resets it to 513.
For better performance, the application can set this to the approximate number of item requests it expects.
JsonExpandedEnumFields
UInt64
0
Sets the RWF/JSON conversion to expand enumerated values in field entries to their display values for JSON protocol. Possible values are:
0 (false): Do not expand enumerated fields.
1 (true): Expand enumerated fields.
Logger
EmaString
N/A
Specifies a set of logging behavior the Consumer should exhibit (it must match the Name parameter from the appropriate <Logger> entry in the LoggerGroup configuration).
If Logger is not specified, the Enterprise Message API uses a set of logger default behaviors. For further details on the <Logger> entry and default settings, refer to Section 3.8.
LoginRequestTimeOut
UInt64
45,000
Specifies the amount of time (in milliseconds) the provider has to respond with a login refresh message before the OmmConsumer throws an exception.
If set to 0, the Enterprise Message API will wait for a response indefinitely.
NOTE: If ChannelSet is configured:
The Enterprise Message API honors LoginRequestTimeOut only on its first connection.
If the channel supporting the first connection goes down, the Enterprise Message API does not use LoginRequestTimeOut on subsequent connections.
MaxDispatchCountApiThread
UInt64
100
Specifies the maximum number of messages the Enterprise Message API dispatches before taking a real-time break.
MaxDispatchCountUserThread
UInt64
100
Specifies the maximum number of messages the Enterprise Message API can dispatch in a single call to the OmmConsumer::dispatch().
MaxOutstandingPosts
UInt64
100,000
Specifies the maximum allowable number of on-stream posts waiting for an acknowledgment before the OmmConsumer disconnects.
MaxEventsInPool
Int64
-1
Specifies the maximum number of event objects in the event's pool.
MsgKeyInUpdates
UInt64
1
Specifies whether the Enterprise Message API fills in message key values on updates using the message key provided with the request. Available values include:
0 (false): Do not fill in the message’s key values (values received from the wire are preserved).
1 (true): Fill in the message’s key values (values received from the wire are overridden).
Name
EmaString
N/A
Specifies the name of this Consumer component. Name is required when creating a Consumer component.
You can use any value for Name.
ObeyOpenWindow
UInt64
1
Specifies whether the OmmConsumer obeys the OpenWindow from services advertised in a provider’s Source Directory response. Available values include:
0 (false)
1 (true)
OutputBufferSize
UInt64
65535
Sets the size of the output buffer for the RWF/JSON conversion.
WARNING! If the buffer size is not large enough, the RWF/JSON conversion fails.
JsonTokenIncrementSize
UInt64
500
Sets the number of JSON token increment size for parsing JSON messages.
PipePort
Int64
9001
Specifies the internal communication port. You might need to adjust this port if it conflicts with other processes on the machine.
PostAckTimUInt64eout
UInt64
15,000
Specifies the length of time (in milliseconds) a stream waits to receive an ACK for an outstanding post before forwarding a negative acknowledgment to the application.
If set to 0, the Enterprise Message API will wait for a response indefinitely.
ReconnectAttemptLimit
Int64
-1
Specifies the maximum number of times the consumer and non-interactive provider attempt to reconnect to a channel when it fails.
If set to -1, the consumer and non-interactive provider continually attempt to reconnect.
ReconnectMaxDelay
Int64
5000
Sets the maximum amount of time the consumer and non-interactive provider wait (in milliseconds) before attempting to reconnect a failed channel. Refer also to the ReconnectMinDelay parameter.
ReconnectMinDelay
Int64
1000
Specifies the minimum amount of time the consumer and non-interactive provider wait (in milliseconds) before attempting to reconnect a failed channel. This wait time increases with each connection attempt, from ReconnectMinDelay to ReconnectMaxDelay.
ReissueTokenAttemptInterval
Int64
5000
Sets the delay (in milliseconds) before the OMMConsumer attempts to reissue the token. The minimum interval is 1000 milliseconds, while the default setting is 5000.
ReissueTokenAttemptLimit
Int64
-1
Specifies the maximum number of times the OMMConsumer attempts to reissue the token. If set to default (i.e., -1), there is no maximum limit.
RequestTimeout
UInt64
15,000
Specifies the amount of time (in milliseconds) the OmmConsumer waits for a response to a request before sending another request.
If set to 0, the Enterprise Message API will wait for a response indefinitely.
RestEnableLog
UInt64
0
Enables REST request/response logging for OmmConsumer interactions (not including Service Discovery) via filestream to either a file (see RestLogFileName) or stdout. Ability to dynamically enable or disable this parameter is supported.
You can specify a log destination in RestLogFileName.
RestEnableLogViaCallback
UInt64
0
Enables REST request/response logging via callback. This parameter works in conjunction with setting the callback: restLoggingCallback. That is, logs are available by servicing callback: onRestLoggingEvent. Ability to dynamically enable or disable this parameter is supported.
RestLogFileName
EmaString
N/A
Allow redirecting REST logs (enabled by RestEnableLog) to some specified file or stream. If this value is not set, the log is sent to standard output (stdout).
RestProxyHostName
EmaString
N/A
Specifies the address or host name of the proxy server to which the Enterprise Message API connects for REST requests: service discovery and auth token service.
Any value provided by a function call overrides the setting in the configuration file.
NOTE: This proxy overrides the proxy settings (ProxyHost) for REST requests in the Channel group. Refer to Section 3.4.4 and Section 3.4.5.
RestProxyPort
EmaString
N/A
Specifies the port of the proxy server to which the Enterprise Message API connects for REST requests: service discovery and auth token service.
Any value provided by a function call overrides the setting in configuration file.
NOTE: This proxy overrides the proxy settings (ProxyPort) for REST requests in the Channel group. Refer to Section 3.4.4 and Section 3.4.5.
RestRequestTimeOut
UInt64
90
Specifies the timeout (in seconds) for token service and service discovery request. If the request times out, the OMMConsumer resends the token reissue and the timeout restarts. If the request times out, the OMMConsumer does not retry.
If set to 0, there is no timeout.
RestVerboseMode
UInt64
0
Enables verbose REST logging. Ability to dynamically enable or disable this parameter is supported.
SendJsonConvError
UInt64
0
Set the RWF/JSON conversion to send back to the provider conversion error in case it occurs. Possible values are:
0 (false): Do not send conversion error.
1 (true): Send conversion error.
ServiceCountHint
UInt64
513
Sets the size of directory structures for managing services. If the application specifies 0, the Enterprise Message API resets it to 513.
ShouldInitializeCPUIDlib
UInt64
1
Specifies whether the Enterprise Message API configures low level Enterprise Transport API to initialize CpuId library (default behavior), or not.
Possible values are:
0 (false): ETA should not initialize CpuId library.
1 (true): ETA should initialize CpuId library.
For further details, refer to the Transport API C Edition Developers Guide.
TokenReissueRatio
Double
.8
Specifies the ratio with which to multiply the access token’s expiration time (in seconds) to determine the length of time the OMMConsumer waits before retrieving a new access token and refreshing its connection to Real-Time - Optimized. The valid range is from 0.05 to 0.95.
WarmStandbyChannelSet
EmaString
N/A
Specifies a comma-separated set of warm standby channels names. Each listed name should have an appropriate WarmStandbyChannel entry in WarmStandbyGroup. Warm standby channels in the set will be moved to another warm standby channel when it failed to establish a connection for the entire warm standby channel.
NOTE:  
If both WarmStandbyChannelSet and ChannelSet are configured, then EMA uses the parameter that is configured in the WarmStandbyChannelSet before moving to ChannelSet.
When using both WarmStandby and ChannelSet, set reconnectAttemptLimit to a value other than default (-1) to avoid retrying servers within a WarmStandbyGroup indefinitely.
XmlTraceDump
UInt64
0
Sets the Enterprise Message API to trace dump RWF messages after converting them from JSON messages. Possible values are:
0 (false): Do not trace dump data.
1 (true): Trace dump data.
XmlTraceFileName
EmaString
EmaTrace
Sets the name of the file to which to write XML trace output if tracing is selected.
XmlTraceHex
UInt64
0
Sets whether to print incoming and outgoing messages in hexadecimal format. Possible values are:
0 (false): Do not print messages in hexadecimal format.
1 (true): Print messages in hexadecimal format.
XmlTraceMaxFileSize
UInt64
100000000
Specifies the maximum size (in bytes) for the trace file.
XmlTracePing
UInt64
0
Sets the Enterprise Message API to trace incoming and outgoing ping messages. Possible values are:
0 (false): Do not trace ping messages.
1 (true): Trace ping messages.
XmlTracePingOnly
UInt64
0
Sets the Enterprise Message API to trace incoming and outgoing ping messages. Allows to trace pure ping messages without any other trace data. Possible values are:
0 (false): Do not trace ping messages.
1 (true): Trace ping messages.
XmlTraceRead
UInt64
1
Sets the Enterprise Message API to trace incoming data. Possible values are:
0 (false): Do not trace incoming data.
1 (true): Trace incoming data
XmlTraceToFile
UInt64
0
Sets whether the Enterprise Message API traces its messages to an XML file whose name is set by XmlTraceFileName. Available values are:
0 (false): Turns off tracing.
1 (true): Turns on tracing to an XML file.
XmlTraceToMultipleFiles
UInt64
0
Specifies whether to write the XML trace to multiple files. Possible values are:
1 (true): the Enterprise Message API writes the XML trace to a new file if the current file size reaches the XmlTraceMaxFileSize.
0 (false): the Enterprise Message API stops writing the XML trace if the current file reaches the XmlTraceMaxFileSize.
XmlTraceToStdout
UInt64
0
Specifies whether the Enterprise Message API traces its messages in XML format to stdout. Possible values are:
0 (false): Turns off tracing.
1 (true): Turns on tracing to stdout.
XmlTraceWrite
UInt64
1
Sets the Enterprise Message API to trace outgoing data. Possible values are:
0 (false): Do not trace outgoing data.
1 (true): Trace outgoing data.