ETAC_RDMUsageGuide Transport APIC RDMUsage Guide
User Manual: Pdf
Open the PDF directly: View PDF .
Page Count: 151
Download | |
Open PDF In Browser | View PDF |
Transport API C Edition V3.2.x RDM USAGE GUIDE C EDITION Document Version: 3.2.0 Date of issue: 27 April 2018 Document ID: ETAC320UMRDM.180 Legal Information © Thomson Reuters 2015 - 2018. All rights reserved. Thomson Reuters, by publishing this document, does not guarantee that any information contained herein is and will remain accurate or that use of the information will ensure correct and faultless operation of the relevant service or equipment. Thomson Reuters, its agents and employees, shall not be held liable to or through any user for any loss or damage whatsoever resulting from reliance on the information contained herein. This document contains information proprietary to Thomson Reuters and may not be reproduced, disclosed, or used in whole or part without the express written permission of Thomson Reuters. Any Software, including but not limited to, the code, screen, structure, sequence, and organization thereof, and Documentation are protected by national copyright laws and international treaty provisions. This manual is subject to U.S. and other national export regulations. Nothing in this document is intended, nor does it, alter the legal obligations, responsibilities or relationship between yourself and Thomson Reuters as set out in the contract existing between us. Transport API C Edition 3.2.x – RDM Usage Guide ETAC320UMRDM.180 ii Contents Contents Chapter 1 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.7.1 1.7.2 1.7.3 1.8 1.9 Introduction ...................................................................................................................... 1 About this Manual ........................................................................................................................................... Audience ......................................................................................................................................................... Open Message Model (OMM)......................................................................................................................... Reuters Wire Format (RWF) ........................................................................................................................... References...................................................................................................................................................... Documentation Feedback ............................................................................................................................... Conventions .................................................................................................................................................... Typographic .............................................................................................................................................. General Transport API Syntax.................................................................................................................. Definitions and Standard Behaviors ......................................................................................................... Acronyms and Abbreviations .......................................................................................................................... What’s New ..................................................................................................................................................... 1 1 1 1 2 2 2 2 3 3 4 4 Chapter 2 Domain Model Overview.................................................................................................. 5 2.1 2.2 2.7.1 2.7.2 2.7.3 2.7.4 2.7.5 2.7.6 2.7.7 What is a Domain Message Model? ............................................................................................................... 5 Reuters Domain Models (RDMs) Vs User-Defined Models ............................................................................ 5 Reuters Domain Models (RDMs).............................................................................................................. 5 User-Defined Domain Model .................................................................................................................... 6 Domain Message Model Creation ............................................................................................................ 6 ........................................................................................................................................................................ 7 OMM Consumer / OMM Interactive Provider Initial Interaction ....................................................................... 8 OMM Non-Interactive Provider Initial Interaction ............................................................................................ 9 Sending and Receiving Content.................................................................................................................... 10 General Transport API Concepts .................................................................................................................. 11 Snapshot and Streaming Requests ........................................................................................................ 11 Multi-Part Messages ............................................................................................................................... 11 Reissue Requests and Pause/Resume .................................................................................................. 11 Rippling Fields ........................................................................................................................................ 12 Dynamic View ......................................................................................................................................... 12 Batch Request ........................................................................................................................................ 12 Posting.................................................................................................................................................... 12 Chapter 3 Login Domain ................................................................................................................. 13 2.2.1 2.2.2 2.2.3 2.3 2.4 2.5 2.6 2.7 3.1 3.2 3.2.1 3.2.2 3.2.3 3.2.4 3.2.5 3.2.6 3.2.7 3.2.8 3.2.9 3.2.10 3.2.11 3.3 3.3.1 3.3.2 3.4 Description .................................................................................................................................................... Usage............................................................................................................................................................ Login Request Message ......................................................................................................................... Login Request Elements......................................................................................................................... Login Refresh Message.......................................................................................................................... Login Refresh Elements ......................................................................................................................... Login Status Message ............................................................................................................................ Login Status Elements............................................................................................................................ Login Update Message........................................................................................................................... Login Close Message ............................................................................................................................. Login Generic Message Use .................................................................................................................. Login Post Message ............................................................................................................................... Login Ack Message ................................................................................................................................ Data............................................................................................................................................................... Login Refresh Message Payload............................................................................................................ Login Generic Message Payload............................................................................................................ Special Semantics......................................................................................................................................... Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 13 14 14 16 19 21 26 27 27 28 28 29 29 30 30 32 33 1 3.4.1 3.4.2 3.4.3 3.4.4 3.5 3.5.1 3.5.2 Chapter 4 4.1 4.2 4.2.1 4.2.2 4.2.3 4.2.4 4.2.5 4.3 4.3.1 4.3.2 4.4 4.4.1 4.4.2 4.4.3 4.4.4 4.4.5 4.5 4.5.1 4.5.2 Chapter 5 5.1 5.2 5.3 5.3.1 5.3.2 5.3.3 5.4 5.5 5.5.1 5.5.2 5.6 5.6.1 5.6.2 5.7 5.8 5.9 5.9.1 5.9.2 5.9.3 5.10 5.11 5.11.1 5.11.2 5.11.3 5.12 Authentication and Login Handling ......................................................................................................... Negotiating msgKey.attrib Parameters ................................................................................................... Group and Service Status....................................................................................................................... Single Open and Allow Suspect Data Behavior...................................................................................... Login Sample XML........................................................................................................................................ Login Request Message Sample XML ................................................................................................... Login Refresh Message Sample XML .................................................................................................... 33 33 33 34 35 35 36 Source Directory Domain .............................................................................................. 37 Description .................................................................................................................................................... Usage............................................................................................................................................................ Source Directory Request Message ....................................................................................................... Source Directory Refresh Message........................................................................................................ Source Directory Update Message......................................................................................................... Source Directory Status Message .......................................................................................................... Source Directory Generic Message........................................................................................................ Data............................................................................................................................................................... Source Directory Refresh and Update Payload...................................................................................... Source Directory ConsumerStatus Generic Message Payload .............................................................. Special Semantics......................................................................................................................................... Multiple Streams ..................................................................................................................................... ServiceState and AcceptingRequests .................................................................................................... Service and Group Status Values........................................................................................................... Removing a Service................................................................................................................................ Non-existent Services............................................................................................................................. Source Directory Sample XML...................................................................................................................... Source Directory Request Message Sample XML ................................................................................. Source Directory Refresh Message Sample XML .................................................................................. 37 38 38 40 41 42 43 44 44 54 54 54 54 56 56 56 57 57 57 Dictionary Domain ......................................................................................................... 59 Description .................................................................................................................................................... Decoding Field List Contents with Field and Enumerated Types Dictionaries .............................................. Usage............................................................................................................................................................ Dictionary Request Message.................................................................................................................. Dictionary Refresh Message................................................................................................................... Dictionary Status Message ..................................................................................................................... Payload and Summary Data for the Refresh Message ................................................................................. Field Dictionary ............................................................................................................................................. Field Dictionary Payload ......................................................................................................................... Field Dictionary File Format.................................................................................................................... Enumerated Types Dictionary....................................................................................................................... Enumerated Types Dictionary Payload .................................................................................................. Enumerated Types Dictionary File Format ............................................................................................. Global Field Set Definition Payload............................................................................................................... Global Element Set Definition Payload ......................................................................................................... Special Semantics......................................................................................................................................... DictionaryId............................................................................................................................................. DictionariesProvided and DictionariesUsed............................................................................................ Version Information................................................................................................................................. Other Dictionary Types ................................................................................................................................. Dictionary Sample XML................................................................................................................................. Dictionary Request Message Sample XML ............................................................................................ Field Dictionary Refresh Message Sample XML .................................................................................... Enumerated Types Dictionary Refresh Message Sample XML.............................................................. Dictionary Utility Function.............................................................................................................................. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 59 59 61 61 62 63 64 65 65 66 70 70 72 75 77 78 78 78 78 79 80 80 80 82 83 2 5.12.1 5.12.2 Chapter 6 6.1 6.2 6.2.1 6.2.2 6.2.3 6.2.4 6.2.5 6.3 6.4 6.4.1 6.4.2 Example: Basic Dictionary Use............................................................................................................... 84 Example: Dictionary Lookup Using a FieldId .......................................................................................... 85 Market Price Domain...................................................................................................... 87 Description .................................................................................................................................................... Usage............................................................................................................................................................ Market Price Request Message.............................................................................................................. Market Price Refresh Message .............................................................................................................. Market Price Update Message ............................................................................................................... Market Price Status Message................................................................................................................. Market Price Post Message.................................................................................................................... Data: Market Price Refresh Message / Update Message Payload ............................................................... Market Price Sample XML ............................................................................................................................ Market Price Request Message Sample XML ........................................................................................ Market Price Refresh Message Sample XML......................................................................................... 87 87 87 89 90 92 93 94 94 94 94 Chapter 7 Market By Order Domain ............................................................................................... 96 7.1 7.2 Description .................................................................................................................................................... 96 Usage............................................................................................................................................................ 96 Market By Order Request Message ....................................................................................................... 96 Market By Order Refresh Message ........................................................................................................ 98 Market By Order Update Message ......................................................................................................... 99 Market By Order Status Message......................................................................................................... 100 Market By Order Post Message............................................................................................................ 100 Data............................................................................................................................................................. 101 Market By Order Refresh / Update Payload ......................................................................................... 101 Summary Data...................................................................................................................................... 102 RsslMapEntry Contents ........................................................................................................................ 102 Market By Order Sample XML .................................................................................................................... 102 Market By Order Request Message Sample XML................................................................................ 102 Market By Order Refresh Message Sample XML................................................................................. 103 7.2.1 7.2.2 7.2.3 7.2.4 7.2.5 7.3 7.3.1 7.3.2 7.3.3 7.4 7.4.1 7.4.2 Chapter 8 8.1 8.2 8.2.1 8.2.2 8.2.3 8.2.4 8.2.5 8.3 8.3.1 8.3.2 8.3.3 8.4 8.4.1 8.4.2 Chapter 9 9.1 9.2 9.2.1 9.2.2 9.2.3 Market By Price Domain .............................................................................................. 105 Description .................................................................................................................................................. Usage.......................................................................................................................................................... Market By Price Request Message ...................................................................................................... Market By Price Refresh Message ....................................................................................................... Market By Price Update Message ........................................................................................................ Market By Price Status Message.......................................................................................................... Market By Price Post Message............................................................................................................. Data............................................................................................................................................................. Market By Price Refresh/Update Payload ............................................................................................ Summary Data...................................................................................................................................... RsslMapEntry Contents ........................................................................................................................ Market By Price Sample XML ..................................................................................................................... Market By Price Request Message Sample XML................................................................................. Market By Price Refresh Message Sample XML.................................................................................. 105 105 105 106 108 109 109 110 110 110 110 111 111 111 Market Maker Domain .................................................................................................. 113 Description .................................................................................................................................................. Usage.......................................................................................................................................................... Market Maker Request Message.......................................................................................................... Market Maker Refresh Message........................................................................................................... Market Maker Update Message............................................................................................................ Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 113 113 113 115 116 3 9.2.4 9.2.5 9.3 9.3.1 9.3.2 9.3.3 9.4 9.4.1 9.4.2 Chapter 10 10.1 10.2 10.2.1 10.2.2 10.2.3 10.2.4 10.2.5 10.3 10.3.1 10.3.2 10.3.3 10.4 10.5 10.5.1 10.5.2 Chapter 11 11.1 11.2 11.2.1 11.2.2 11.2.3 11.2.4 11.3 11.3.1 11.3.2 11.3.3 11.4 11.4.1 11.4.2 Market Maker Status Message ............................................................................................................. Market Maker Post Message ................................................................................................................ Data............................................................................................................................................................. Market Maker Refresh/Update Payload................................................................................................ Summary Data...................................................................................................................................... RsslMapEntry Contents ........................................................................................................................ Market Maker Sample XML......................................................................................................................... Market Maker Request Message Sample XML .................................................................................... Market Maker Refresh Message Sample XML ..................................................................................... 117 117 118 118 118 118 119 119 119 Yield Curve Domain ..................................................................................................... 122 Description .................................................................................................................................................. Usage.......................................................................................................................................................... Yield Curve Request Message ............................................................................................................. Yield Curve Refresh Message .............................................................................................................. Yield Curve Update Message ............................................................................................................... Yield Curve Status Message ................................................................................................................ Yield Curve Domain Post Message ...................................................................................................... Data............................................................................................................................................................. Yield Curve Refresh/Update Payload ................................................................................................... Summary Data...................................................................................................................................... Yield Curve Input and Output Entries ................................................................................................... .................................................................................................................................................................... Yield Curve Sample XML ............................................................................................................................ Yield Curve Request Message Sample XML........................................................................................ Yield Curve Refresh Message Sample XML ........................................................................................ 122 122 122 124 125 126 126 127 127 128 128 128 129 129 129 Symbol List Domain..................................................................................................... 132 Description .................................................................................................................................................. Usage.......................................................................................................................................................... Symbol List Request Message ............................................................................................................. Symbol List Refresh Message .............................................................................................................. Symbol List Update Message ............................................................................................................... Symbol List Status Message ................................................................................................................ Data............................................................................................................................................................. Symbol List Request Payload............................................................................................................... Symbol List Data Streams .................................................................................................................... Symbol List Refresh/Update Payload ................................................................................................... Symbol List Sample XML ............................................................................................................................ Symbol List Request Message Sample XML........................................................................................ Symbol List Refresh Message Sample XML ........................................................................................ 132 132 132 134 135 136 136 136 137 138 138 138 138 Appendix A RDMUpdateEventTypes................................................................................................ 140 Appendix B Revision History ............................................................................................................ 141 Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 4 Contents List of Figures Figure 1. Figure 2. Figure 3. Figure 4. Figure 5. Figure 6. Figure 7. Figure 8. Figure 9. Figure 10. Figure 11. Figure 12. Figure 13. Figure 14. Figure 15. Figure 16. Figure 17. Figure 18. Figure 19. Figure 20. Figure 21. Figure 22. Figure 23. Figure 24. Figure 25. Figure 26. Figure 27. Figure 28. Figure 29. OMM Consumer and Interactive Provider Initial Interactions .......................................................................... 8 OMM Non-Interactive Provider Initial Interaction ............................................................................................ 9 General Domain Use..................................................................................................................................... 10 Login Refresh Message Payload .................................................................................................................. 30 Source Directory Refresh and Update Message Payload............................................................................. 44 RsslFieldList Referencing Field Dictionary............................................................................................ 60 RsslFieldEntry Referencing an Enumerated Types Table ..................................................................... 61 Field Dictionary Payload ............................................................................................................................... 65 Field Dictionary File Format Sample ............................................................................................................. 67 Field Dictionary Tagged Attributes Sample ................................................................................................... 67 Enumerated Types Dictionary Refresh Message Payload............................................................................ 71 Global Field Set Definition Payload............................................................................................................... 75 Global Element Set Definition Payload ......................................................................................................... 78 Enumerated Type Dictionary Refresh Message Sample XML Message Layout .......................................... 83 Market Price Request Message Sample XML Message Layout ................................................................... 94 Market Price Refresh Message Sample XML Message Layout .................................................................... 94 .................................................................................................................................................................... 101 Market By Order Request Message Sample XML Message Layout ........................................................... 102 Market By Order Refresh Message Sample XML Message Layout............................................................ 104 Market By Price Request Message Sample XML Message Layout ............................................................ 111 Market By Price Refresh Message Sample XML Message Layout............................................................. 112 .................................................................................................................................................................... 118 Market Maker Request Message Sample XML Message Layout ............................................................... 119 Market Maker Refresh Message Sample XML Message Layout ................................................................ 121 Yield Curve Payload Example..................................................................................................................... 127 Yield Curve Request Message Sample XML Message Layout................................................................... 129 Yield Curve Refresh Message Sample XML Message Layout ................................................................... 131 Symbol List Request Message Sample XML Message Layout................................................................... 138 Symbol List Refresh Message Sample XML Message Layout ................................................................... 139 Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 1 Contents List of Tables Table 1: Table 2: Table 3: Table 4: Table 5: Table 6: Table 7: Table 8: Table 9: Table 10: Table 11: Table 12: Table 13: Table 14: Table 15: Table 16: Table 17: Table 18: Table 19: Table 20: Table 21: Table 22: Table 23: Table 24: Table 25: Table 26: Table 27: Table 28: Table 29: Table 30: Table 31: Table 32: Table 33: Table 34: Table 35: Table 36: Table 37: Table 38: Table 39: Table 40: Table 41: Table 42: Table 43: Table 44: Table 45: Table 46: Table 47: Table 48: Table 49: Table 50: Table 51: Acronyms and Abbreviations .......................................................................................................................... 4 Reuters Domain Model Overview ................................................................................................................... 5 Login Request Message Member Use .......................................................................................................... 14 Login Request msgKey.attrib Elements.................................................................................................. 16 Login Refresh Message Member Use........................................................................................................... 19 Login Refresh msgKey.attrib Elements................................................................................................... 21 Login Status Message Member Use ............................................................................................................. 26 Login Status msgKey.attrib Elements ..................................................................................................... 27 Login Close Message Member Use .............................................................................................................. 28 Login Generic Message Member Use........................................................................................................... 28 Login Refresh.Payload Vector.SummaryData’s ElementList Contents .............................................. 31 Login Refresh.Payload VectorEntry’s ElementList Contents .................................................................. 31 GenericMsg.Payload RsslMap's MapEntry Information ........................................................................ 32 Login GenericMsg.Payload MapEntry Elements ................................................................................... 32 SingleOpen and AllowSuspectData Handling ............................................................................................... 34 Source Directory Request Message Member Use ........................................................................................ 38 Source Directory Refresh Message Member Use......................................................................................... 40 Source Directory Update Message Member Use.......................................................................................... 41 Source Directory Status Message Member Use ........................................................................................... 42 Source Directory Generic Message Member Use......................................................................................... 43 Source Directory RsslMap Contents............................................................................................................ 44 Source Directory RsslMapEntry Filter Entries ........................................................................................... 45 Source Directory Info Filter Entry Elements .................................................................................................. 46 Source Directory State RsslFilterEntry Elements ................................................................................ 49 Source Directory Group RsslFilterEntry Elements ............................................................................... 50 Source Directory Load RsslFilterEntry Elements ................................................................................. 51 Source Directory Data RsslFilterEntry Elements ................................................................................. 51 Source Directory Link RsslFilterEntry Map Contents ........................................................................... 52 Source Directory Sequenced Multicast RsslFilterEntry Map Contents ................................................ 53 Source Directory Sequenced Multicast RsslFilterEntry Vector Contents............................................. 53 Source Directory RsslGenericMsg RsslMapEntry .................................... 54 Source Directory Generic Message RsslMapEntry Elements ................................................................... 54 ServiceState and AcceptingRequests........................................................................................................... 55 Dictionary Request Message Member Use................................................................................................... 61 Dictionary Request Message Member Use................................................................................................... 62 Dictionary Status Message Member Use ...................................................................................................... 63 Dictionary summaryData......................................................... 64 Field Dictionary Element Entries ................................................................................................................... 66 Field Dictionary File Tag Information ............................................................................................................ 67 Field Dictionary File Column Names and RsslElementEntry Names...................................................... 68 Field Dictionary Type Keywords and Their Data Types ................................................................................ 68 Marketfeed to RWF Mappings in RDMFieldDictionary.................................................................................. 69 Element Entries Describing Each Enumerated Type Table .......................................................................... 72 Enumerated Type Dictionary File Tag Information........................................................................................ 74 RWF EnumType Dictionary File Format Reference Fields ........................................................................... 74 RWF EnumType Dictionary File Values ........................................................................................................ 74 Set Definition Enumerations.......................................................................................................................... 76 Other Dictionary Types ................................................................................................................................. 80 Dictionary Helper Functions .......................................................................................................................... 83 Market Price Request Message Member Use .............................................................................................. 87 Market Price Refresh Message Member Use ............................................................................................... 89 Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 1 Table 52: Table 53: Table 54: Table 55: Table 56: Table 57: Table 58: Table 59: Table 60: Table 61: Table 62: Table 63: Table 64: Table 65: Table 66: Table 67: Table 68: Table 69: Table 70: Table 71: Table 72: Table 73: Table 74: Table 75: Table 76: Table 77: Table 78: Table 79: Table 80: Table 1: Table 2: Market Price Update Message Member Use ................................................................................................ 90 Market Price Update Message Member Use ................................................................................................ 92 Market By Order Request Message Member Use ........................................................................................ 96 Market By Order Refresh Message Member Use ......................................................................................... 98 Market By Order Update Message Member Use .......................................................................................... 99 Market By Order Status Message Member Use ......................................................................................... 100 Market By Order Map.................................................................................................................................. 101 Market By Price Request Message Member Use ....................................................................................... 105 Market By Price Refresh Message Member Use ........................................................................................ 106 Market By Price Update Message Member Use ......................................................................................... 108 Market By Price Status Message Member Use .......................................................................................... 109 Market By Price Map ................................................................................................................................... 110 Market Maker Request Message Member Use........................................................................................... 113 Market Maker Refresh Message Member Use ........................................................................................... 115 Market Maker Update Message Member Use ............................................................................................ 116 Market Maker Status Message Member Use .............................................................................................. 117 Market Maker Map ...................................................................................................................................... 118 Yield Curve Request Message Member Use .............................................................................................. 122 Yield Curve Refresh Message Member Use ............................................................................................... 124 Yield Curve Update Message Member Use ................................................................................................ 125 Yield Curve Status Message Member Use ................................................................................................. 126 Yield Curve Inputs and Outputs .................................................................................................................. 128 Symbol List Request Message Member Use .............................................................................................. 132 Symbol List Refresh Message Member Use ............................................................................................... 134 Symbol List Update Message Member Use ................................................................................................ 135 Symbol List Status Message Member Use ................................................................................................. 136 Symbol List Behaviors Element .................................................................................................................. 136 Symbol List Behaviors Element .................................................................................................................. 137 Symbol List Refresh/Update Map ............................................................................................................... 138 RDMUpdateEventTypes ............................................................................................................................. 140 Document Revision History ......................................................................................................................... 141 Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 2 Chapter 1 Introduction Chapter 1 Introduction 1.1 About this Manual This manual describes how the Reuters Domain Models (RDM) are defined in terms of the Open Message Model (OMM). Data conforming to RDM is available via Thomson Reuters Enterprise Platform (TREP), EleKtron, and Reuters Data Feed Direct (RDFD) using the Transport API. 1.2 Audience This guide is written for software developers who are familiar with the Transport API and want to develop Transport API-based applications to access RDM-formatted data. Before reading this manual: • • Users should be familiar with OMM concepts and types. It may be useful to read the Transport API C Edition Developers Guide and be familiar with the example applications provided in the Transport API package. 1.3 Open Message Model (OMM) The OMM is a collection of message header and data constructs. Some OMM message header constructs, such as the Update message, have implicit market logic associated with them while others, such as the Generic message, allow for freeflowing bi-directional messaging. OMM data constructs can be combined in various ways to model data that ranges from simple (or flat) primitive types to complex multiple-level hierarchal data. The layout and interpretation of any specific OMM model, also referred to as a domain model, is described within that model’s definition and is not coupled with the API. The OMM is the flexible tool that simply provides the building blocks to design and produce domain models to meet the needs of the system and its users. The Transport API provides structural representations of the OMM constructs and manages the RWF binary-encoded representation of the OMM. Transport API users can leverage the provided OMM constructs to consume or provide OMM data throughout their TREP. 1.4 Reuters Wire Format (RWF) Reuters Wire Format (RWF) is the encoded representation of OMM. RWF is a highly-optimized, binary format designed to reduce the cost of data distribution as compared to previous wire formats. Binary encoding represents data in the machine’s native manner, enabling further use in calculations or data manipulations. RWF allows for serializing OMM message and data constructs in an efficient manner while still allowing rich content types. RWF can distribute field identifier-value pair data, selfdescribing data, as well as more complex, nested hierarchal content. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 1 Chapter 1 1.5 Introduction References For additional Transport API documentation, refer to: • • The Transport API C Edition Developers Guide The Thomson Reuters Professional Developer Community 1.6 Documentation Feedback While we make every effort to ensure the documentation is accurate and up-to-date, if you notice any errors, or would like to see more details on a particular topic, you have the following options: • • Send us your comments via email at apidocumentation@thomsonreuters.com. Mark up the PDF using the Comment feature in Adobe Reader. After adding your comments, you can submit the entire PDF to Thomson Reuters by clicking Send File in the File menu. Use the apidocumentation@thomsonreuters.com address. 1.7 Conventions 1.7.1 Typographic The Transport API uses the following typographical conventions: • The Reuters Domain Models (RDMs) are described in terms of OMM concepts. Images and XML example layouts are provided as a reference in relevant sections. • In-line structures, functions, and types are shown in orange, Lucida Console font. • Parameters, filenames, and directories are shown in Bold font. • Document titles and variable values are shown in italics. • When included in the body of the text, new concepts are called out in Bold, Italics the first time they are mentioned. • Verbose code examples (one or more lines of code) are shown in Lucida Console font against an orange background. Comments in such code samples are formatted in green coloring. For example: /* decode contents into the filter list structure */ if ((retVal = rsslDecodeFilterList(&decIter, &filterList)) >= RSSL_RET_SUCCESS) { /* create single filter entry and reuse while decoding each entry */ RsslFilterEntry filterEntry = RSSL_INIT_FILTER_ENTRY; Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 2 Chapter 1 1.7.2 Introduction General Transport API Syntax The Transport API uses the following general API syntax conventions: • Dot-separated notation indicates data available within a hierarchy. Each period can indicate a structure (e.g., RsslRefreshMsg.msgKey), a data member (e.g., msgKey.name), an entry (e.g., RsslRefreshMsg.Payload.DirectoryInfo, where DirectoryInfo refers to the DirectoryInfo filter entry), or an element name (e.g., RsslUpdateMsg.Payload.DirectoryInfo.name where name refers to the name element). • streamId values are assigned by the application and used across all domain models. Consumer applications assign positive streamId values when requesting content and interactive provider applications respond using the same streamId. Non-interactive provider applications assign negative streamId values. • Payload generically refers to the message payload. On any RsslMsg, the payload is housed in the encDataBody buffer and follows the formatting rules of that message’s containerType. • Integer constants are defined in all capital letters with underscores (e.g., RSSL_DMT_MARKET_PRICE, RDM_DIRECTORY_SERVICE_INFO_ID). In the Transport API, they can be found in the rsslRDM.h header. • The names of Transport API filterId values (e.g. RDM_DIRECTORY_SERVICE_INFO_ID) correspond to the flag value enumeration defined for use with the message key’s filter (e.g., RDM_DIRECTORY_SERVICE_INFO_FILTER). Names may be shortened for clarity (e.g., ServiceInfo). • 1.7.3 Definitions and Standard Behaviors This Transport API manual uses the following terms and the API illustrates the following default behavior: • Not Used means the attribute is not extensible; the Transport API may pass-on the information, however there is no guarantee that the data will be passed through the network now or in the future. Use of a “Not Used” attribute may cause problems when interacting with some components. • Required means the data must be provided or set. • Conditional means date might be required depending on a particular scenario or context. Refer to the description for specific details. • Optional means the data may be provided or set, but is not required. This data should be handled and understood by all applications, even if not including it. When present, this information should be passed through the network. • If data is not present, the Transport API assumes the default value. • Generic message use is not supported within existing, defined Reuters Domain Models, except when explicitly defined. • Posting is assumed to be supported within currently-defined Reuters Domain Models, except when otherwise indicated. Posting is not supported on Source Directory and Dictionary domains. Posting within the Login domain must follow off-stream posting rules and target a domain other than Login. Posting on any other allowed domains must follow on-stream posting rules and target that specific domain. For further details about posting, refer to the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 3 Chapter 1 1.8 Introduction Acronyms and Abbreviations ACRONYM DEFINITION AAAAPI Authorization, Authentication, and Administration API ADH Advanced Data Hub ADS Advanced Distribution Server API Application Programming Interface ASCII American Standard Code for Information Interchange ATS Advanced Transformation Server DACS Data Access Control System DMM Domain Message Model EED Elektron Edge Device EMA Elektron Message API ETA Elektron Transport API OMM Open Message Model QoS Quality of Service RDM Reuters Domain Model RMTES Reuters Multi-Lingual Text Encoding Standard RSSL Reuters Source Sink Library RWF Reuters Wire Format TRDFD Thomson Reuters Datafeed Direct TREP Thomson Reuters Enterprise Platform Table 1: Acronyms and Abbreviations 1.9 What’s New This release of the RDM Usage Manual includes general documentation changes. Appendix B maintains a versioned list of changes to this document. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 4 Chapter 2 Domain Model Overview Chapter 2 Domain Model Overview 2.1 What is a Domain Message Model? A Domain Message Model (DMM) describes a specific arrangement of OMM message and data constructs. A domain message model will define any specialized behaviors associated with the domain or any specific meaning or semantics associated with data contained in the message. Unless a domain model specifies otherwise, any implicit market logic associated with a message still applies (e.g. an Update message indicates that any previously-received data also contained in the Update message is being modified). 2.2 Reuters Domain Models (RDMs) Vs User-Defined Models 2.2.1 Reuters Domain Models (RDMs) An RDM is a domain message model typically provided or consumed by a Thomson Reuters product, such as the TREP, Data Feed Direct, or Elektron. Some currently-defined RDMs allow for authenticating to a provider (e.g. Login), exchanging field or enumeration dictionaries (e.g. Dictionary), and providing or consuming various types of market data (e.g. Market Price, Market by Order, Market by Price). Thomson Reuters’s defined models have a domain value of less than 128. The following table provides a high-level overview of the currently-available RDMs. The following chapters provide more detailed descriptions for each of these. DOMAIN PURPOSE Login Authenticates users and advertise/request features that are not specific to a particular domain. Use of and support for this domain is required for all OMM applications. This is considered an administrative domain, content is required and expected by many Thomson Reuters components and conformance to the domain model definition is expected. For further details refer to Chapter 3, Login Domain. Source Directory Advertises information about available services and their state, QoS, and capabilities. This domain also conveys any group status and group merge information. Interactive and Non-Interactive OMM provider applications require support for this domain. Thomson Reuters strongly recommends that OMM Consumers request this domain. This is considered an administrative domain, and many Thomson Reuters components expect and require content to conform to the domain model definition. For further details, refer to Chapter 4, Source Directory Domain. Dictionary Provides dictionaries that may be needed when decoding data. Though use of the Dictionary domain is optional, Thomson Reuters recommends that provider applications support the domain’s use. Considered an administrative domain, content is required and expected by many Thomson Reuters components and following the domain model definition is expected. For further details refer to Chapter 5, Dictionary Domain. Table 2: Reuters Domain Model Overview Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 5 Chapter 2 Domain Model Overview DOMAIN PURPOSE Market Price Provides access to Level I market information such as trades, indicative quotes and top of book quotes. Content includes information such as volume, bid, ask, net change, last price, high, and low. For further details refer to Chapter 6, Market Price Domain. Market By Order Provides access to Level II full order books. Contains a list of orders (keyed by the order IDs) with related information such as price, whether it is a bid/ask order, size, quote time, and market maker identifier. For further details refer to Chapter 7, Market By Order Domain. Market By Price Provides access to Level II market depth information. Contains a list of price points (keyed by that price and the bid/ask side) with related information. For further details refer to Chapter 8, Market By Price Domain. Market Maker Provides access to market maker quotes and trade information. Contains a list of market makers (keyed by that market maker’s ID) with related information such as that market maker’s bid and asking prices, quote time, and market source. For further details refer to Chapter 9, Market Maker Domain. Yield Curve Provides access to yield curve information. This can contain input information used to calculate a yield curve along with output information (which is the curve itself). A yield curve shows the relation between the interest rate and the term associated with the debt of a borrower. The curve’s shape can help to give an idea of future economic activity and interest rates. For further details refer to Chapter 10, Yield Curve Domain. Symbol List Provides access to a set of symbol names, typically from an index, service, or cache. Minimally contains symbol names and can optionally contain additional cross-reference information such as permission information, name type, or other venue-specific content. For further details refer to Chapter 11, Symbol List Domain. Table 2: Reuters Domain Model Overview (Continued) 2.2.2 User-Defined Domain Model A User Defined Domain Model is a domain message model defined by a party other than Thomson Reuters. These may be defined to solve a specific user or system need in a particular deployment which is not resolvable through the use of an RDM. Any user-defined model must use a domain value between 128 and 255. If needed, domain model designers can work with Thomson Reuters to define their models as standard RDMs. This allows for the most seamless interoperability with future RDM definitions and with other Thomson Reuters products. 2.2.3 Domain Message Model Creation This document discusses defined RDMs capable of flowing through the Transport API. Transport API users can leverage OMM to create their own Domain Message Models (DMMs) in addition to those described in this document. When defining a DMM, consider the following questions / points: • • Is a new DMM really needed, or can you express the data in terms of an existing RDM? The DMM should be well-defined. Following the design templates used in this document is a good approach. The structure, properties, use cases, and limitations of the DMM should be specified. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 6 Chapter 2 Domain Model Overview • While OMM provides building blocks that can structure data in many ways, the semantics of said data must abide by the rules of OMM. For example, custom DMMs should follow the request, refresh, status, and update semantics implicitly defined by those messages. If more flexible messaging is desired within a custom DMM, it can be accomplished through the use of a generic message, which allows for more free-form bidirectional messaging after a stream is established. • domainType values less than 128 are reserved for RDMs. The domainType of a custom DMM must be between 128 and 255. • You might want to work with Thomson Reuters to define a published RDM, rather than use a custom DMM. This ensures the most seamless interoperability with future RDMs and other Thomson Reuters products. 2.3 Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 7 Chapter 2 2.4 Domain Model Overview OMM Consumer / OMM Interactive Provider Initial Interaction An OMM consumer application can establish connections to other OMM interactive provider applications, including TREP, Data Feed Direct, and Elektron. This interaction first requires an exchange of login messages between the consumer and provider, where the provider can either accept or reject the consumer. If the consumer is allowed to log in, it may then request the list of services available from the provider. Optionally1, the consumer can request any dictionaries it needs to decode data from the provider. After this process successfully completes, the consumer application can begin requesting from nonadministrative domains, which provide other content (e.g. Market Price, Market By Order). Figure 1. OMM Consumer and Interactive Provider Initial Interactions 1. Instead of downloading any needed dictionaries, the application can load them from a local file. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 8 Chapter 2 2.5 Domain Model Overview OMM Non-Interactive Provider Initial Interaction An OMM non-interactive provider application can establish a connection to an Advanced Data Hub (ADH). After successfully connecting, an OMM non-interactive provider can publish information into the ADH’s cache, without needing to handle requests for the information. This interaction first requires a login message exchange between the non-interactive provider and the ADH, where the ADH can either accept or reject the non-interactive provider. If the non-interactive provider logs in, it should push out its service information. After this process successfully completes, the non-interactive provider application can begin publishing content on other non-administrative domains (e.g. Market Price, Market By Order). Figure 2. OMM Non-Interactive Provider Initial Interaction Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 9 Chapter 2 2.6 Domain Model Overview Sending and Receiving Content Use of non-administrative domains generally follows a specific sequence: • • The consumer sends an RsslRequestMsg containing the name of an item it is interested in. • • As data changes, the provider sends RsslUpdateMsg (if the consumer requested streaming information). The provider first responds with an RsslRefreshMsg to bring the consumer up to date with all currently available information. When the consumer is no longer interested, it sends an RsslCloseMsg to close the stream (or, if the provider needs to close the stream, it uses an RsslStatusMsg). Figure 3. General Domain Use Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 10 Chapter 2 2.7 Domain Model Overview General Transport API Concepts Many domains share a set of common behaviors for handling data. If a specific behavior is not supported on a domain, this should be specified in that domains detailed description. This section briefly defines these concepts; the Transport API C Edition Developers Guide describes them in greater detail. 2.7.1 Snapshot and Streaming Requests Many domains generally support issuing a request message with or without setting the RSSL_RQMF_STREAMING flag. When the flag is set, the request is known as a “streaming” request, meaning that the refresh will be followed by updates. When a snapshot request is made, the refresh should have a streamState of RSSL_STREAM_NON_STREAMING. When the final part of the refresh is received, the stream is considered closed (the final refresh is indicated by the RSSL_RFMF_REFRESH_COMPLETE flag on the RsslRefreshMsg). The consumer should be prepared to receive status messages or update messages between the first and final parts of the refresh (if the domain supplies only single part refresh messages, like Market Price, no updates would be delivered on the stream). A provider may also set the streamState to RSSL_STREAM_NON_STREAMING if it does not allow streaming of the requested item. 2.7.2 Multi-Part Messages Many domains support splitting the content of a large RsslRefreshMsg into multiple, smaller refresh messages. Each part is a continuation of data from the previous parts, and the final part is denoted by including the RSSL_RFMF_REFRESH_COMPLETE flag. When possible, the provider should indicate the expected number of total container entries across all parts of the refresh. This is set using the totalCountHint parameter available on some containers (such as RsslMap). Though the Transport API Transport Package can fragment large messages on the users behalf, Thomson Reuters recommends that the application fragment large messages whenever possible. The application knows best how data should be split, and this allows consuming applications to receive and process parts of the message without needing to wait for all parts to be delivered. In addition to RsslRefreshMsg, RsslPostMsg and RsslGenericMsg also have multi-part support. For more information, see the Transport API C Edition Developers Guide. 2.7.3 Reissue Requests and Pause/Resume A consumer application can request a new refresh and change certain parameters on an already requested stream. To do so, the application sends a subsequent RsslRequestMsg on the same stream. This is known as a reissue. A reissue changes the priority of a stream and pauses or resumes data flow. • To pause streaming data, the application can send a reissue with the RSSL_RQMF_PAUSE flag. Issuing a pause on the Login stream is interpreted as a Pause All request, resulting in all streams being paused. • To resume data flow on the stream, the application can send a subsequent reissue with the RSSL_RQMF_STREAMING flag. Issuing a resume on the Login stream is interpreted as a Resume All. Pause and Resume is provided as a best effort, and data may continue streaming even after a pause has been issued. For further details on reissue requests, changeable parameters, and Pause and Resume functionality, refer to the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 11 Chapter 2 2.7.4 Domain Model Overview Rippling Fields The RsslFieldList container supports the rippling of fields. When rippling, newly received content associated with a fieldId replaces previously received content associated with the same fieldId. The previously received content is moved to a new fieldId, which is typically indicated in a field dictionary. In the RDMFieldDictionary, the ‘RIPPLES TO’ column defines fieldId information used when rippling (for details, refer to Section 5.5.1 and Section 5.5.2). Rippling typically reduces bandwidth consumption. Because previously received information is still relevant, it would normally need to be sent with subsequent updates even though the value does not change. The use of rippling allows this information to be optimized out of subsequent updates; however it relies on the consumer to use ripple information from a field dictionary to correctly propagate the previously received content. Note: The consumer application is responsible for rippling and the Transport API does not perform entry rippling. Warning! The application should not perform rippling if the updateType of the RsslUpdateMsg is RDM_UPD_EVENT_TYPE_CORRECTION. 2.7.5 Dynamic View A dynamic view allows a consumer application to specify a subset of data content in which it is interested. A providing application can choose to supply only this requested subset of content across all response messages. This filtering results in reduced data flow across the connection. View use can be leveraged across all non-administrative domain model types, where specific usage and support should be indicated in the model definition. The provider indicates its support for view requesting via the supportViewRequests Login attribute, as described in Section 3.3.1. For more information on dynamic views, refer to the Transport API C Edition Developers Guide. 2.7.6 Batch Request A batch request allows a consumer application to indicate interest in multiple like-item streams with a single RsslRequestMsg. A providing application should respond by providing a status on the batch request stream itself and with new individual item streams for each item requested in the batch. Batch requesting can be leveraged across all non-administrative domain model types. The provider indicates its support for batch requests via the supportBatchRequests Login attribute, as described in Section 3.3.1. For more information on batch requests, refer to the Transport API C Edition Developers Guide. 2.7.7 Posting Posting offers an easy way for an OMM consumer application to publish content to upstream components which can then provide the information. This can be done off-stream using the Login domain or on-stream using any other non-administrative domain. Use RsslPostMsg to post content to the system. An RsslPostMsg can contain any OMM container type as its payload (but this is often an RsslMsg). A provider indicates support for posting via the supportOMMPost Login attribute, as described in Section 3.3.1. For more information on posting, refer to the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 12 Chapter 3 Login Domain Chapter 3 Login Domain 3.1 Description The Login domain registers a user with the system, after which the user can request1, post2, or provide3 RDM content. A Login request can also be used to authenticate a user with the system. • • A consumer application must log into the system before it can request or post content. A non-interactive provider application must log into the system before providing any content. An interactive provider application is required to handle log in requests and provide Login response messages, possibly using DACS to authenticate users. For further details: • • • • Section 3.2 details the use of each message within the Login domain. Section 3.3 presents the message payloads. Section 3.4 includes a brief summary of login handling and authentication. Section 3.5 includes example layouts of login messages. 1. Consumer applications can request content after logging into the system. 2. Consumer applications can post content, which is similar to contribution or unmanaged publication, after logging into the system. 3. Non-interactive provider applications. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 13 Chapter 3 3.2 Usage 3.2.1 Login Request Message Login Domain A Login request message is encoded and sent by OMM consumer and OMM non-interactive provider applications. This message registers a user with the system. After receiving a successful login response, applications can then begin consuming or providing additional content. An OMM provider can use the Login request information to authenticate users with DACS. An initial Login request must be streaming (i.e., a RSSL_RQMF_STREAMING flag is required). After the initial Login stream is established, subsequent Login requests using the same streamId can be sent to obtain additional refresh messages, pause the stream, or resume the stream. If a login stream is paused, this is interpreted as a ‘Pause All’ request which indicates that all item streams associated with the user should be paused. A login stream is paused by specifying RSSL_RQMF_PAUSE without the streaming flag. To resume data flow on all item streams (also known as a Resume All), the streaming flag must be sent again. For more information, refer to the Transport API C Edition Developers Guide. For an example layout of this message, refer to Section 3.4.4. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_LOGIN == 1 qos Not used. worstQos Not used. priorityClass Not used. priorityCount Not used. extendedHeader Not used. msgKey.serviceId Not used. Table 3: Login Request Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 14 Chapter 3 Login Domain COMPONENT DESCRIPTION / VALUE msgKey.nameType Optional, if present msgKey.flags value of RSSL_MKF_HAS_NAME_TYPE should be specified. Possible values are: • RDM_LOGIN_USER_NAME == 1 • RDM_LOGIN_USER_EMAIL_ADDRESS == 2 • RDM_LOGIN_USER_TOKEN == 3 • RDM_LOGIN_USER_COOKIE == 4 • RDM_LOGIN_USER_AUTHN_TOKEN == 5 If msgKey.nameType is not set, it is assumed to be RDM_LOGIN_USER_NAME. A type of RDM_LOGIN_USER_NAME typically corresponds to a DACS user name. This can be used to authenticate and permission a user. RDM_LOGIN_USER_TOKEN is specified when using the AAA API The user token is retrieved from a AAA API gateway and then passed through the system via the msgKey.name. To validate users, a provider can pass this user token to an authentication manager application. If you specify RDM_LOGIN_USER_AUTHN_TOKEN, you must also set msgKey.name to a single, null character (i.e., a 0x00 binary), and include an AuthenticationToken element in the msgKey.attrib. For details on the AuthenticationToken, refer to Section 3.2.2. Both RDM_LOGIN_USER_TOKEN and RDM_LOGIN_USER_AUTHN_TOKEN can periodically change: when it changes, an application can send a login reissue to pass information upstream. • For further details on using RDM_LOGIN_USER_TOKEN, refer to the AAA API documentation. • For further details on using RDM_LOGIN_USER_AUTHN_TOKEN, refer to the TREP Authentication User Manual.a msgKey.name Required. A msgKey.flags value of RSSL_MKF_HAS_NAME_TYPE should be specified. msgKey.name should be populated with appropriate content corresponding to the msgKey.nameType specification. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Optional. If present, a msgKey.flags value of RSSL_MKF_HAS_ATTRIB should be specified and msgKey.attribContainerType should be set to RSSL_DT_ELEMENT_LIST. Attributes are specified in Section 3.2.2. Payload Not used. Table 3: Login Request Message Member Use (Continued) a. For further details on TREP Authentication, refer to the TREP Authentication User Manual, accessible on Thomson Reuters MyAccount in the DACS product documentation set. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 15 Chapter 3 3.2.2 Login Domain Login Request Elements You can use the Login msgKey.attrib elements to send additional authentication information and user preferences between components. The ReqMsg.Attrib attribContainerType is an RsslElementList (RSSL_DT_ELEMENT_LIST). The predefined elements available on a Login Request are shown in the following table. ELEMENT NAME DATA TYPE ENUMERATION RANGE/ EXAMPLE DESCRIPTION AllowSuspectData RSSL_DT_UINT 0|1 • ApplicationAuthorizationToken RSSL_DT_ASCII_STRING Encrypted Indicates that application behaviors was application inspected and approved by Thomson Reuters. authorization token Encrypt this token using the provided methods in the API to prevent other users or applications from compromising it. For more information on obtaining an application authorization token, contact your Thomson Reuters representative. ApplicationId RSSL_DT_ASCII_STRING 1 - 65535 e.g., 256 The DACS application ID. If the server authenticates with DACS, the consumer application might need to pass in a valid ApplicationId. This must be unique for each application. IDs from 1 to 256 are reserved for permanent market data applications. These are assigned by Thomson Reuters and will be uniform across all client systems. IDs from 257 to 65535 are available for site-specific use. ApplicationName RSSL_DT_ASCII_STRING Name of application e.g., Transport API Identifies the application sending the Login request or response message. When present, the application name in the Login request identifies the OMM consumer, and the application name in the Login response identifies the OMM provider. AuthenticationExtended RSSL_DT_BUFFER Any binary buffer This is a binary buffer whose content will be passed to the token authenticator as an additional means for verifying a user’s identity. AuthenticationToken RSSL_DT_ASCII_STRING Any ASCII String, e.g., HOLDER Conditional. AuthenticationToken is a client-generated token that identifies the user when operating in an environment that uses TREP Authenticationa. On login reissue messages, this field contains a new token intended to replace the previous one about to expire. If your TREP system has TREP Authentication enabled, AuthenticationToken is included in the message. The default setting is: "" (an empty string) DisableDataConversion N/A Reserved by TR. N/A 1: Indicates that the consumer application allows for suspect streamState information • 0: Indicates that the consumer application prefers any suspect data result in the stream being closed with an RSSL_STREAM_CLOSED_RECOVER state. For more information, refer to Section 3.4.4. Table 4: Login Request msgKey.attrib Elements Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 16 Chapter 3 Login Domain ELEMENT NAME DATA TYPE ENUMERATION RANGE/ EXAMPLE DownloadConnectionConfig RSSL_DT_UINT 0|1 InstanceId RSSL_DT_ASCII_STRING Any ASCII String, e.g., Instance1 InstanceId is used to differentiate applications that run on the same machine. However, because InstanceId is set by the user logging into the system, it does not guarantee uniqueness across different applications on the same machine. Password RSSL_DT_ASCII_STRING my_password Sets the password for logging into the system. See specific component documentation to determine password requirements and how to obtain one. Position RSSL_DT_ASCII_STRING ip addr/net e.g., 192.168.1.1/ net DACS position. If the server is authenticating with DACS, the consumer application might need to pass in a valid position. ProvidePermissionExpressions RSSL_DT_UINT 0|1 If specified on the Login Request, this indicates a consumer wants permission expression information to be sent with responses. Permission expressions allow for items to be proxy permissioned by a consumer via content-based entitlements. ProvidePermissionExpressions defaults to 1. ProvidePermissionProfile RSSL_DT_UINT 0|1 When specified on a Login Request, indicates that a consumer desires the permission profile. An application can use the permission profile to perform proxy permissioning. ProvidePermissionProfile defaults to 1. Role RSSL_DT_UINT RDM_LOGIN_ROL Indicates the role of the application logging onto E_CONS == 0, the system. RDM_LOGIN_ROL • An OMM consumer application should specify E_PROV == 1 its role as RDM_LOGIN_ROLE_CONS. • An OMM non-interactive provider application should specify its role as RDM_LOGIN_ROLE_PROV. OMM consumer applications typically connect to a different port number than non-interactive provider applications. Role information allows TREP to detect and inform users of incorrect port use. Role defaults to 0. DESCRIPTION Specifies whether to download the configuration: • 1: Indicates the user wants to download connection configuration information. • 0 (or if absent): Indicates that no connection configuration information is desired. 0 is the default setting. Table 4: Login Request msgKey.attrib Elements (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 17 Chapter 3 Login Domain ELEMENT NAME DATA TYPE ENUMERATION RANGE/ EXAMPLE DESCRIPTION SingleOpen RSSL_DT_UINT 0|1 • SupportProviderDictionaryDownload RSSL_DT_UINT 0|1 Indicates whether the server supports the Provider Dictionary Download feature: • 1: The server supports provider dictionary downloads. • 0: The server does not support provider dictionary downloads. If this element is missing, the server does not support provider dictionary downloads. For more information on the provider dictionary download feature, refer to the Transport API C Edition Developers Guide. SupportProviderDictionaryDownload defaults to 0. 1: Indicates the consumer application wants the provider to drive stream recovery. • 0: Indicates that the consumer application will drive stream recovery. For more information, refer to Section 3.4.4. SingleOpen defaults to 1. Table 4: Login Request msgKey.attrib Elements (Continued) a. For further details on TREP Authentication, refer to the TREP Authentication User Manual, accessible on Thomson Reuters MyAccount in the DACS product documentation set. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 18 Chapter 3 3.2.3 Login Domain Login Refresh Message A Login refresh message is encoded and sent by OMM interactive provider applications. This message is used to respond to a Login Request message after the user’s Login is accepted. An OMM provider can use the Login request information to authenticate users with DACS. After authentication, a refresh message is sent to convey that the login was accepted. If the login is rejected, a Login status message should be sent as described in Section 3.2.5. The content of a Login Refresh message is expected to be atomic and contained in a single part, therefore RSSL_RFMF_REFRESH_COMPLETE should be set to true. If the login refresh is sent in response to a request, the RSSL_RFMF_SOLICITED flag should be set to true to indicate that this is a solicited response. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_REFRESH == 2 domainType Required. RSSL_DMT_LOGIN == 1 state When accepting Login: qos seqNum • streamState = RSSL_STREAM_OPEN • dataState = RSSL_DATA_OK • stateCode = RSSL_SC_NONE Not used. Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. groupId Not used. permData Not used. extendedHeader Not used. msgKey.serviceId Not used. msgKey.nameType Optional. If present, a msgKey.flags value of RSSL_MKF_HAS_NAME_TYPE should be specified. Possible values: • RDM_LOGIN_USER_NAME == 1 • RDM_LOGIN_USER_EMAIL_ADDRESS == 2 • RDM_LOGIN_USER_TOKEN == 3 • RDM_LOGIN_USER_COOKIE == 4 • RDM_LOGIN_USER_AUTHN_TOKEN == 5 If nameType is not set then it is assumed to be a nameType of RDM_LOGIN_USER_NAME. If present, the value should match the type specified in the Login request. msgKey.name Optional. A msgKey.flags value of RSSL_MKF_HAS_NAME should be specified, and name should match the name specified in the Login request and contain appropriate content corresponding to the nameType specification. msgKey.filter Not used. Table 5: Login Refresh Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 19 Chapter 3 COMPONENT DESCRIPTION / VALUE msgKey.identifier Not used. msgKey.attrib Optional. Login Domain If present msgKey.flags value of RSSL_MKF_HAS_ATTRIB should be specified and msgKey.attribContainerType should be RSSL_DT_ELEMENT_LIST. Elements are specified in Section 3.2.4. Payload Optional. Typically present when login requests connection configuration or permission profile information. The payload is sent as an RsslElementList. For payload details, refer to Section 3.3.1. Table 5: Login Refresh Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 20 Chapter 3 3.2.4 Login Domain Login Refresh Elements The Login msgKey.attrib can be used to send additional authentication information and user preferences between components. The attribContainerType is an RsslElementList, which can contain any of the following predefined elements (none of which are required): ELEMENT NAME DATA TYPE ENUMERATION RANGE/EXAMPLE DESCRIPTION AllowSuspectData RSSL_DT_UINT 0|1 Sets whether the provider application passes along suspect streamState information. • 1: The provider application passes along suspect streamState information. 1 is the default setting. • 0: The provider application does not pass along suspect data. Any suspect stream will be closed with an RSSL_STREAM_CLOSED_RECOVER state. For more information, refer to Section 3.4.4. ApplicationId RSSL_DT_ASCII_STRING 1 - 65535 e.g., 256 ApplicationName Specifies the DACS application ID. If the server authenticates with DACS, the consumer application may be required to pass in a valid ApplicationId. This should match whatever was sent in the request. This must be unique for each application. IDs from 1 to 256 are reserved for permanent market data applications. Thomson Reuters assigns these and they are uniform across all client systems. IDs from 257 to 65535 are available for sitespecific use. RSSL_DT_ASCII_STRING name of application Identifies the application sending the Login e.g., Transport API request or response message. When present, the application name in the Login request If connecting to identifies the OMM consumer and the ADS, use ADS application name in the Login response identifies the OMM provider. From 0 to 4294967296 AuthenticationErrorCode RSSL_DT_UINT AuthenticationErrorText RSSL_DT_ASCII_STRING User-defined value AuthenticationExtendedResp RSSL_DT_BUFFER Specifies the code for a specific TREP Authentication error (or non-error) condition. 0 indicates no error condition and is the default setting. Text accompanying and explaining the AuthenticationErrorCode. User-defined value This is a binary buffer. AuthenticationExtendedResp contains additional customer-defined data associated with the AuthenticationToken element sent in the original Login Request. Table 6: Login Refresh msgKey.attrib Elements Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 21 Chapter 3 ELEMENT NAME DATA TYPE ENUMERATION AuthenticationTTReissue RSSL_DT_UINT Position RSSL_DT_ASCII_STRING ip addr/hostname RANGE/EXAMPLE DESCRIPTION User-defined value Indicates when a new authentication token needs to be reissued (in UNIX epoch time). or ip addr/net e.g.: 192.168.1.1/net ProvidePermissionExpressions RSSL_DT_UINT Login Domain 0|1 Specifies the DACS location. If the server authenticates with DACS, the consumer application might be required to pass in a valid position. If present, this should match whatever was sent in the request or be set to the IP address of the connected client. If specified on a Login Refresh, indicates that a provider will send permission expression information with its responses. ProvidePermissionExpressions is typically present because the login request message requested this information. Permission expressions allow for items to be proxy permissioned by a consumer via contentbased entitlements. ProvidePermissionExpressions defaults to 1. ProvidePermissionProfile RSSL_DT_UINT 0|1 If specified on the Login Refresh, indicates that the permission profile is provided. This is typically present because the login request message requested this information. An application can use the permission profile to perform proxy permissioning. ProvidePermissionProfile defaults to 1. SequenceRetryInterval RSSL_DT_UINT 0-4,294,967,295 The ADS uses this element to configure a watchlist-enabled Transport API reactor that consumes multicast data. Configures the number of seconds the reactor delays the recovery of items in response to a detected gap. SequenceRetryInterval defaults to 5. SequenceNumberRecovery RSSL_DT_UINT 0|1 The ADS uses this element to configure a watchlist-enabled Transport API Reactor that consumes multicast data. Configures whether the reactor recovers item streams when gaps are detected. • 0: The reactor does not recover items. • 1: The reactor recovers items. 1 is the default setting. Table 6: Login Refresh msgKey.attrib Elements (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 22 Chapter 3 ELEMENT NAME DATA TYPE ENUMERATION RANGE/EXAMPLE DESCRIPTION SingleOpen RSSL_DT_UINT 0|1 Login Domain Specifies whether the provider drives stream recovery: • 1: The provider drives stream recovery. 1 is the default setting. • 0: The provider does not drive stream recovery; it is the responsibility of the downstream application. For more information, refer to Section 3.4.4. SupportBatchRequests RSSL_DT_UINT 0, 7 Indicates whether the provider supports batch messages. Consumers use batch messages to specify multiple items or streams in the same request or close message. For more information on batch requesting, refer to the Transport API C Edition Developers Guide. • 0x0 (or if absent): The provider does not support batch messages. 0 is the default setting. • 0x1: The provider supports batch request. • 0x2: The provider supports batch reissue. • 0x4: The provider supports batch close. For instance, if value is set to 7, then based on combination of bits set (0x1 + 0x2 + 0x4), provider supports batch request, reissue, and close. SupportEnhancedSymbolList RSSL_DT_UINT 0|1 Indicates whether the provider supports enhanced symbol list functionality. • 0: The provider does not support Symbol List enhancements. 0 is the default setting. • 1: The provider supports Symbol List data streams. For more information on Symbol List items, refer to the Transport API C Edition Developers Guide. Table 6: Login Refresh msgKey.attrib Elements (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 23 Chapter 3 ELEMENT NAME DATA TYPE ENUMERATION RANGE/EXAMPLE DESCRIPTION SupportOMMPost RSSL_DT_UINT 0|1 Login Domain Indicates whether the provider supports OMM posting and whether the user is permissioned to post: • 1: The provider supports OMM posting and the user is permissioned. • 0: The provider supports the OMM posting feature, but the user is not permissioned. 0 is the default setting. • If absent, the server does not support the OMM Post feature. For more information on Posting, refer to the Transport API C Edition Developers Guide. SupportOptimizedPauseResume RSSL_DT_UINT SupportProviderDictionaryDownl RSSL_DT_UINT oad 0|1 0|1 Indicates whether the provider supports Optimized Pause and Resume. Optimized Pause and Resume allows for pausing/ resuming of individual item streams or pausing all item streams (by pausing the Login stream). For more information on Pause and Resume, refer to the Transport API C Edition Developers Guide. • 1: The server supports optimized pause and resume. • 0 (or if absent): The server does not support optimized pause and resume. 0 is the default setting. Indicates whether the server supports the Provider Dictionary Download feature: • 1: The server supports the provider dictionary download. • 0: The server does not support the provider dictionary download feature. 0 is the default setting. If this element is missing, the server does not support the provider dictionary download feature. For more information on the provider dictionary download feature, refer to the Transport API C Edition Developers Guide. Table 6: Login Refresh msgKey.attrib Elements (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 24 Chapter 3 ELEMENT NAME DATA TYPE ENUMERATION RANGE/EXAMPLE DESCRIPTION SupportStandby RSSL_DT_UINT 0|1 Login Domain Indicates whether the provider supports Warm Standby functionality. If supported, a provider can be told to run as an active or a standby server, where the active will behave as usual. The standby will respond to item requests only with the message header and will forward any state changing information. If informed that the active server failed, the standby begins sending responses and assumes active functionality. • 1: The provider supports a Warm Standby group setup. • 0 (or if absent): The provider does not support warm standby functionality. 0 is the default setting. For more information on Warm Standby functionality, refer to Section 3.2.9. SupportViewRequests UpdateBufferLimit RSSL_DT_UINT RSSL_DT_UINT 0|1 0-4,294,967,295 Indicates whether the provider supports requesting with Dynamic View information. Using Dynamic Views, a user can request only the specific contents of the response information in which they are interested. For more information on using Dynamic Views, refer to the Transport API C Edition Developers Guide. • 1: The provider supports Dynamic Views specified on request messages. • 0 (or if absent): The provider does not support Dynamic Views specified on request messages. 0 is the default setting. The ADS uses this element to configure a watchlist-enabled Transport API reactor that consumes multicast data. Configures the maximum number of multicast messages the reactor will interally buffer for an item. The reactor synchronizes buffered messages against the item’s refresh. UpdateBufferLimit defaults to 100. Table 6: Login Refresh msgKey.attrib Elements (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 25 Chapter 3 3.2.5 Login Domain Login Status Message OMM provider and OMM non-interactive provider applications use the Login status message to convey state information associated with the login stream. Such state information can indicate that a login stream cannot be established or to inform a consumer of a state change associated with an open login stream. The Login status message can also be used to reject a login request or close an existing login stream. When a login stream is closed via a status, any other open streams associated with the user are also closed as a result. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_STATUS == 3 domainType Required. RSSL_DMT_LOGIN == 1 state When rejecting Login: • streamState = RSSL_STREAM_CLOSED or RSSL_STREAM_CLOSED_RECOVER • dataState = RSSL_DATA_SUSPECT • stateCode = RSSL_SC_NOT_ENTITLED groupId Not used. permData Not used. extendedHeader Not used. msgKey.serviceId Not used. msgKey.nameType Optional. If present, a msgKey.flags value of RSSL_MKF_HAS_NAME_TYPE should be specified. Possible values: • RDM_LOGIN_USER_NAME == 1 • RDM_LOGIN_USER_EMAIL_ADDRESS == 2 • RDM_LOGIN_USER_TOKEN == 3 • RDM_LOGIN_USER_COOKIE == 4 If present, msgKey.nameType should match the type specified in the Login request. If msgKey.nameType is unspecified, it is assumed to be a msgKey.nameType of RDM_LOGIN_USER_NAME. msgKey.name Optional. A msgKey.flags value of RSSL_MKF_HAS_NAME should be specified and msgKey.name should match the one used in the Login request and should contain appropriate content corresponding to the msgKey.nameType specification. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Optional. If present, contains the AuthenticationErrorCode and any associated AuthenticationErrorText. Payload Not used. Table 7: Login Status Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 26 Chapter 3 3.2.6 Login Domain Login Status Elements The Login msgKey.attrib can be used to send additional authentication information and user preferences between components. The attribContainerType is an RsslElementList, which can contain any of the following predefined elements (none of which are required): ELEMENT NAME DATA TYPE ENUMERATION AuthenticationErrorCode RSSL_DT_UINT AuthenticationErrorText RSSL_DT_ASCII_STRING UpdateBufferLimit RSSL_DT_UINT RANGE/EXAMPLE DESCRIPTION From 0 to 4294967296 Specifies the code for a specific TREP Authentication error (or non-error) condition. 0 indicates no error condition and is the default setting. Text accompanying and explaining the AuthenticationErrorCode. 0-4,294,967,295 The ADS uses this element to configure a watchlist-enabled Transport API reactor that consumes multicast data. Configures the maximum number of multicast messages the reactor will interally buffer for an item. The reactor synchronizes buffered messages against the item’s refresh. UpdateBufferLimit defaults to 100. Table 8: Login Status msgKey.attrib Elements 3.2.7 Login Update Message Update messages are currently not used or supported on a Login stream. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 27 Chapter 3 3.2.8 Login Domain Login Close Message A Login close message is encoded and sent by OMM consumer applications. This message allows a consumer to log out of the system. Closing a login stream is equivalent to a ‘Close All’ type of message, where all open streams are closed (thus all other streams associated with the user are closed). A provider can log off a user and close all of that user’s streams via a Login Status message (for details, refer to Section 3.2.5). COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_CLOSE == 5 domainType Required. RSSL_DMT_LOGIN == 1 extendedHeader Not used. Payload Not used. Table 9: Login Close Message Member Use 3.2.9 Login Generic Message Use Note: The Transport API supports RsslGenericMsg use on the Login domain only for the sending and receiving of information related to “ConsumerConnectionStatus” Warm Standby Mode. A Login generic message is encoded and sent by OMM consumer applications. This message informs an interactive provider of its role in a Warm Standby group (either as an Active or Standby provider). When Active, a provider behaves normally. However, if a provider is Standby, it responds to requests only with a message header (intended to allow a consumer application to confirm the availability of their requested data across active and standby servers), and forwards any staterelated messages (i.e., unsolicited refresh messages, status messages). While in Standby mode, a provider should aggregate changes to item streams whenever possible. If the provider is changed from Standby to Active via this message, all aggregated update messages are passed along. When aggregation is not possible, a full, unsolicited refresh message is passed along. The consumer application is responsible for ensuring that items are available and equivalent across all providers in a warm standby group. This includes managing state and availability differences as well as item group differences. Content for a Login Generic message is expected to be atomic and contained in a single part, therefore RSSL_GNMF_MESSAGE_COMPLETE should be present in the Generic message’s flags. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_GENERIC == 7 domainType Required. RSSL_DMT_LOGIN == 1 partNum Not used. seqNum Not used. secondarySeqNum Not used. permData Not used. extendedHeader Not used. Table 10: Login Generic Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 28 Chapter 3 Login Domain COMPONENT DESCRIPTION / VALUE msgKey.serviceId Not used. msgKey.nameType Not used. msgKey.name Required. msgKey.name must be set to ConsumerConnectionStatus. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. Indicates whether a provider acts as an Active or Standby server. Payload is sent as an RSSL_DT_MAP type. For further details, refer to Section 3.3.2. Table 10: Login Generic Message Member Use (Continued) 3.2.10 Login Post Message OMM consumer applications can encode and send data for any item via Post messages on the item’s Login stream. This is known as off-stream posting because items are posted without using that item’s dedicated stream. Posting an item on its own dedicated stream is referred to as on-stream posting. When an application is posting off-stream, the RsslPostMsg requires msgKey information. For more details on posting, refer to the Transport API C Edition Developers Guide. 3.2.11 Login Ack Message OMM provider applications encode and send acknowledgment messages (RsslAck) to acknowledge the receipt of Post messages. This message is used whenever a consumer posts and asks for acknowledgments. For more details on posting, see the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 29 Chapter 3 3.3 Data 3.3.1 Login Refresh Message Payload Login Domain When a Login request message asks for connection configuration information (i.e., DownloadConnectionConfig = 1), a provider capable of supplying these details should respond with extended connection information in the RsslRefreshMsg payload. This information can be useful for load balancing connections across multiple providers or ADS components. Load balancing can be set up in a manner where some well-known providers act solely as load-balancing servers, monitoring the load and state of other providers and directing consumers to less-loaded providers to handle the information exchange. The extended connection information contains a list of other providers, along with connection and load-related information, and is formatted as a sorted RsslVector type, where each RsslVectorEntry contains an RsslElementList. Each vector entry contains data specific to one provider. The summary data (an RsslElementList) contains information about the number of standby providers to which the consumer should connect. If this value is non-zero, the consumer is expected to support Warm Standby functionality and connect to multiple providers. The list should be sorted in order of best to worst choice. Figure 4. Login Refresh Message Payload Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 30 Chapter 3 Login Domain When the payload is present, the summary data RsslElementList must contain the following element (which has no default): NAME TYPE RANGE/EXAMPLE DESCRIPTION NumStandbyServers RSSL_DT_UINT 0 - 0xFFFFFFFF value Specifies the number of standby servers to which the client can connect. If set to 0, only one provider is connected, which serves as the primary connection (i.e., warm standby should not be attempted). Table 11: Login Refresh.Payload Vector.SummaryData’s ElementList Contents Each RsslVectorEntry contains an RsslElementList, each list describing a single provider. Possible elements in this list are as follows, with any default behavior included in the description: NAME TYPE RANGE/EXAMPLE DESCRIPTION Hostname RSSL_DT_ASCII_STRING “myHostName” “192.168.1.100” Conditional. Specifies the candidate provider’s IP address or hostname. Hostname is required when a payload is present. Port RSSL_DT_UINT 14002 Conditional. Specifies the candidate provider’s port number. Port is required when a payload is present. LoadFactor RSSL_DT_UINT 0 - 65535 Describes the load of the provider, where 0 is the least loaded and 65535 is the most loaded. The RsslVector is expected to be sorted, so a consumer need not traverse the list to find the least loaded; the first RsslVectorEntry should contain an RsslElementList describing the least-loaded provider. LoadFactor defaults to 65535. ServerType RSSL_DT_UINT 0|1 When using a warm standby setup, ServerType specifies the provider’s expected behavior: SystemID RSSL_DT_ASCII_STRING • 0: This provider should be the Active server. • 1: This provider should be the Standby server. 1 is the default setting. For future use. Table 12: Login Refresh.Payload VectorEntry’s ElementList Contents Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 31 Chapter 3 3.3.2 Login Domain Login Generic Message Payload The Login data structure for GenericMsg.Payload is a Map of AsciiString -> ElementList. Each key is a ServiceName.Map.Key. Each RsslElementList contains one RsslElementEntry. The Login GenericMsg.Payload is formatted as an RsslMap type, with a keyPrimitiveType of RSSL_DT_ASCII_STRING and a containerType of RSSL_DT_ELEMENT_LIST. There is no summary data and typically only one map entry that informs the provider of its warm standby role. KEY PRIMITIVE TYPE CONTAINER TYPE PERMISSION DATA RSSL_DT_ASCII_STRING RSSL_DT_ELEMENT_LIST Not used DESCRIPTION Required. This entry key must be set to WarmStandbyInfo. Table 13: GenericMsg.Payload RsslMap's MapEntry Information ELEMENT NAME DATA TYPE RANGE/EXAMPLE DESCRIPTION WarmStandbyMode RSSL_DT_UINT 0|1 Required. Informs an interactive provider of its role in a Warm Standby group. • 0: Informs the provider to be an Active server • 1: Informs the provider to be a Standby server. WarmStandbyMode does not have a default. Table 14: Login GenericMsg.Payload MapEntry Elements Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 32 Chapter 3 3.4 Special Semantics 3.4.1 Authentication and Login Handling Login Domain Whether or not a user is authenticated depends on how the provider is implemented. However, providers are required to respond to Login Request Messages in the following manner: • If the Login is accepted, the provider should send a Refresh message with streamState = RSSL_STREAM_OPEN, dataState = RSSL_DATA_OK, and stateCode = RSSL_SC_NONE. • A login request can be rejected or closed by sending a Status message with streamState = RSSL_STREAM_CLOSED (or RSSL_STREAM_CLOSED_RECOVER if the user is allowed to attempt another login), dataState = RSSL_DATA_SUSPECT, and a stateCode that best describes the reason for the stream closure. • If the provider closes the login stream, all other streams related to that login are implicitly closed without sending any item status messages to the consumer. • If the consumer application closes the login stream using a close message, all streams related to that login are automatically closed without sending any item close messages to the provider. • If a login stream is not open or was closed by either the consumer or the provider, the consumer must open a new Login stream before sending any other request messages. If the consumer application attempts to request data without an open Login stream, it will receive a status message indicating failure. • 3.4.2 Negotiating msgKey.attrib Parameters Note: The consumer must support all parameters specified by the provider in its Login response. Several ReqMsg.MsgKey.Attrib parameters indicate how the provider should handle a connection including: ProvidePermissionProfile, ProvidePermissionExpressions, SingleOpen, AllowSuspectData, InstanceId, and Role. If the provider cannot support a specified value, it can change the value in the RespMsg.MsgKey.Attrib’s ElementList in its response to the consumer. If the RespMsg.MsgKey.Attrib includes an ElementList, then the Elements should be checked to verify that the parameters have been accepted. If a request parameters differs from the response parameter, the consumer must support the parameters that the server provided in the RespMsg. 3.4.3 Group and Service Status Group and service status messages do not apply to the Login domain. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 33 Chapter 3 3.4.4 Login Domain Single Open and Allow Suspect Data Behavior The SingleOpen and AllowSuspectData Elements that are passed via the ReqMsg.MsgKey.Attrib can effect how state information is processed. When the provider indicates support for SingleOpen behavior, the provider should drive the recovery of item streams. If no provider support is indicated, the consumer should drive any recovery. The following table shows how a provider can convert messages to honor the consumer’s SingleOpen and AllowSuspectData settings. The first column in the table shows the provider’s actual streamState and dataState. Each subsequent column shows how this state information can be modified to follow that column’s specific SingleOpen and AllowSuspectData settings. If any SingleOpen and AllowSuspectData configuration causes a contradiction in behavior (e.g., SingleOpen indicates that the provider should handle recovery, but AllowSuspectData indicates that the consumer does not want to receive suspect status), SingleOpen behavior takes precedence. Note: The Transport API does not perform any special processing based on the SingleOpen and AllowSuspectData settings. The provider application must perform any necessary conversion. If AcceptingRequests is FALSE, new requests should not be made to a provider application, regardless of ServiceState. However, even if AcceptingRequests is FALSE, reissue requests can still be made for any item streams that are currently open to the provider. The following table uses the abbreviations: • SS for streamState • DS for dataState ACTUAL STATE INFORMATION MESSAGE SENT WHEN: SINGLEOPEN = 1 ALLOWSUSPECTDATA = 1 MESSAGE SENT WHEN: SINGLEOPEN = 1 ALLOWSUSPECTDATA = 0 MESSAGE SENT WHEN: SINGLEOPEN = 0 ALLOWSUSPECTDATA = 1 MESSAGE SENT WHEN: SINGLEOPEN = 0 ALLOWSUSPECTDATA = 0 SS = OPEN DS = SUSPECT SS = OPEN DS = SUSPECT SS = OPEN DS = SUSPECT SS = OPEN DS = SUSPECT SS = CLOSED_RECOVER DS = SUSPECT SS = CLOSED_RECOVER DS = SUSPECT SS = OPEN DS = SUSPECT SS = OPEN DS = SUSPECT SS = CLOSED_RECOVER DS = SUSPECT SS = CLOSED_RECOVER DS = SUSPECT New item request whena: SS = OPEN ServiceState = DOWN DS = SUSPECT AcceptingRequests = TRUE SS = OPEN DS = SUSPECT SS = CLOSED_RECOVER DS = SUSPECT SS = CLOSED_RECOVER DS = SUSPECT SS = OPEN New item requests whena: ServiceState = UP DS = OK or SUSPECT based AcceptingRequests = TRUE on individual item’s state. SS = OPEN DS = OK or SUSPECT based on individual item’s state. SS = OPEN DS = OK or SUSPECT based on individual item’s state. If DS == OK: SS = OPEN if DS == SUSPECT: SS = CLOSED_RECOVER Table 15: SingleOpen and AllowSuspectData Handling a. For more information, refer to Source Directory information in Chapter 4, Source Directory Domain. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 34 Chapter 3 3.5 Login Sample XML 3.5.1 Login Request Message Sample XML Login DomainCode Example 1: Login Request Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 35 Chapter 3 3.5.2 Login Domain Login Refresh Message Sample XML Code Example 2: Login Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 36 Chapter 4 Source Directory Domain Chapter 4 Source Directory Domain 4.1 Description The Source Directory domain model conveys: • Information about all available services and their capabilities. This includes information about domain types supported within a service, the service’s state, the QoS, and any item group information associated with the service. Each service is associated with a unique serviceId. When requesting or responding to information associated with a specific service, the serviceId is specified in the msgKey. • Status information associated with item groups. This allows a single message to change the state of all associated items, avoiding the need to send a status message for each individual item. The consumer is responsible for applying any changes to its open items. For details, refer to Section 4.3.1.2 and Section 4.3.1.3. • Source Mirroring information between an ADH and OMM interactive provider applications exchanged via a specificallyformatted generic message as described in Section 4.2.5. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 37 Chapter 4 4.2 Usage 4.2.1 Source Directory Request Message Source Directory Domain A Directory request message is encoded and sent by OMM consumer applications. A consumer can request information about all services by omitting serviceId information, or specify a serviceId to request information about only that service. Because the Source Directory domain uses a RsslFilterList, a consumer can indicate the specific source related information in which it is interested via a msgKey.filter. Each bit-value represented in the filter corresponds to an information set that can be provided in response messages. A consumer can change the requested filter via a reissue. For more details about the RsslFilterList type, refer to the Transport API C Edition Developers Guide. Thomson Reuters recommends that a consumer application minimally request Info, State, and Group filters for the Source Directory: • The Info filter contains the ServiceName and serviceId data for all available services. When an appropriate service is discovered by the OMM Consumer, the serviceId associated with the service is used on subsequent requests to that service. • The State filter contains status data for the service. Status data informs the Consumer whether the service is up (and available) or down (and unavailable). • The Group filter conveys any item group status information, including group states and as regards the merging of groups if applicable. Note: If an application does not subscribe to the Source Directory’s group filter, it will not receive group status messages. This can result in potentially incorrect item state information, as relevant status information may be missed. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_SOURCE == 4 qos Not used. worstQos Not used. priorityClass Not used. priorityCount Not used. extendedHeader Not used. msgKey.nameType Not used. msgKey.name Not used. Table 16: Source Directory Request Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 38 Chapter 4 Source Directory Domain COMPONENT DESCRIPTION / VALUE msgKey.filter Required. Specifies a filter indicating the specific data in which a consumer is interested. Available categories include: • RDM_DIRECTORY_SERVICE_INFO_FILTER == 0x01 • RDM_DIRECTORY_SERVICE_STATE_FILTER == 0x02 • RDM_DIRECTORY_SERVICE_GROUP_FILTER == 0x04 • RDM_DIRECTORY_SERVICE_LOAD_FILTER == 0x08 • RDM_DIRECTORY_SERVICE_DATA_FILTER == 0x10 • RDM_DIRECTORY_SERVICE_LINK_FILTER == 0x20 • RDM_DIRECTORY_SERVICE_SEQ_MCAST_FILTER == 0x40 For details on the contents of each filter entry, refer to Section 4.3.1.1. msgKey.serviceId Optional. If a consumer wants information regarding only one particular service, it should specifythe msgKey.serviceId of that service (i.e., set a msgKey.flags value of RSSL_MKF_HAS_SERVICE_ID). If the consumer wishes to receive information about all services, the consumer should not specify a msgKey.serviceId (i.e., the consumer should not set RSSL_MKF_HAS_SERVICE_ID). msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 16: Source Directory Request Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 39 Chapter 4 4.2.2 Source Directory Domain Source Directory Refresh Message A Directory Refresh Message is sent by OMM provider and OMM non-interactive provider applications. This message provides information about currently-known services, as well as additional details ranging from state information to provided domain types. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_REFRESH == 2 domainType Required. RSSL_DMT_SOURCE == 4 state Required. Indicates stream and data state information. qos Not used. seqNum Optional. A user-specified, item-level sequence number that the application can use to sequence messages within this stream. groupId Not used. permData Not used. extendedHeader Not used. msgKey.serviceId Not used. msgKey.nameType Not used. msgKey.name Not used. msgKey.filter Required. Identifies the filtered entries provided in this response. When possible, this should match the filter set in the consumer’s request. For additional details, refer to the msgKey.filter member in Section 4.2.1. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. The payload contains data about available services in the form of an RsslMap where each entry’s key is one serviceId. For additional details, refer to Section 4.3.1. Table 17: Source Directory Refresh Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 40 Chapter 4 4.2.3 Source Directory Domain Source Directory Update Message A Source Directory Update Message is sent by OMM provider and OMM non-interactive provider applications. An Update message can: • Indicate the addition or removal of services from the system or changes to existing services. • Convey item group status information via the State and Group filter entries. For more information about item group use, refer to the Transport API C Edition Developers Guide. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_UPDATE == 4 domainType Required. RSSL_DMT_SOURCE == 4 updateType Not used. seqNum Optional. A user-specified, item-level sequence number that the application can use to sequence messages in this stream. conflationCount Not used. conflationTime Not used. permData Not used. extendedHeader Not used. msgKey.serviceId Not used. msgKey.nameType Not used. msgKey.name Not used. msgKey.filter Optional. The msgKey.filter indicates which filter entries are provided in this response. For an update, this conveys only the ID values associated with filter entries present in the update payload. For more details, refer to the msgKey.filter member in Section 4.2.1. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. The payload contains only the changed information associated with the provided services. For more details, refer to Section 4.3.1. Table 18: Source Directory Update Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 41 Chapter 4 4.2.4 Source Directory Domain Source Directory Status Message A Source Directory status message is encoded and sent by both OMM interactive provider and non-interactive provider applications. This message conveys state change information associated with a source directory stream. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_STATUS == 3 domainType Required. RSSL_DMT_SOURCE == 4 state Optional. Contains stream and data state information for the directory stream. groupId Not used. permData Optional. If present, this is the new permissioning information associated with all contents on the stream. extendedHeader Not used. msgKey.serviceId Not used. msgKey.nameType Not used. msgKey.name Not used. msgKey.filter Required. The filter represents the filter entries being provided in this response. When possible, this should match the filter as set in the consumer’s request. For additional details, refer to the msgKey.filter member in Section 4.2.1 msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 19: Source Directory Status Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 42 Chapter 4 4.2.5 Source Directory Domain Source Directory Generic Message A Source Directory Generic message is encoded and sent by an ADH when using a ‘hot standby’ configuration. When running in hot standby mode, the ADH can leverage source mirroring and use a generic message to convey usage information to upstream providers. A generic message can inform providers whether the ADH is an active server without a standby (ActiveNoStandby), an active server with a standby (ActiveWithStandby) or a standby provider (Standby). This message is mainly for informational purposes, and allows a provider to better understand their role in a hot standby environment (the provider does not require a return action or acknowledgment). A provider indicates each service’s ability to process this message via the AcceptingConsumerStatus element in its Source Directory responses (refer to Section 4.3.1.1). COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_GENERIC == 7 domainType Required. RSSL_DMT_SOURCE == 4 partNum Not used. seqNum Optional. A user-specified, item-level sequence number that the application can use to sequence messages in this stream. secondarySeqNum Not used. permData Not used. extendedHeader Not used. msgKey.serviceId Not used (Payload can contain information pertaining to multiple services, each of which is specifically identified in the payload). msgKey.nameType Not used. msgKey.name Required. The name of this message must be ConsumerStatus. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. The payload is an RsslMap whose entries contain the Source Mirroring status for each service. For the full structure, refer to Section 4.3.2. Table 20: Source Directory Generic Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 43 Chapter 4 4.3 Data 4.3.1 Source Directory Refresh and Update Payload Source Directory Domain A list of services is represented by an RsslMap. Each RsslMapEntry represents a known service and is uniquely identified by its msgKey.serviceId (i.e., its key). The information about each service is represented as an RsslFilterList. Each RsslFilterEntry contains one of six different categories of information. These categories should correspond to the msgKey.filter member of the refresh or update. For example layouts of these messages, refer to Section 4.5. Figure 5. Source Directory Refresh and Update Message Payload KEY TYPE CONTAINER TYPE PERMISSION DATA DESCRIPTION RSSL_DT_UINT RSSL_DT_FILTER_LIST Not used Contains information for each known service. The key is the service’s msgKey.serviceId. Table 21: Source Directory RsslMap Contents Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 44 Chapter 4 Source Directory Domain There are six categories of information about a service, each represented by one RsslFilterEntry. Categories can be added or updated in update messages (note that the clear action RSSL_FTEA_CLEAR_ENTRY is not used, and that the Info category should not change). RSSLFILTERENTRY ID (CORRESPONDING MSGKEY.FILTER BITVALUE) TYPE DESCRIPTION RDM_DIRECTORY_SERVICE_INFO_ID == 1 (RDM_DIRECTORY_SERVICE_INFO_FILTER == 0x01) RSSL_DT_ELEMENT_LIST Provider applications must be able to provide this information. Identifies a service and its available data. Refer to Section 4.3.1.1. RDM_DIRECTORY_SERVICE_STATE_ID = 2 (RDM_DIRECTORY_SERVICE_STATE_FILTER == 0x02) RSSL_DT_ELEMENT_LIST Provider applications must be able to provide this information. Describes the current state of a service (i.e., the service’s current ability to provide data). Can also change the status of all items associated with this service. The effects of this category occur immediately. Therefore, the initiating RsslUpdateMsg should set RSSL_UPMF_DO_NOT_CONFLATE. Refer to Section 4.3.1.2. RDM_DIRECTORY_SERVICE_GROUP_ID == 3 (RDM_DIRECTORY_SERVICE_GROUP_FILTER == 0x04) RSSL_DT_ELEMENT_LIST Manages group information. Can change the status of a group of items or merge items from one group to another. The effects of this category occur immediately and only affect existing items. Therefore, the initiating RsslUpdateMsg should set RSSL_UPMF_DO_NOT_CONFLATE and RSSL_UPMF_DO_NOT_CACHE. Refer to Section 4.3.1.3. RDM_DIRECTORY_SERVICE_LOAD_ID == 4 (RDM_DIRECTORY_SERVICE_LOAD_FILTER == 0x08) RSSL_DT_ELEMENT_LIST Information about the current workload of this service, including how many items are currently being serviced. Optionally, the initiating RsslUpdateMsg can set RSSL_UPMF_DO_NOT_CONFLATE. Refer to Section 4.3.1.4. RDM_DIRECTORY_SERVICE_DATA_ID == 5 (RDM_DIRECTORY_SERVICE_DATA_FILTER == 0x10) RSSL_DT_ELEMENT_LIST Includes broadcast data that applies to all items requested from that service. This information is typically provided in a dedicated RsslUpdateMsg and sent independently of other filter entries. The data filter is commonly used with ANSI Pagebased data. Flag values RSSL_UPMF_DO_NOT_CONFLATE and RSSL_UPMF_DO_NOT_CACHE can optionally be set to prevent conflation and caching of this content. Refer to Section 4.3.1.5. Table 22: Source Directory RsslMapEntry Filter Entries Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 45 Chapter 4 RSSLFILTERENTRY ID (CORRESPONDING MSGKEY.FILTER BITVALUE) RDM_DIRECTORY_SERVICE_LINK_ID = 6 (RDM_DIRECTORY_SERVICE_LINK_FILTER = 0x20) Source Directory Domain TYPE DESCRIPTION RSSL_DT_MAP Provides information about individual upstream sources that provide data for this service. This is primarily used by systems that aggregate sources (such as the ADH) for identification and load balancing, and is not required to be processed by a consumer application. Refer to Section 4.3.1.6. RDM_DIRECTORY_SERVICE_SEQ_MCAST_ID = 7 RSSL_DT_ELEMENT_LIST (RDM_DIRECTORY_SERVICE_SEQ_MCAST_FILTER = 0x40) Provides information about the EDF (Elektron Direct Feed) and EDF connection information. For further information, refer to the Elektron Direct Feed Development Guide. Table 22: Source Directory RsslMapEntry Filter Entries (Continued) 4.3.1.1 Source Directory Info Filter Entry The Info filter entry (RDM_DIRECTORY_SERVICE_INFO_FILTER, RDM_DIRECTORY_SERVICE_INFO_ID) conveys information that identifies a service and the content it can provide. This includes information about provided domain types (e.g., Market Price, Market By Order), available QoS, and the names of any dictionaries required to parse the published content. The Info RsslFilterEntry should be present when a service is first added, and should not be changed as long as the service remains in the list. If an RsslFilterEntry element uses a default value, it is included in the element’s description. RANGE/ EXAMPLE ELEMENT NAME TYPE DESCRIPTION Name RSSL_DT_ASCII_STRING e.g., IDN_RDF Required. Specifies the service’s name. This value allows for mapping between the service name and the serviceId. Vendor RSSL_DT_ASCII_STRING e.g., Thomson Reuters Specifies the name of the vendor that provides the data for this service. IsSource RSSL_DT_UINT 0|1 Specifies whether the service aggregates content from multiple sources. Available values are: • 0: The service aggregates multiple sources into a single service. This is the default behavior. • 1: The service is provided directly by the original publisher Capabilities RSSL_DT_ARRAY of RSSL_DT_UINT e.g., [5, 6] Required. Lists the domains which this service can provide. For example, a list containing RSSL_DMT_DICTIONARY (5) and RSSL_DMT_MARKET_PRICE (6) indicates a consumer can request dictionaries and Market Price data from this service. Set RsslArray.itemLength to 1, as each domainType uses only one byte. Table 23: Source Directory Info Filter Entry Elements Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 46 Chapter 4 RANGE/ EXAMPLE Source Directory Domain ELEMENT NAME TYPE DictionariesProvided RSSL_DT_ARRAY of e.g., RWFFld RSSL_DT_ASCII_STRING Lists the Dictionary names that this service can provide. A consumer can obtain these dictionaries by requesting them by name on the RSSL_DMT_DICTIONARY domain. For details, refer to Chapter 5, Dictionary Domain. DictionariesUsed RSSL_DT_ARRAY of e.g., RWFFld, RSSL_DT_ASCII_STRING RWFEnum Conditional. Lists the Dictionary names that might be required to fully process data from this service. Whether or not the dictionary is required depends on the consumer’s needs. For example: if the consumer is not a display application, it might not need an Enumerated Types Dictionary. For details, refer to Chapter 5, Dictionary Domain. QoS RSSL_DT_ARRAY of RSSL_DT_QOS e.g., Realtime, Tick- Specifies the available Qualities of Service (QoS). By-Tick • If the data comes from one source, there will usually be only one QoS. • If there are multiple sources, more than one QoS may be available. The default QoS is Realtime, Tick-By-Tick. Thus. if a QoS is not provided, or if the Transport API receives a QoS value of Unspecified, the Transport API assumes the service provides a QoS of Realtime, Tick-By-Tick. For more information about QoS use and handling, refer to the Transport API C Edition Developers Guide. SupportsQoSRange RSSL_DT_UINT 0|1 ItemList RSSL_DT_ASCII_STRING SupportsOutOfBandSnapshots RSSL_DT_UINT DESCRIPTION Indicates whether the provider supports a QoS range when requesting an item. If supported, a consumer can indicate an acceptable range via the qos and worstQos members of an RsslRequestMsg. • 0: The provider does not support QoS range requests. This is the default behavior. • 1: The provider supports QoS range requests. Specifies the name of a SymbolList (i.e., a specific item requested to get the names of all items available for this service). The consumer requests this item via the RSSL_DMT_SYMBOL_LIST domain (See Chapter 11, Symbol List Domain). 0|1 Indicates whether Snapshot requests can still be made after reaching the OpenLimit (refer to Section 4.3.1.4). • 0: Snapshot requests cannot be made if the OpenLimit is reached. • 1: Snapshot requests can be made even when the OpenLimit is reached. This is the default behavior. Table 23: Source Directory Info Filter Entry Elements (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 47 Chapter 4 ELEMENT NAME TYPE RANGE/ EXAMPLE AcceptingConsumerStatus RSSL_DT_UINT 0|1 Source Directory Domain DESCRIPTION Indicates whether a service can accept and process messages related to Source Mirroring (refer to Section 4.2.4). • 0: The service cannot accept and process messages related to Source Mirroring. • 1: The service can accept and process messages related to Source Mirroring. This is the default behavior. Table 23: Source Directory Info Filter Entry Elements (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 48 Chapter 4 4.3.1.2 Source Directory Domain Source Directory State Filter Entry The State filter entry (RDM_DIRECTORY_SERVICE_STATE_FILTER, RDM_DIRECTORY_SERVICE_STATE_ID) conveys information about the current state of a service. This information usually has some bearing on the availability of data from a service. If a service becomes temporarily unavailable or becomes available again, consumers are informed via updates to this category. This category should be present in the initial refresh and updated as needed. The Status element can change the state of items provided by this service. Prior to changing a service status, Thomson Reuters recommends that you issue item or group status messages to update item states. Any default behavior is explained in the Element’s description. ELEMENT NAME TYPE RANGE/EXAMPLE DESCRIPTION ServiceState RSSL_DT_UINT 0|1 Required. Indicates whether the original provider of the data is available to respond to new requests. If the service is down, requests for data may be handled by the immediate upstream provider (to which the consumer is directly connected). However, because the most current data might be serviced from a cached copy while the source is down, the most current data may not be immediately available. Changes to ServiceState do not affect streams that are already open. Available values are: • 0: Service is Down • 1: Service is Up Refer to Section 4.4.3. AcceptingRequests RSSL_DT_UINT 0|1 Indicates whether the immediate provider can accept new requests and/or handle reissue requests on already open streams. Existing streams remain unaffected, however new requests may be rejected. AcceptingRequests defaults to 1. Available values are: • 0: The provider cannot accept new requests on existing streams. • 1: The provider can accept new requests on existing streams. Refer to Section 4.4.3. Status RSSL_DT_STATE e.g., [RSSL_STREAM_OPEN, Specifies a status change to apply to all items provided by RSSL_DATA_OK, this service. It is equivalent to sending an RsslStatusMsg for each item. RSSL_SC_NONE] The streamState is only allowed to be RSSL_STREAM_OPEN or RSSL_STREAM_CLOSED_RECOVER. This status only applies to item streams that have received a refresh or status of OPEN/OK. Refer to Section 4.4.3.1. Table 24: Source Directory State RsslFilterEntry Elements Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 49 Chapter 4 4.3.1.3 Source Directory Domain Source Directory Group Filter Entry The Group filter entry (RDM_DIRECTORY_SERVICE_GROUP_FILTER, RDM_DIRECTORY_SERVICE_GROUP_ID) conveys item group status and item group merge information. Every item stream is associated with an item group as defined by the groupId provided with the item’s RsslRefreshMsg or RsslStatusMsg. If some kind of change impacts all items within the same group, only a single group status message need be provided. For more information on item group use and handling, see the Transport API C Edition Developers Guide. If multiple group RsslFilterEntrys are received in a single RsslFilterList, then they should be applied in the order in which they were received. Any default behavior is explained in the Element’s description. ELEMENT NAME TYPE RANGE/EXAMPLE DESCRIPTION Group RSSL_DT_BUFFER e.g., 1.26.102 Required. Specifies the groupId with which this information is associated. This is typically represented as a series of 2-byte unsigned integers (i.e., two-byte unsigned integers written directly next to each other in the buffer). The example provided in the RANGE / EXAMPLE column of this table shows such a series, with inserted dots to help indicate two-byte value. When encoded into a buffer, do not include these dots. MergedToGroup RSSL_DT_BUFFER e.g., 1.26.110 Changes all items whose group currently matches the Group element to the specified MergedToGroup. Note: The consumer should change the groupId of those items to match this element. Status RSSL_DT_STATE e.g., [RSSL_STREAM_OPEN, RSSL_DATA_OK, RSSL_SC_NONE, ] A status change to be applied to all items whose groupId matches the Group element. It is equivalent to sending an RsslStatusMsg to each item. • The streamState is only allowed to be RSSL_STREAM_OPEN or RSSL_STREAM_CLOSED_RECOVER. • If you need to convey group status text or code information without changing the data state, use the value RSSL_DATA_NO_CHANGE. • If present in the same message as a MergedToGroup element, this change should be applied before the merge. This change only applies to item streams that have received a refresh or status with a state of OPEN/OK. Refer to Section 4.4.3.2 Table 25: Source Directory Group RsslFilterEntry Elements Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 50 Chapter 4 4.3.1.4 Source Directory Domain Source Directory Load Filter Entry The Load filter entry (RDM_DIRECTORY_SERVICE_LOAD_FILTER, RDM_DIRECTORY_SERVICE_LOAD_ID) conveys information about the service’s workload. If multiple services can provide desired data, a consumer can use service workload information to help decide which to use. None of these elements are required, nor have a default value. ELEMENT NAME TYPE RANGE/ EXAMPLE OpenLimit RSSL_DT_UINT 0 – 4,294,967,295 Maximum number of streaming items that the client is allowed to open for this service. If the service supports out-of-band snapshots, snapshot requests do not count against this limit (refer to Section 4.3.1.1). OpenWindow RSSL_DT_UINT 0 - 4,294,967,295 Maximum number of outstanding requests (i.e., requests for items not yet open) that the service will allow at any given time. If OpenWindow is 0, the behavior is the same as setting AcceptingRequests to 0 and no open item request is accepted. The provider should not assume that the OpenWindow becomes effective immediately. LoadFactor RSSL_DT_UINT 0-65,535 A number indicating the current workload on the source providing the data. This number and the means of its calculation vary based on the system (i.e., bandwidth usage, CPU usage, number of clients, etc). The only requirements are that: • The LoadFactor should be calculated the same way for all services in a system. • A more heavily-loaded service should have a higher LoadFactor than one that is less loaded. DESCRIPTION Table 26: Source Directory Load RsslFilterEntry Elements 4.3.1.5 Source Directory Data Filter Entry The Data filter entry (RDM_DIRECTORY_SERVICE_DATA_FILTER, RDM_DIRECTORY_SERVICE_DATA_ID) conveys information that should be applied to all items associated with the service. This is commonly used for services that provide ANSI Page-based data. These elements has do not have a default value. ELEMENT NAME TYPE RANGE/EXAMPLE Type RSSL_DT_UINT • • • • • Data Any Data Type DESCRIPTION Time(1) Conditional. You must include Type when data is present. Explains the content of the Data. Alert (2) Headline (3) Status (4) Reserved values : 0 - 1023 Data that should be applied to all items from the service; commonly used for services providing ANSI Page-based data. The contents of this element should be applied as an update to every item open for this stream. After the data fans out, it does not need to be cached as part of the source directory. Table 27: Source Directory Data RsslFilterEntry Elements Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 51 Chapter 4 4.3.1.6 Source Directory Domain Source Directory Link Filter Entry The Link filter entry (RDM_DIRECTORY_SERVICE_LINK_FILTER, RDM_DIRECTORY_SERVICE_LINK_ID) conveys information about the upstream sources that provide data to a service. This information is represented as an RsslMap, where each RsslMapEntry represents one upstream source. The map entry key is the name associated with the communication link, and is of type RSSL_DT_ASCII_STRING. This name is scoped globally, and if multiple sources have the same name, they are assumed to be identical and the aggregating system will balance requests among them. An ADH component can leverage this information for failover and hot standby functionality. More detailed information is available in the ADH documentation. A typical consumer application can treat this entry as mainly informational. The consumer should use the State RsslFilterEntry to make programmatic decisions about service availability and status. Any default behavior is explained in the Element’s description. ELEMENT NAME TYPE RANGE/EXAMPLE DESCRIPTION Type RSSL_DT_UINT 1|2 Indicates whether the upstream source is interactive or broadcast. This does not describe whether the service itself is interactive or broadcast. • 1: The upstream source is interactive (this is the default). • 2: The upstream source is a broadcast source. LinkState RSSL_DT_UINT 0|1 Required. Indicates whether the upstream source is up or down • 0: The upstream source is down. • 1: The upstream source is up. LinkCode RSSL_DT_UINT 0-3 Provides additional status information about the upstream source. • 0: None (this is the default) • 1: Ok • 2: RecoveryStarted • 3: RecoveryCompleted Text RSSL_DT_ASCII_STRING N/A Explains the LinkState and LinkCode. Text defaults to “”. Table 28: Source Directory Link RsslFilterEntry Map Contents Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 52 Chapter 4 4.3.1.7 Source Directory Domain Source Directory Sequenced Multicast Filter Entry The Sequenced Multicast filter entry (RDM_DIRECTORY_SERVICE_SEQ_MCAST_FILTER, RDM_DIRECTORY_SERVICE_SEQ_MCAST_ID) convey information about EDF components and connection information. This information is represented as an RsslElementList, where each RsslElementEntry represents information about the EDF component. The entries that contain the information about the Real Time Streams or Gap Fill Servers will have RsslElementEntry that contain RsslVector with RsslVectorEntry with additional connection information (Multicast Group, Port, and Domain). While none of the RsslFieldEntry Map elements are required, all of the RsslFieldEntry vector elements are required. ELEMENT NAME TYPE RANGE/ EXAMPLE DESCRIPTION ReferenceDataServerHost RSSL_DT_ASCII_STRING 10.0.1.125 The hostname, or IP address, of the Reference Data Server. ReferenceDataServerPort RSSL_DT_UINT 14000 The port number to which the Reference Data Server is bound and on which it listens for incoming connections. SnapshotServerHost RSSL_DT_ASCII_STRING 10.0.1.125 The hostname, or IP address, of the Snapshot server. SnapshotServerPort RSSL_DT_UINT 14002 The port number to which the Snapshot Server is bound and on which it listens for incoming connections. GapRecoveryServerHost RSSL_DT_ASCII_STRING 10.0.1.125 The hostname, or IP address, of the Gap Recovery Server. GapRecoveryServerPort RSSL_DT_UINT 14001 The port number to which the Gap Recovery Server is bound and on which it listens for incoming connections. StreamingMulticastChannel RSSL_DT_VECTOR of s RSSL_DT_ELEMENT_LIST Multicast channel/port information for the streaming data provided by the service. GapMulticastChannels Multicast channel/port information used by the Gap Recovery Server. RSSL_DT_VECTOR of RSSL_DT_ELEMENT_LIST Table 29: Source Directory Sequenced Multicast RsslFilterEntry Map Contents ELEMENT NAME TYPE RANGE/ EXAMPLE DESCRIPTION MulticastGroup RSSL_DT_ASCII_STRING 224.1.62.2 Required. The Multicast channel used. Port RSSL_DT_UINT 30001 Required. The port used. Domain RSSL_DT_UINT 6 (MarketPrice) Required. The domain covered by this multicast channel and port. Table 30: Source Directory Sequenced Multicast RsslFilterEntry Vector Contents Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 53 Chapter 4 4.3.2 Source Directory Domain Source Directory ConsumerStatus Generic Message Payload Note: RsslGenericMsg(s) are supported for the DIRECTORY RDM only for sending / receiving information related to ConsumerStatus/Source Mirroring Mode. The data structure for the ConsumerStatus message is an RsslMap. Each RsslMapEntry sends status to one service and is uniquely identified by msgKey.serviceId (its key). Each entry contains an RsslElementList with one RsslElementEntry that indicates how the provider is used. RsslMapEntrys do not use permission data. KEY TYPE VALUE TYPE DESCRIPTION RSSL_DT_UINT RSSL_DT_ELEMENT_LIST Required. Represents a service in the Source Directory. Contains an RsslElementList with Source Mirroring information for that service. Table 31: Source Directory RsslGenericMsg RsslMapEntry ELEMENT NAME TYPE RANGE/EXAMPLE DESCRIPTION SourceMirroringMode RSSL_DT_UINT 0-2 Required. Indicates how the downstream component uses the service. There is no default setting. SourceMirroringMode can have any of the following values: • 0: ActiveNoStandby. The downstream device uses the data from this service, and does not receive it from any other service. • 1: ActiveWithStandby. The downstream device uses the data from this service, but also receives it from another service. • 2: Standby. The downstream device receives data from this service, but actually uses data from another service. A reply from the provider application is not needed because this is for informational use only. Table 32: Source Directory Generic Message RsslMapEntry Elements 4.4 Special Semantics 4.4.1 Multiple Streams Unlike other MessageModelTypes, two directory streams can be open with identical message key information. It is also permissible to change an open stream’s filter. 4.4.2 ServiceState and AcceptingRequests The ServiceState and AcceptingRequests elements in the State filter entry work together to indicate the ability of a particular service to provide data: • ServiceState indicates whether the source of the data is accepting requests. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 54 Chapter 4 • Source Directory Domain AcceptingRequests indicates whether the immediate upstream provider (the provider to which the consumer is directly connected) can accept new requests. If False, new requests are rejected while existing streams remain unaffected (reissue requests can still be made for any item streams that are currently open to the provider). The following table applies only to new requests. Changes to the status of current streams should be sent using individual item status messages or group status messages via the Group filter entry (refer to Section 4.3.1.3). SERVICESTATE ACCEPTINGREQUESTS MEANING Up(1) Yes (1) New requests and reissue requests can be successfully processed. Up(1) No (0) Although the source of data is available, the immediate provider is not accepting new requests. It may be possible to request from another provider. However, reissue requests on already open streams can be processed. Down (0) Yes (1) The source of data is not available. The immediate provider, however, can accept the request and forward it when the source becomes available. Down (0) No (0) Neither the source nor the immediate provider is accepting new requests. Table 33: ServiceState and AcceptingRequests Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 55 Chapter 4 4.4.3 Source Directory Domain Service and Group Status Values The Status elements in the State and Group FilterEntries are transient. Their values should be applied to all existing streams. The values should not be cached and should not affect any new requests. 4.4.3.1 Service Status Providers can use a directory’s ServiceState.Status element to efficiently change the state of all of a service’s existing streams with a single message. The ServiceState.Status does not apply to requests that are currently pending a first refresh or status response message. EMA consumer implementation normally fans out state from the Status Element to all items associated with the service. When EMA does this, it will not forward this Element to the application. Instead, the application receives a RsslStatusMsg for each item from the service. The other elements from the ServiceState RsslFilterEntry will still be sent to the application. 4.4.3.2 Group Status The Group RsslFilterEntry can be used to efficiently change the state of a large number of items with a single message. The Group.Status does not apply to requests that are currently pending a first refresh or status response message. EMA consumer implementation normally fans out group messages to all items associated with the group. When EMA does this, it will not forward this RsslFilterEntry to the application. Instead, the application will receive a RsslStatusMsg for each item in the group. 4.4.4 Removing a Service If a provider needs to remove a service from the list of known services, it should send the service’s RsslMapEntry with the action set to RSSL_MPEA_DELETE_ENTRY. A consumer should place all open items associated with this service in the RSSL_STREAM_CLOSED_RECOVER. All services associated with a Source Directory stream are removed if: • The connection between the provider and consumer is closed or lost • The provider sends a state of RSSL_STREAM_CLOSED or RSSL_STREAM_CLOSED_RECOVER on the Source Directory stream. • The provider sends a message with the RSSL_RFMF_CLEAR_CACHE on an RsslRefreshMsg or RSSL_STMF_CLEAR_CACHE on an RsslStatusMsg on the Source Directory stream. Note: Though not best practice, some applications may continue to store service information, even after a service is removed. If this is the case, the application should advertise the service as Down and not accepting requests. 4.4.5 Non-existent Services If no services currently exist or the consumer issued a Source Directory request and specified an unknown serviceId, a Source Directory refresh should be sent containing an empty RsslMap. The provider can then add services, via Source Directory updates, as they become available. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 56 Chapter 4 4.5 Source Directory Sample XML 4.5.1 Source Directory Request Message Sample XML Source Directory Domain Code Example 3: Source Directory Request Message Sample XML Message Layout 4.5.2 Source Directory Refresh Message Sample XML Code Example 4: Source Directory Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 58 Chapter 5 Dictionary Domain Chapter 5 Dictionary Domain 5.1 Description Note: RsslGenericMsg(s) are not supported for the Dictionary domain model. OMM can optimize bandwidth usage by reducing or removing the need to constantly communicate well-known information (e.g., names and data types associated with information in an RsslFieldList). Using these techniques, information is instead contained in a field dictionary, where the field list contains only fieldId references to information in the dictionary. A provider application can indicate any dictionaries needed to parse published content. To reconstruct omitted information, consumer applications reference required dictionaries when decoding. Dictionaries may be available locally (i.e., in a file) or available for request over the network from an upstream provider. The following dictionaries provide domain models for network requests: • Field Dictionary: Stores data referenced by the RsslFieldList. Each fieldId in an RsslFieldEntry corresponds to an entry in the Field Dictionary, which provides information such as the field’s name (e.g., BID) and data type (e.g., RSSL_DT_INT). Additional information (such as rippling fields and expected cache-sizing requirements) are also present. • Enumerated Types Dictionary: Contains tables defining values for enumerated values of type RsslEnum (RSSL_DT_ENUM). Each table indicates the fieldId values of all fields that use the data in the table, as well as the possible enumerated values. For example, a field indicating the currency of an item will use a table listing enumerations of various currencies. If a consumer decodes the value of that field (e.g., 840), it can cross reference that value with its copy of the table. The entry the consumer finds will contain a string that the consumer can print (e.g. USD), and possibly a more meaningful description as well. • Global Field Set Definition and Global Element Set Definition: Provides global set definition database information. These databases contain several set definitions, each of which contains a list of fieldId (for field lists) or Name (for element lists) and value pairs. These definitions are used with structured data and provide bandwidth savings by not sending data contained in the set definition on the wire. The consumer should store the information contained in these dictionaries and may need to refer to them when decoding data. For assistance, the Transport API provides utility functions for loading, encoding, and decoding the Thomson Reuters Field Dictionary (RDMFieldDictionary) and Enumerated Types Dictionaries (enumtype.def) (for details, refer to Section 5.12). 5.2 Decoding Field List Contents with Field and Enumerated Types Dictionaries By itself, an RsslFieldEntry contains only the fieldId and its associated encoded value in encData. With few exceptions, the type information is not sent with the data and will appear as RSSL_DT_UNKNOWN. To decode the value, the application must cross reference the fieldId with the correct Field Dictionary to determine its type. The RsslFieldList.dictionaryId can optionally convey the identifier of the associated dictionary. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 59 Chapter 5 Dictionary Domain Figure 6. RsslFieldList Referencing Field Dictionary The consumer matches the fieldId of the RsslFieldEntry to the information about that FID in the dictionary. This tells the consumer the type (RsslDataTypes) of the data contained in the RsslFieldEntry. The consumer can now decode the data by calling the appropriate decode function for that type. If the field’s type is RSSL_DT_ENUM, the application expects and looks for a table of values in a corresponding Enumerated Types Dictionary. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 60 Chapter 5 Dictionary Domain Figure 7. RsslFieldEntry Referencing an Enumerated Types Table The consumer, having decoded the enumerated value (e.g., 840), finds the correct table that defines the field and looks up the enumerated value in that table. The value will have a displayable string associated with it (e.g., USD). 5.3 Usage 5.3.1 Dictionary Request Message A dictionary request message is encoded and sent by OMM consumer applications. The request indicates the name of the desired dictionary and how much information from that dictionary is needed. Though updates are not sent on dictionary streams, Thomson Reuters recommends that the consumer make a streaming request (setting RSSL_RQMF_STREAMING) so that it is notified whenever the dictionary version changes. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_DICTIONARY == 5 qos Not used. Table 34: Dictionary Request Message Member Use Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 61 Chapter 5 COMPONENT Dictionary Domain DESCRIPTION / VALUE worstQos Not used. priorityClass Not used. priorityCount Not used. extendedHeader Not used. msgKey.serviceId Required. Specifies the msgKey.serviceId of the service from which the consumer requests the dictionary. msgKey.nameType Not used. msgKey.name Required. Specify a msgKey.flags value of RSSL_MKF_HAS_NAME. Specifies the msgKey.name of the desired dictionary as seen in the Source Directory response (refer to Section 4.3.1.1). msgKey.filter Required. The filter represents the desired verbosity of the dictionary. The consumer should set the msgKey.filter according to how much information is needed: • RDM_DICTIONARY_INFO == 0x00: Provides version information only. • RDM_DICTIONARY_MINIMAL == 0x03: Provides information needed for caching. • RDM_DICTIONARY_NORMAL == 0x07: Provides all information needed for decoding. • RDM_DICTIONARY_VERBOSE == 0x0F: Provides all information (including comments). Providers are not required to support the MINIMAL and VERBOSE filters. msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 34: Dictionary Request Message Member Use (Continued) 5.3.2 Dictionary Refresh Message A dictionary request message is encoded and sent by OMM consumer applications. The request indicates the name of the desired dictionary and how much information from that dictionary is needed. Though updates are not sent on dictionary streams, Thomson Reuters recommends that the consumer make a streaming request (setting RSSL_RQMF_STREAMING) so that it is notified whenever the dictionary version changes. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_DICTIONARY == 5 qos Not used. worstQos Not used. priorityClass Not used. priorityCount Not used. Table 35: Dictionary Request Message Member Use Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 62 Chapter 5 COMPONENT Dictionary Domain DESCRIPTION / VALUE extendedHeader Not used. msgKey.serviceId Required. Specifies the msgKey.serviceId of the service from which the consumer requests the dictionary. msgKey.nameType Not used. msgKey.name Required. Specify a msgKey.flags value of RSSL_MKF_HAS_NAME. Specifies the msgKey.name of the desired dictionary as seen in the Source Directory response (refer to Section 4.3.1.1). msgKey.filter Required. The filter represents the desired verbosity of the dictionary. The consumer should set the msgKey.filter according to how much information is needed: • RDM_DICTIONARY_INFO == 0x00: Provides version information only. • RDM_DICTIONARY_MINIMAL == 0x03: Provides information needed for caching. • RDM_DICTIONARY_NORMAL == 0x07: Provides all information needed for decoding. • RDM_DICTIONARY_VERBOSE == 0x0F: Provides all information (including comments). Providers are not required to support the MINIMAL and VERBOSE filters. msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 35: Dictionary Request Message Member Use (Continued) 5.3.3 Dictionary Status Message A dictionary status message is encoded and sent by OMM Interactive and non-interactive provider applications. This message can indicate changes to a dictionary’s version. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_STATUS == 3 domainType Required. RSSL_DMT_DICTIONARY == 5 state Optional. Used to indicate a change to a dictionary version. For more details, refer to Section 5.9.3. groupId Not used. permData Conditional. Used if the provided dictionary requires permissioning. extendedHeader Not used. msgKey.serviceId Optional. msgKey.nameType Not used. msgKey.name Optional. Should match name that was requested. msgKey.filter Not used. Table 36: Dictionary Status Message Member Use Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 63 Chapter 5 COMPONENT Dictionary Domain DESCRIPTION / VALUE msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 36: Dictionary Status Message Member Use (Continued) 5.4 Payload and Summary Data for the Refresh Message For example layouts of some dictionary messages, refer to Section 5.11. The payload varies depending on the type of dictionary being sent. The domain model layout for each type of dictionary is described in the following sections. Although the structure varies for each type of dictionary, each uses an RsslElementList to identify its type, version, and DictionaryId. If sending the dictionary as a multi-part refresh, this data must be present only in the first part. Any default behavior is included in the dictionary type’s description. NAME TYPE RANGE/EXAMPLE Version RSSL_DT_ASCII_STRING “1.1” DESCRIPTION Required. Specifies the version of the provided dictionary. For additional details on dictionary versions, refer to Section 5.9.3. Note: The Enumerated Types dictionaries populate the Version element using information from the DT_Version tag. Type RSSL_DT_UINT Total range is from 0 to 255, where values 0 - 127 are Required. Indicates the type of reserved and values 28-255 are extensible. dictionary contained in the payload. • RDM_DICTIONARY_FIELD_DEFINITIONS == 1 • RDM_DICTIONARY_ENUM_TABLES == 2 • RDM_DICTIONARY_RECORD_TEMPLATES == 3 • RDM_DICTIONARY_DISPLAY_TEMPLATES == 4 • RDM_DICTIONARY_DATA_DEFINITIONS == 5 • RDM_DICTIONARY_STYLE_SHEET == 6 • RDM_DICTIONARY_REFERENCE == 7 DictionaryId RSSL_DT_INT Total range is from -16383 to 16383, where: • Values 0 to 16383 are reserved by Thomson Reuters • The value 1 corresponds to the RDMFieldDictionary. • Values -1 to -16383 are Extensible An ID that can indicates a relationship between dictionaries. For example, a Field Dictionary and EnumeratedTypes Dictionary may have the same DictionaryId, indicating that they can be used together. DictionaryId defaults to 0. Table 37: Dictionary summaryData Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 64 Chapter 5 RANGE/EXAMPLE Dictionary Domain NAME TYPE DESCRIPTION RT_Version RSSL_DT_ASCII_STRING “1.1” Optionally sent only with the enumerated type dictionary. RT_Version identifies which field dictionary should be used with this enumerated type dictionary. DT_Version RSSL_DT_ASCII_STRING “1.1” Optionally sent only with the enumerated type dictionary. DT_Version conveys the display template version. Table 37: Dictionary summaryData (Continued) 5.5 Field Dictionary 5.5.1 Field Dictionary Payload The payload of a Field Dictionary Refresh Message consists of an RsslSeries where each series entries contains an RsslElementList. Each RsslSeriesEntry represents a row of information in the dictionary. The RsslElementList contained in each series entry provides information about an element of the row. Figure 8. Field Dictionary Payload Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 65 Chapter 5 Dictionary Domain Element entries do not have default values. NAME TYPE LEAST RANGE/EXAMPLE VERBOSITY NAME RSSL_DT_ASCII_STRING MINIMAL e.g., “PROD_PERM” Equivalent to the field’s ACRONYM (i.e., Short Name). FID RSSL_DT_INT MINIMAL -32768 to 32767 The field’s fieldId. RIPPLETO RSSL_DT_INT MINIMAL -32768 to 32767 If the field ripples, this is the fieldId of the field it ripples to. A value of 0 indicates no rippling. For a description of rippling, refer to the DESCRIPTION Transport API C Edition Developers Guide. TYPEa RSSL_DT_INT MINIMAL e.g., RSSL_MFEED_INTEGER The data type of the field for the Marketfeed format. LENGTHa RSSL_DT_UINT MINIMAL 0 to 65535 The maximum string length of the field for the Marketfeed format. RWFTYPE RSSL_DT_UINT MINIMAL e.g., RSSL_DT_INT The data type (RsslDataTypes) of the field. RWFLEN RSSL_DT_UINT MINIMAL 0 to 65535 The maximum length needed to cache the encoded value (the value found in the RsslFieldEntry’s encData buffer). This is only a suggestion and is not enforced. A length of 0 implies that the maximum possible size for that type should be used for caching. ENUMLENGTH RSSL_DT_UINT NORMAL 0 to 65535 Used for fields of type RSSL_DT_ENUM. This is the length of the DISPLAY element in its Enumerated Types table (See Section 5.6.1). LONGNAME RSSL_DT_ASCII_STRING NORMAL e.g., “PERMISSION” Equivalent to the field’s DDE ACRONYM (i.e., Long Name). Table 38: Field Dictionary Element Entries a. These elements are specific to the Marketfeed format and can be used in converting to or from it. They can otherwise be ignored. 5.5.2 Field Dictionary File Format The RDMFieldDictionary file format is a plain-text table. Each row represents one field, and each column a datum about that field. Each row is separated with a line break and columns are separated by whitespace. Lines beginning with an exclamation point (!) are comments and are ignored. !ACRONYM PROD_PERM RDNDISPLAY DSPLY_NAME RDN_EXCHID DDE ACRONYM "PERMISSION" "DISPLAYTEMPLATE" "DISPLAY NAME" "IDN EXCHANGE ID" FID 1 2 3 4 Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 RIPPLES TO NULL NULL NULL NULL FIELD TYPE INTEGER INTEGER ALPHANUMERIC ENUMERATED LENGTH 5 3 16 3 ( 3 ) RWF TYPE UINT64 UINT32 RMTES_STRING ENUM RWF LEN 2 1 16 1 66 Chapter 5 TRDPRC_2 TRDPRC_3 TRDPRC_4 TRDPRC_5 "LAST "LAST "LAST "LAST 1" 2" 3" 4" 7 8 9 10 TRDPRC_3 TRDPRC_4 TRDPRC_5 NULL PRICE PRICE PRICE PRICE 17 17 17 17 REAL64 REAL64 REAL64 REAL64 Dictionary Domain 7 7 7 7 Figure 9. Field Dictionary File Format Sample Several tagged attributes are available at the beginning of the file. These attributes provide versioning information about the dictionary in the file and are processed when loading from a file-based dictionary. Some of this information is conveyed along with the domain model representation of the dictionary. Tags may be added as future dictionary versions become available. For the RDMFieldDictionary, an example of these tags are shown below. !tag !tag !tag !tag !tag !tag Filename Desc Type Version Build Date RWF.DAT RDFD RWF field set 1 4.00.14 002 18-Nov-2010 Figure 10. Field Dictionary Tagged Attributes Sample 5.5.2.1 Field Dictionary Tag Attributes The following table describes tag attributes and indicates whether they are used when encoding the domain representation of the file. TAG ATTRIBUTE DESCRIPTION Filename The original name of the file as created by Thomson Reuters. This typically will not match the current name of the file, RDMFieldDictionary. Filename is not used when encoding the domain representation of the field dictionary. Desc Describes the dictionary. Desc is not used when encoding the domain representation of the field dictionary. Type Stores the dictionary type associated with this dictionary. For a field dictionary, this should be RDM_DICTIONARY_FIELD_DEFINITIONS == 1. Other types are defined in Section 5.4. Type is used when encoding the domain representation of the field dictionary. Version Stores version information associated with this dictionary. Version is used when encoding the domain representation of the field dictionary. Build Stores internal build information. Build is not used when encoding the domain representation of the field dictionary. Table 39: Field Dictionary File Tag Information Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 67 Chapter 5 TAG ATTRIBUTE DESCRIPTION Date Stores dictionary release date information. Dictionary Domain Date is not used when encoding the domain representation of the field dictionary. Table 39: Field Dictionary File Tag Information (Continued) 5.5.2.2 Field Dictionary Columns The columns in the field dictionary correspond to the RsslElementEntry names used while encoding and decoding the Field Dictionary: COLUMN NAME IN FILE RWF ELEMENT NAME NOTES ACRONYM NAME The abbreviated name corresponding to the field. DDE ACRONYM LONGNAME A longer version of the name represented by the Acronym. FID FID The Field Identifier value. RIPPLES TO RIPPLETO The file format uses the ACRONYM of the target field, rather than the rows fieldId. If the field does not ripple, this should be NULL. FIELD TYPE TYPE The Marketfeed type associated with this field. LENGTH LENGTH (ENUMLENGTH) The Marketfeed length associated with the field. RWF TYPE RWFTYPE The RWF type (RsslDataTypes) associated with the field. RWF LEN RWFLEN A caching length hint associated with this field. Table 40: Field Dictionary File Column Names and RsslElementEntry Names 5.5.2.3 RWF TYPE Keywords The following keywords are supported for the RWF TYPE: KEYWORD RSSL DATA TYPE ANSI_PAGEa RSSL_DT_ANSI_PAGE ARRAYa RSSL_DT_ARRAY ASCII_STRING RSSL_DT_ASCII_STRING BUFFER RSSL_DT_BUFFER DATE RSSL_DT_DATE DATETIMEa RSSL_DT_DATETIME DOUBLEa RSSL_DT_DOUBLE ELEMENT_LIST, ELEM_LISTa RSSL_DT_ELEMENT_LIST Table 41: Field Dictionary Type Keywords and Their Data Types Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 68 Chapter 5 KEYWORD Dictionary Domain RSSL DATA TYPE ENUM RSSL_DT_ENUM FIELD_LISTa RSSL_DT_FIELD_LIST FILTER_LISTa RSSL_DT_FILTER_LIST FLOATa RSSL_DT_FLOAT INT, INT32, INT64 RSSL_DT_INT MAPa RSSL_DT_MAP MSGa RSSL_DT_MSG OPAQUE RSSL_DT_OPAQUE QOSa RSSL_DT_QOS REAL, REAL32, REAL64 RSSL_DT_REAL RMTES_STRING RSSL_DT_RMTES_STRING SERIESa RSSL_DT_SERIES STATUSa RSSL_DT_STATE TIME RSSL_DT_TIME UINT, UINT32, UINT64 RSSL_DT_UINT UTF8_STRING RSSL_DT_UTF8_STRING VECTORa RSSL_DT_VECTOR XMLa RSSL_DT_XML Table 41: Field Dictionary Type Keywords and Their Data Types (Continued) a. Type is RWF-Only and does not have a Marketfeed equivalent. 5.5.2.4 FIELD TYPE Keywords Valid keywords for the Marketfeed Field Type are INTEGER, ALPHANUMERIC, ENUMERATED, TIME, TIME_SECONDS, DATE, or PRICE. The table below lists the mappings from FIELD TYPE to the RWF TYPE keyword. All are used in RDMFieldDictionary and are safe. FIELD TYPE LENGTH RWF TYPE RWF LEN NOTES ALPHANUMERIC 14 ASCII_STRING 14 RIC/SYMBOL ALPHANUMERIC 21 ASCII_STRING 21 RIC/SYMBOL ALPHANUMERIC 28 ASCII_STRING 28 RIC/SYMBOL ALPHANUMERIC 1-255 RMTES_STRING 1-255 length <= 3 is technically ASCII Table 42: Marketfeed to RWF Mappings in RDMFieldDictionary Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 69 Chapter 5 Dictionary Domain FIELD TYPE LENGTH RWF TYPE RWF LEN NOTES ENUMERATED 2-3 (1-8) ENUM 1 Enum values 0 - 255 ENUMERATED 5 (3-8) ENUM 2 Enum values 0 - 65535 BINARY 3 UINT32 2 Base64 encoded 2-byte unsigned int BINARY 4 UINT32 3 Base64 encoded 3-byte unsigned int BINARY 43 BUFFER 32 Base64 encoded buffer BINARY 171 BUFFER 128 Base64 encoded buffer DATE 11 DATE 4 Day, month, year TIME_SECONDS 8 TIME 5 Time in hour, minute, second, and millisecond TIME 5 TIME 5 Time in hour, minute, and second PRICE 17 REAL 9 RsslReal can represent values with fractional denominators, trailing zeros, or up to 14 decimal positions. INTEGER 15 REAL 7 Signed integer value, where trailing zero values can be optimized off of the wire. INTEGER 3 UINT 1 unsigned int 0 - 255 INTEGER 5 UINT 2 unsigned int 0 - 65535 INTEGER 10 UINT 5 unsigned int 0 - (240-1) INTEGER 15 UINT 8 unsigned int 0 - (264-1) INTEGER 15 UINT 4 unsigned int 0 - (232-1) Table 42: Marketfeed to RWF Mappings in RDMFieldDictionary (Continued) 5.6 Enumerated Types Dictionary 5.6.1 Enumerated Types Dictionary Payload The payload of an Enumerated Types Dictionary Refresh Message consists of an RsslSeries with each series entry (RsslSeriesEntry) containing an RsslElementList and representing a table in the dictionary. The RsslElementList in each entry contains information about each Enumerated Type in the table. Each RsslElementEntry has a type of RSSL_DT_ARRAY, where there is one element for each column in the file: VALUE, DISPLAY, and MEANING. The content of each RsslArray corresponds to one Enumerated Type, so each array should contain the same number of entries. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 70 Chapter 5 Dictionary Domain Figure 11. Enumerated Types Dictionary Refresh Message Payload Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 71 Chapter 5 LEAST EXAMPLE VERBOSITY LIST Dictionary Domain NAME TYPE FIDS RSSL_DT_ARRAY of RSSL_DT_INT NORMAL 15, 1084, 1085,… The fieldId’s of all fields that reference this table. These fields should have type RSSL_DT_ENUM in the Field Dictionary and use the values given in the VALUE list. The RsslArray.itemLength should be 2 because each fieldId is a two-byte, signed integer value. VALUE RSSL_DT_ARRAY of RSSL_DT_ENUM NORMAL 826, 840, … Includes values that correspond to each Enumerated Type. RsslFieldEntries that use the table contain these values. The RsslArray.itemLength should be 2 since each enum is a two-byte, unsigned integer value. DISPLAY NORMAL RSSL_DT_ARRAY of RSSL_DT_ASCII_STRING, RSSL_DT_RMTES_STRING, or RSSL_DT_UTF8_STRING “GBP”, “USD”,… Brief, displayable names for each Enumerated Type. RSSL_DT_ARRAY of RSSL_DT_ASCII_STRING “UK pound sterling”, “US Dollar”,… MEANING VERBOSE DESCRIPTION When special characters are needed, the DISPLAY column uses a hexadecimal value identified by using hash marks instead of quotation marks (e.g., #42FE#). A longer description of each Enumerated Type. Note: Providers do not need to provide this array (even when verbosity is VERBOSE). Table 43: Element Entries Describing Each Enumerated Type Table 5.6.2 Enumerated Types Dictionary File Format The enumtype.def file format is a plain-text set of tables. Rows are separated by lines and columns are separated by whitespace (excepting quoted strings, as illustrated in Section 5.6.1). Lines that begin with an exclamation point (!) are comments and are ignored. The file contains a set of tables, each with two sections: 1. A section with the list of fieldId values corresponding to all fields that use the table. 2. A section with the table of enumerated values and their respective display data. 5.6.2.1 Enumerated Types Dictionary File Example ! ACRONYM ! ------BIG_FIGURE PIPS_POS ! VALUE ! ----0 FID --6207 6208 DISPLAY ------"INT" MEANING ------whole number Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 72 Chapter 5 1 2 3 4 5 6 7 "1DP" "2DP" "3DP" "4DP" "5DP" "6DP" "7DP" ! ! ACRONYM ! ------MATUR_UNIT ! ! VALUE ! ----0 1 2 3 4 1 2 3 4 5 6 7 decimal decimal decimal decimal decimal decimal decimal Dictionary Domain place places places places places places places FID --2378 DISPLAY ------" " "Yr " "Mth" "Wk " "Day" MEANING ------Undefined Years Months Weeks Days Code Example 5: Enumerated Types Dictionary File Format Sample 5.6.2.2 Tagged Attributes Several tagged attributes are available at the beginning of the file. These attributes provide version information about the dictionary contained in the file and are processed while loading from a file-based dictionary. Some of this information is conveyed along with the domain model representation of the dictionary. Tags may be added as future dictionary versions become available. For the enumtype.def, an example of these tags are as follows: !tag !tag !tag !tag !tag !tag Filename Desc Type RT_Version DT_Version Date ENUMTYPE.001 IDN Marketstream enumerated tables 2 4.20.17 15.41 5-Feb-2017 Code Example 6: Enumerated Types Dictionary Tagged Attribute Sample The following table describes the tag attributes and indicates which are used when encoding the domain representation of the file. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 73 Chapter 5 TAG ATTRIBUTE Date Dictionary Domain DESCRIPTION Includes information regarding the dictionary release date. Date is not used when encoding the domain representation of the field dictionary. Desc A Description of the dictionary. Desc is not used when encoding the domain representation of the field dictionary. DT_Version The version of the display template version. DT_Version is used when encoding the domain representation of the field dictionary. For device compatibility purposes, this value is sent as both Version and DT_Version. Filename The original name of the file as created by Thomson Reuters. This typically does not match the current name of the file, enumtype.def. Filename not used when encoding the domain representation of the field dictionary. RT_Version The version of the field dictionary associated with this enumerated type dictionary. RT_Version is used when encoding the domain representation of the field dictionary. Type The dictionary type associated with this dictionary. For an enumerated types dictionary, this should be RDM_DICTIONARY_ENUM_TABLES == 2. Other types are defined in Section 5.4. Type is used when encoding the domain representation of the field dictionary. Table 44: Enumerated Type Dictionary File Tag Information 5.6.2.3 Reference Fields Section The first section lists all fields that use the table. These fields should have the type RSSL_DT_ENUM in their corresponding Field Dictionary and have matching names. NAME RWF ELEMENT NAME ACRONYM n/a (The name of the field is not sent with the dictionary payload). FID FIDS Table 45: RWF EnumType Dictionary File Format Reference Fields 5.6.2.4 Values Table Section The second section lists the value of each enumerated type and its corresponding display data. NAME RWF ELEMENT NAME NOTES VALUE VALUE The unsigned, integer value corresponding to the enumerated value. DISPLAY DISPLAY In cases where special characters are needed, the DISPLAY column uses a hexadecimal value, which is identified by using hash marks instead of quotation marks, e.g. #42FE#. MEANING MEANING The meaning column is not required over the network and typically not provided. Table 46: RWF EnumType Dictionary File Values Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 74 Chapter 5 5.7 Dictionary Domain Global Field Set Definition Payload Note: This portion of the Dictionary Domain is used only with the Elektron Direct Feed (EDF) product. For further details, consult the EDF product documentation. The payload of a Field Set Definition Dictionary Refresh Message consists of an RsslVector, where each vector entry contains an RsslElementList. Each RsslVectorEntry represents a specific Set Definition Id, which corresponds to the RsslVectorEntry’s index. Each line in the set definition is represented by a corresponding value in the arrays within the FIDS and TYPES element entries. Figure 12. Global Field Set Definition Payload Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 75 Chapter 5 Dictionary Domain The following table shows the valid type enumerations for a set definition line, including base primitives, as well as set primitives. RWF TYPE DESCRIPTION RSSL_DT_INT Signed Integer, 63 bits of value, with one bit of sign RSSL_DT_UINT Unsigned Integer, 64 bits of value RSSL_DT_FLOAT 32-bit Floating Point, represents the same range as the system type RSSL_DT_DOUBLE 64-bit Floating Point, represents the same range as the system type RSSL_DT_REAL Real Numeric value, 63 bits of value, with a one-bit sign, and a hint enumeration RSSL_DT_DATE Date type, containing month, day, and year values RSSL_DT_TIME Time type, containing hour, minute, second, and millisecond values RSSL_DT_DATETIME Date time type, containing all members of RSSL_DT_DATE and RSSL_DT_TIME RSSL_DT_QOS Quality of Service type RSSL_DT_STATE Stream state type. RSSL_DT_ENUM Enumeration type, defined as a two-byte unsigned value RSSL_DT_ARRAY Array type, represents a list of simple primitive types RSSL_DT_BUFFER Buffer type, represents a binary data buffer RSSL_DT_ASCII_STRING Buffer type containing an ASCII string data RSSL_DT_UTF8_STRING Buffer type containing a UTF8 string data RSSL_DT_RMTES_STRING Buffer type containing a Reuters Multilingual Text Encoding Standard string data RSSL_DT_INT_1 1-byte encoded length signed integer, 7 bits value with 1 bit sign RSSL_DT_INT_2 2-byte encoded length signed integer, 15 bits value with 1 bit sign RSSL_DT_INT_4 4-byte encoded length signed integer, 31 bits value with 1 bit sign RSSL_DT_INT_8 8-byte encoded length signed integer, 63 bits value with 1 bit sign RSSL_DT_UINT_1 1 encoded byte length unsigned integer, 8 bits of value RSSL_DT_UINT_2 2-byte encoded length unsigned integer, 16 bits of value RSSL_DT_UINT_4 4-byte encoded length unsigned integer, 32 bits of value RSSL_DT_UINT_8 8-byte encoded length unsigned integer, 64 bits of value RSSL_DT_FLOAT_4 4-byte encoded length floating point value RSSL_DT_DOUBLE_8 8-byte encoded length floating point value RSSL_DT_REAL_4RB Optimized, variable length real encoding, with a maximum value up to 31 bits and 1 signed bit RSSL_DT_REAL_8RB Optimized, variable length real encoding, with a maximum value of 63 bits and 1 signed bit RSSL_DT_DATE_4 4-byte encoded length date type containing year, month, and day values Table 47: Set Definition Enumerations Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 76 Chapter 5 RWF TYPE Dictionary Domain DESCRIPTION RSSL_DT_TIME_3 3-byte encoded length time type containing hours, minutes, and seconds values RSSL_DT_TIME_5 5-byte encoded length time type containing hours, minutes, seconds, and milliseconds values RSSL_DT_TIME_7 7-byte encoded length time type containing hours, minutes, seconds, milliseconds, and microseconds values RSSL_DT_TIME_8 8-byte encoded length time type containing hours, minutes, seconds, milliseconds, microseconds, and nanoseconds values RSSL_DT_DATETIME_7 7-byte encoded length date time type containing full RSSL_DT_DATE and hours, minutes and seconds RSSL_DT_DATETIME_9 9-byte encoded length date time type containing full RSSL_DT_DATE and RSSL_DT_TIME values RSSL_DT_DATETIME_11 11-byte encoded length date time type containing RSSL_DT_DATE and hours, minutes, seconds, milliseconds, and microseconds values. RSSL_DT_DATETIME_12 12-byte encoded length date time type containing RSSL_DT_DATE/DataTypes.DATE and hours, minutes, seconds, milliseconds, microseconds, and nanoseconds values Table 47: Set Definition Enumerations (Continued) 5.8 Global Element Set Definition Payload Note: This portion of the Dictionary Domain is used only with the Elektron Direct Feed (EDF) product. For further details, consult the EDF product documentation. The payload of a Global Element Set Definition Dictionary Refresh Message consists of an RsslVector, where each vector entry contains an RsslElementList. Each RsslVectorEntry represents a specific set definition ID, which corresponds to the RsslVectorEntry’s index. Each line in the set definition is represented by a corresponding value in the arrays within the FIDS and TYPES element entries. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 77 Chapter 5 Dictionary Domain Figure 13. Global Element Set Definition Payload 5.9 Special Semantics 5.9.1 DictionaryId A dictionaryId can be included with RsslFieldList and RsslElementList payload information. The dictionaryId contained in the payload should match the Id of the dictionaries required to encode or decode the content. (e.g. Field Dictionary, Enumerated Types Dictionary). Dictionaries used together to decode a field list should all have a matching Id. dictionaryId values are globally scoped and can have a range of values from -16383 to 16383. Values 0 through 16383 are reserved for Thomson Reuters use. Customers can provide their own dictionaries by selecting a dictionaryId between -1 and -16383. A dictionaryId can be changed in two ways. If a dictionaryId is provided on a solicited or unsolicited refresh message, this dictionary is used across all messages on the stream until a different dictionaryId is provided in a subsequent solicited or unsolicited refresh. If an RsslFieldEntry contains a fieldId of zero, this reserved value indicates a temporary dictionary change. In this situation, this entry’s value is the new dictionaryId, encoded or decoded as an RsslInt. When a dictionaryId is changed in this manner, the change is only in effect on the remaining entries in the field list or until another fieldId of zero is encountered. Any other containerType housed inside of a remaining entry also adopts the temporarily changed dictionary. After the end of the field list is reached, the dictionaryId from the refresh takes precedence once again. 5.9.2 DictionariesProvided and DictionariesUsed The Source Directory’s Info filter entry (refer to Section 4.3.1.1) includes two elements related to Dictionaries: DictionariesProvided and DictionariesUsed. Both elements contain an RsslArray of RSSL_DT_ASCII_STRING dictionary names. These names can be used in msgKey.name to request the dictionaries. To dynamically discover dictionaries while minimizing the amount of data downloaded: 1. Parse the “DictionariesUsed” from each desired service in the Source Directory. 2. Parse the “DictionariesProvided” from every service in the Source Directory. 3. Make a streaming request for each Dictionary Name listed in DictionariesUsed from the service that lists the DictionaryName in DictionariesProvided. The msgKey.filter of each RsslRequestMsg should be set to RDM_DICTIONARY_INFO so as to request only the dictionary’s basic information (because dictionaries tend to be large, this setting prevents unnecessary network traffic). 4. For each Dictionary response, parse the summaryData in the payload to obtain the dictionary’s Type and Version. • If a dictionary is of an unneeded type, that dictionary stream can be closed. • If a dictionary is needed, a reissue request can be made where the msgKey.filter requests a higher verbosity (e.g. RDM_DICTIONARY_NORMAL). • Version information can be used to determine if the consumer needs to update its dictionary. 5.9.3 Version Information The version of a dictionary is normally available in Summary Data in the payload of an RsslRefreshMsg. All available verbosities are expected to include this information. The verbosity RDM_DICTIONARY_INFO can be used to request only the version information (as the many fields in dictionaries tend to result in large messages). Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 78 Chapter 5 Dictionary Domain This information normally comes in the form of an RSSL_DT_ASCII_STRING containing a dotted-decimal version number, indicating first the major version, followed by the minor version, and possibly followed by a third (informational) micro-version. For example, in the string 1.2.3: • 1 is the major version • 2 is the minor version • 3 is the micro-version 5.9.3.1 Version Information Usage Version information has a couple of uses: • The minor version changes whenever a dictionary adds new fields, but does not modify existing fields. This means the consumer can still use the previous dictionary with its data (though the consumer is unable to decode any new fields). Also, if the consumer has multiple dictionaries with the same major version available, it can use the minor version information to determine which is the latest (and therefore will be able to decode all fields regardless of the data’s source). • The major version changes if the dictionary changes in a way that is not compatible with previous versions (such as changing an existing field). This means that data encoded using a dictionary with one major version cannot be decoded using a dictionary with a different major version. If a consumer learns that its provider has changed to a dictionary with a different major version, it must retrieve the new dictionary before again decoding data. 5.9.3.2 Handling Dictionary Version Changes To keep consumers informed of changes, Thomson Reuters recommends that dictionary requests be streaming even though updates are not used for this domain. If the dictionary’s minor version changes, a provider may advertise it via an RsslStatusMsg with an RsslState of RSSL_STREAM_OPEN/RSSL_DATA_SUSPECT. The consumer may then reissue its dictionary request to obtain the latest version. If a dictionary’s major version is changed, the provider should disconnect all consumers to ensure that the consumers’ content and dictionary are entirely resynchronized. 5.10 Other Dictionary Types The Dictionary domain is intended to be used for other versionable data that updates very rarely. This section briefly describes the other reserved dictionary types. None of these dictionary types are currently used, nor is there any domain model specification associated with any of them at this time. Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 79 Chapter 5 DICTIONARY TYPE RecordTemplate Dictionary Domain DESCRIPTION A RecordTemplate dictionary contains multiple record templates. Each record template contains a list of all of the fields present in a FieldList. Historically, RecordTemplates have been used for QForms. While they can be used for Marketfeed records and FieldLists, they typically are not used for those data formats. Templates for Marketfeed records and FieldLists are dynamically generated when an image is received. Examples of external file representations for a RecordTemplate dictionary include tss_records.cf and appendix_d. DisplayTemplate A DisplayTemplate dictionary contains specifications that describe how and where to display fields on a screen. DataDefinition A Data Definitions dictionary contains specifications for Set Definitions for use with Field Lists and Element Lists. Set Definitions provide bandwidth optimization by separating out repetitive or redundant data. StyleSheet A StyleSheet dictionary contains an XSLT or CSS style sheet. Reference A Reference dictionary is a table of reference information provided as a RsslSeries. This information is not used for parsing, interpreting, caching, or displaying data. Table 48: Other Dictionary Types 5.11 Dictionary Sample XML 5.11.1 Dictionary Request Message Sample XML Code Example 7: Dictionary Request Message Sample XML Message Layout 5.11.2 Field Dictionary Refresh Message Sample XML Code Example 8: Field Dictionary Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 81 Chapter 5 5.11.3 Dictionary Domain Enumerated Types Dictionary Refresh Message Sample XML Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 80 Chapter 5 Dictionary Domain Figure 14. Enumerated Type Dictionary Refresh Message Sample XML Message Layout 5.12 Dictionary Utility Function Utility functions load, encode, and decode Field and Enumerated Types Dictionaries. You may find these functions in the rsslDataDictionary.h header. The functions should be called with an RsslDataDictionary object, which stores information associated with each field (any associated Enumerated Types table, if the field uses one). Each load or decode function adds information to the object when called. Fields and Enumerated Types tables may be added from any number of sources, as long as there is no duplicate or conflicting information. The RsslDataDictionary object stores an array of RsslDictionaryEntry objects, indexed by fieldId. Each entry stores the data type (RsslDataTypes) of the field along with other information. The field will also have a reference to an RsslEnumTypeTable, if the field uses an Enumerated Types table. FUNCTION NAME DESCRIPTION rsslClearDataDictionary Clears the RsslDataDictionary. This must be done prior to initial use of the object. rsslLoadFieldDictionary Adds data from a Field Dictionary file to the RsslDataDictionary (refer to Section 5.5.2). This currently supports the RDMFieldDictionary, or other dictionaries using the same formatting. rsslDecodeFieldDictionary Adds data from a Field Dictionary message payload to the RsslDataDictionary (refer to Section 5.5.1). rsslEncodeFieldDictionary Creates a Field Dictionary message payload from the RsslDataDictionary object (refer to Section 5.5.1). rsslLoadEnumTypeDictionary Adds data from an Enumerated Types Dictionary file to the RsslDataDictionary (refer to Section 5.6.2). This currently supports the enumtype.def, or other enumerated type dictionaries using the same formatting. rsslDecodeEnumTypeDictionary Adds data from an Enumerated Types Dictionary message payload to the RsslDataDictionary (refer to Section 5.6.1). rsslEncodeEnumTypeDictionary rsslPrintDataDictionary Creates an Enumerated Types Dictionary message payload from the RsslDataDictionary object (refer to Section 5.6.1). Note that this function uses RSSL_DT_ASCII_STRING as the DISPLAY array type. Prints the information (fields, enumerated type tables) currently stored in the RsslDataDictionary. Aids in debugging. Table 49: Dictionary Helper Functions Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 83 Chapter 5 FUNCTION NAME rsslExtractDictionaryType Dictionary Domain DESCRIPTION Extracts the RDM Dictionary Type (RDMDictionaryTypes) information from an encoded dictionary. This can determine the specific dictionary decode function that should be used (e.g. for dictionary type of RDM_DICTIONARY_FIELD_DEFINITIONS, the user would next invoke the rsslDecodeFieldDictionary function). This is expected to be called after rsslDecodeMsg (where the RsslMsg.domainType is RSSL_DMT_DICTIONARY), but before decoding the RsslMsg.encDataBody payload. rsslClearFieldSetDefDb Clears the RsslFieldSetDefDb. This must be called before initial use of the object. rsslAddFieldSetDefToDb Deep copies the given RsslFieldSetDef into the RsslFieldSetDefDb. rsslEncodeFieldSetDefDictionary Creates a Global Field Set Definition Dictionary message payload from the RsslFieldSetDefDb object (refer to Section 5.7). rsslDecodeFieldSetDefDictionary Adds data from a Global Field Set Definition Dictionary message payload to the RsslFieldSetDefDb object. rsslClearElementSetDefDb Clears the RsslElementSetDefDb. This must be called before initial use of the object. rsslAddElementSetDefToDb Deep copies the given RsslElementSetDef into the RsslElementSetDefDb. rsslEncodeElementSetDefDictionary Creates a Global Element Set Definition Dictionary message payload from the RsslElementSetDefDb object (refer to Section 5.7). rsslDecodeElementSetDefDictionary Adds data from a Global Element Set Definition Dictionary message payload to the RsslElementSetDefDb object. rsslAllocateFieldSetDefDb Allocates the RsslFieldSetDefDb’s array of RsslFieldSetDef pointers, and deep copies the version information. rsslDeleteFieldSetDefDb Deletes all of the allocated data contained by the RsslFieldSetDefDb. This will delete any data allocated by rsslAllocateFieldSetDefDb and rsslAddFieldSetDefToDb. This will also delete any data allocated by rsslDecodeFieldSetDefDictionary. rsslAllocateElementSetDefDb Allocates the RsslElementSetDefDb’s array of RsslElementSetDef pointers, and deep copies the version information. rsslDeleteElementSetDefDb Deletes all of the allocated data contained by the RsslElementSetDefDb. This will delete any data allocated by rsslAllocateElementSetDefDb and rsslAddElementSetDefToDb. This will also delete any data allocated by rsslDecodeElementSetDefDictionary. Table 49: Dictionary Helper Functions (Continued) 5.12.1 Example: Basic Dictionary Use The following example illustrates basic field and enumerated dictionary loading and unloading. Additional examples of encoding or decoding from domain model can be seen in the example applications provided with the Transport API. /* This sample shows loading field and enumerated dictionaries from a file */ RsslDataDictionary dictionary; /* clear the dictionary before first use/load */ rsslClearDataDictionary(&dictionary); Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 84 Chapter 5 Dictionary Domain /* load field dictionary from file */ if (rsslLoadFieldDictionary(“RDMFieldDictionary”, &dictionary, &errorText) < 0) { printf("\nUnable to load dictionary.\n\tText: %s\n", errorText.data); /* cleanup and exit */ } /* load enumerated dictionary from file */ if (rsslLoadEnumTypeDictionary(“enumtype.def”, &dictionary, &errorText) < 0) { printf("\nUnable to load enum type dictionary.\n\tText: %s\n", errorText.data); /* cleanup and exit */ } /* when users are done, they should unload dictionaries to clean up memory */ if (rsslDeleteDataDictionary(&dictionary) < 0) { printf("\nUnable to delete dictionary.\n); } Code Example 9: Transport API Dictionary Loading Utility Function Use 5.12.2 Example: Dictionary Lookup Using a FieldId This example illustrates a dictionary lookup using a fieldId to determine how to decode the RsslFieldEntry data. This example also cross references an enumerated type (RSSL_DT_ENUM) to use enumerated type dictionary information. For additional examples of encoding or decoding from the domain model, refer to the Transport API’s example applications. /* This sample shows use of a loaded dictionary. This looks up a fieldId to determine how to decode the FieldEntry content. It also demonstrates cross referencing an enumerated type */ RsslDictionaryEntry* dictionaryEntry = NULL; /* used while decoding field list content */ rsslDecodeFieldEntry(&decIter, &fieldEntry) /* look up entry associated with fieldId */ dictionaryEntry = dictionary->entriesArray[fieldEntry.fieldId]; /* return if no entry found */ if (!dictionaryEntry) { printf("\tFid %d not found in dictionary\n", fEntry->fieldId); return; } /* If found, we can access various pieces of information, and use the Type information for further decoding of the field */ switch(dictionaryEntry->rwfType) Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 85 Chapter 5 Dictionary Domain { case RSSL_DT_UINT: rsslDecodeUInt(&decIter, &rsslUInt); break; case RSSL_DT_INT: rsslDecodeInt(&decIter, &rsslInt); break; case RSSL_DT_ENUM: /* enumerated types can be cross referenced with enum dictionary */ rsslDecodeEnum(&decIter, &rsslEnum); /* RsslEnumType contains value, display, and meaning information */ RsslEnumType *pEnumType = getFieldEntryEnumType(dictionaryEntry, rsslEnum); break; /* continued with decoding for other possible types */ } Code Example 10: Transport API Dictionary Utility Function Field and Enum Look Up Example Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 86 Chapter 6 Market Price Domain Chapter 6 Market Price Domain 6.1 Description The Market Price domain provides access to Level I market information such as trades, indicative quotes, and top-of-book quotes. All information is sent as an RsslFieldList. Field-value pairs contained in the field list include information related to that item (i.e., net change, bid, ask, volume, high, low, or last price). Note: RsslGenericMsg(s) are not supported in the MARKET_PRICE Reuters Domain Model. 6.2 Usage 6.2.1 Market Price Request Message A Market Price request message is encoded and sent by OMM consumer applications. The request specifies the name and attributes of an item in which the consumer is interested. To receive updates, a consumer can make a “streaming” request by setting the RSSL_RQMF_STREAMING flag. If the flag is not set, the consumer requests a “snapshot,” and the refresh ends the request. By default, JSON sets the RSSL_RQMF_STREAMING flag to true. To request a snapshot, you must explicitly set the RSSL_RQMF_STREAMING flag to false. To stop updates, a consumer can pause an item (if the provider supports the pause feature) by setting Request.Pause to true. For additional details, refer to the Transport API C Edition Developers Guide. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_MARKET_PRICE == 6 qos Optional. Indicates the QoS at which the consumer wants the stream serviced. If both qos and worstQos are specified, this request can be satisfied by a range of QoS. worstQos Optional. Used with the qos member to define a range of acceptable QoS. When the provider encounters such a range, it should attempt to provide the best QoS it can within that range. worstQos should only be used on services that claim to support it via the SupportsQosRange item in the Source Directory response (refer to Section 4.3.1.1). priorityClass Optional. Indicates the class of a streams priority. priorityCount Optional. Indicates the count associated with a streams priority. extendedHeader Not used. msgKey.serviceId Required. Optional. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service from which the consumer wishes to request the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. Table 50: Market Price Request Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 87 Chapter 6 COMPONENT Market Price Domain DESCRIPTION / VALUE msgKey.nameType Optional. When consuming from Thomson Reuters sources, typically set to RDM_INSTRUMENT_NAME_TYPE_RIC (the “Reuters Instrument Code”). If unspecified, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Required in initial request, otherwise optional. Specifies the name of the requested item. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Optional. When features such as View (RSSL_RQMF_HAS_VIEW) or Batch (RSSL_RQMF_HAS_BATCH) are leveraged, the payload can contain information relevant to that feature. For more detailed information, refer to the Transport API C Edition Developers Guide. Table 50: Market Price Request Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 88 Chapter 6 6.2.2 Market Price Domain Market Price Refresh Message A Market Price Refresh Message is sent by OMM provider and OMM non-interactive provider applications. This message sends all currently available information about the item to the consumer. RsslFieldList in the payload should include all fields that may be present in subsequent updates, even if those fields are currently blank. When responding to a View request, this refresh should contain all fields that were requested by the specified view. If for any reason the provider wishes to send new fields, it must first send an unsolicited refresh with both the new and currently-present fields. Note: All solicited or unsolicited refresh messages in the Market Price domain must be atomic, and have their RSSL_RFMF_CLEAR_CACHE and RSSL_RFMF_REFRESH_COMPLETE flags set to true (the WebSocket API automatically defaults these flags to true). The Market Price domain does not allow for multi-part refresh use. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REFRESH == 2 partNum Not used. domainType Required. RSSL_DMT_MARKET_PRICE == 6 state Required. Includes the state of the stream and data. qos Optional. Specifies the QoS at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. groupId Required. Associates the item with an Item Group (refer to Section 4.3.1.3). permData Optional. Specifies the permission information associated with content on this stream. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. msgKey.nameType should match the msgKey.nameType specified in the request. If unspecified, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. msgKey.flags value of RSSL_MKF_HAS_NAME should be specified. This should match the requested name. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. This should consist of an RsslFieldList containing all fields associated with the item. Table 51: Market Price Refresh Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 89 Chapter 6 6.2.3 Market Price Domain Market Price Update Message A Market Price Update Message is sent by OMM provider and OMM non-interactive provider applications. The Market Price Update Message conveys any changes to an item’s data. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_UPDATE == 4 domainType Required. RSSL_DMT_MARKET_PRICE == 6 updateType Required. Indicates the general content of the update: • RDM_UPD_EVENT_TYPE_UNSPECIFIED == 0 (this is the default setting) • RDM_UPD_EVENT_TYPE_QUOTE == 1 • RDM_UPD_EVENT_TYPE_TRADE == 2 • RDM_UPD_EVENT_TYPE_NEWS_ALERT == 3 • RDM_UPD_EVENT_TYPE_VOLUME_ALERT == 4 • RDM_UPD_EVENT_TYPE_ORDER_INDICATION == 5 • RDM_UPD_EVENT_TYPE_CLOSING_RUN == 6 • RDM_UPD_EVENT_TYPE_CORRECTION == 7 • RDM_UPD_EVENT_TYPE_MARKET_DIGEST == 8 • RDM_UPD_EVENT_TYPE_QUOTES_TRADE == 9 • RDM_UPD_EVENT_TYPE_MULTIPLE == 10 • RDM_UPD_EVENT_TYPE_VERIFY == 11 qos Optional. Specifies the QoS at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. conflationCount Optional. If a provider sends a conflated update, conflationCount specifies the number of updates in the conflation. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. conflationTime Optional. If a provider sends a conflated update, conflationTime specifies the time interval (in milliseconds) over which data is conflated. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. permData Optional. Specifies permissioning information associated with only the contents of this update. extendedHeader Not used. msgKey.serviceId Conditional. msgKey.serviceId is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set to true on the request (by default, the WebSockets API sets RSSL_RQMF_MSG_KEY_IN_UPDATES to true). Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the data. msgKey.serviceId can be left blank if the provider uses a default ID or name. Table 52: Market Price Update Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 90 Chapter 6 COMPONENT Market Price Domain DESCRIPTION / VALUE msgKey.nameType Conditional. msgKey.nameType is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set to true on the request (by default, the WebSockets API sets RSSL_RQMF_MSG_KEY_IN_UPDATES to true). msgKey.nameType should match the name type specified on the request. If msgKey.nameType is unspecified, its value defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Conditional. msgKey.name is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set to true on the request (by default, the WebSockets API sets RSSL_RQMF_MSG_KEY_IN_UPDATES to true). msgKey.name specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. This should consist of an RsslFieldList with any changed data. Table 52: Market Price Update Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 91 Chapter 6 6.2.4 Market Price Domain Market Price Status Message A Market Price Update Message is sent by OMM provider and OMM non-interactive provider applications. It conveys any changes to an item’s data. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_UPDATE == 4 domainType Required. RSSL_DMT_MARKET_PRICE == 6 updateType Required. Indicates the general content of the update: • RDM_UPD_EVENT_TYPE_UNSPECIFIED == 0 • RDM_UPD_EVENT_TYPE_QUOTE == 1 • RDM_UPD_EVENT_TYPE_TRADE == 2 • RDM_UPD_EVENT_TYPE_NEWS_ALERT == 3 • RDM_UPD_EVENT_TYPE_VOLUME_ALERT == 4 • RDM_UPD_EVENT_TYPE_ORDER_INDICATION == 5 • RDM_UPD_EVENT_TYPE_CLOSING_RUN == 6 • RDM_UPD_EVENT_TYPE_CORRECTION == 7 • RDM_UPD_EVENT_TYPE_MARKET_DIGEST == 8 • RDM_UPD_EVENT_TYPE_QUOTES_TRADE == 9 • RDM_UPD_EVENT_TYPE_MULTIPLE == 10 • RDM_UPD_EVENT_TYPE_VERIFY == 11 qos Optional. Specifies the QoS at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. conflationCount Optional. If a provider sends a conflated update, conflationCount specifies the number of updates in the conflation. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. conflationTime Optional. If a provider sends a conflated update, conflationTime specifies the time interval (in milliseconds) over which data is conflated. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. groupId Optional. Associates the item with an Item Group (refer to Section 4.3.1.3). permData Optional. Specifies permissioning information associated with only the contents of this update. extendedHeader Not used. msgKey.serviceId Conditional. msgKey.serviceId is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request (by default, the WebSockets API sets RSSL_RQMF_MSG_KEY_IN_UPDATES to true). Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the data. msgKey.serviceId can be left blank if the provider uses a default ID or name. Table 53: Market Price Update Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 92 Chapter 6 COMPONENT Market Price Domain DESCRIPTION / VALUE msgKey.nameType Conditional. msgKey.nameType is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request (by default, the WebSockets API sets RSSL_RQMF_MSG_KEY_IN_UPDATES to true). msgKey.nameType should match the name type specified on the request. If msgKey.nameType is unspecified, its value defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Conditional. msgKey.name is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request (by default, the WebSockets API sets RSSL_RQMF_MSG_KEY_IN_UPDATES to true). msgKey.name specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. This should consist of an RsslFieldList with any changed data. Table 53: Market Price Update Message Member Use (Continued) 6.2.5 Market Price Post Message If support is specified by the provider, consumer applications can post Market Price data. For more information on posting, refer to the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 93 Chapter 6 6.3 Market Price Domain Data: Market Price Refresh Message / Update Message Payload Market Price data is conveyed as an RsslFieldList, where each RsslFieldEntry corresponds to a piece of information and its current value. The field list should be decoded using its associated Field Dictionary, indicated by the dictionaryId present in the field list. For more information, refer to Section 5.2. For more information on using the RsslFieldList container type, refer to the Transport API C Edition Developers Guide. 6.4 Market Price Sample XML 6.4.1 Market Price Request Message Sample XML Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 82 Chapter 5 Dictionary Domain Figure 15. Market Price Request Message Sample XML Message Layout 6.4.2 Market Price Refresh Message Sample XML Figure 16. Market Price Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 94 Chapter 6 Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 Market Price Domain 95 Chapter 7 Market By Order Domain Chapter 7 Market By Order Domain 7.1 Description The Market By Order domain provides access to Level II full order books. The list of orders is sent in the form of an RsslMap. Each RsslMapEntry represents one order (using the order’s Id as its key) and contains an RsslFieldList describing information related to that order (such as price, whether it is a bid/ask order, size, quote time, and market maker identifier). Note: RsslGenericMsg(s) are not supported for RSSL_DMT_MARKET_BY_ORDER RDMs. 7.2 Usage 7.2.1 Market By Order Request Message A Market By Order request message is encoded and sent by OMM consumer applications. The request specifies the name of the item in which a consumer is interested. To receive updates, the consumer makes a “streaming” request by setting the RSSL_RQMF_STREAMING flag. If the flag is not set, the consumer is requesting a “snapshot,” and the final part of the refresh (i.e., the refresh has the RSSL_RFMF_REFRESH_COMPLETE flag set) indicates all responses have been received for the snapshot. Updates may be received in either case if the refresh has multiple parts. To stop updates, a consumer can pause an item if the provider supports this functionality. For additional details, refer to the Transport API C Edition Developers Guide. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_MARKET_BY_ORDER == 7 qos Optional. Indicates the QoS at which the consumer wants the stream serviced. If both qos and worstQos are specified, this request can be satisfied by a range of qualities of service. worstQos Optional. Used with the qos member to define a range of acceptable Qualities of Service. When encountering such a range, the provider should attempt to provide the best QoS it can within that range. This should only be used on services that claim to support it via the SupportsQosRange item in the Source Directory response (refer to Section 4.3.1.1). priorityClass Optional. Indicates the class of a streams priority. priorityCount Optional. Indicates the count associated with a streams priority. extendedHeader Not used. msgKey.serviceId Required. This should be the ID or name (e.g., “ELEKTRON_DD”) associated with the service from which the consumer wants to request the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. Table 54: Market By Order Request Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 96 Chapter 7 COMPONENT Market By Order Domain DESCRIPTION / VALUE msgKey.nameType Optional. When consuming from Thomson Reuters sources, msgKey.nameType is typically set to RDM_INSTRUMENT_NAME_TYPE_RIC (the “Reuters Instrument Code”). If absent, the Transport API assumes a setting of RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Required in initial request, otherwise optional. Specifies the requested item’s name. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Optional. When features such as View (RSSL_RQMF_HAS_VIEW) or Batch (RSSL_RQMF_HAS_BATCH) are leveraged, the payload can contain information relevant to that feature. For more detailed information, refer to Transport API C Edition Developers Guide. Table 54: Market By Order Request Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 97 Chapter 7 7.2.2 Market By Order Domain Market By Order Refresh Message A Market By Order refresh message is encoded and sent by OMM interactive provider and OMM non-interactive provider applications. A Market By Order refresh may be sent in multiple parts. It is possible for update and status messages to be delivered between parts of a refresh message, regardless of whether the request is streaming or non-streaming. Providers must set the RSSL_RFMF_CLEAR_CACHE flag on the solicited RsslRefreshMsg. For multi-part refreshes, the RSSL_RFMF_CLEAR_CACHE flag must be set on the first part only. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REFRESH == 2 domainType Required. RSSL_DMT_MARKET_BY_ORDER == 7 state Required. The state of the stream and data. partNum Optional. Specifies the part number of a multi-part refresh. qos Optional. Specifies the QoS at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. groupId Required. Associates the item with an Item Group (refer to Section 4.3.1.3). permData Optional. Specifies permission information associated with content on this stream. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. nameType should match the nameType specified in the request. If absent, msgKey.nameType is assumed to be RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. msgKey.flags value of RSSL_MKF_HAS_NAME should be specified and the contents of name should match the requested item’s name. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. An order book is represented by an RsslMap, where each entry (RsslMapEntry) contains information (RsslFieldList) that corresponds to an order. Table 55: Market By Order Refresh Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 98 Chapter 7 7.2.3 Market By Order Domain Market By Order Update Message A Market By Order update message is encoded and sent by OMM interactive provider and OMM non-interactive provider applications. The provider can send an update message to add, update, or remove order information. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_UPDATE == 4 domainType Required. RSSL_DMT_MARKET_BY_ORDER == 7 updateType Required. Indicates the general content of the update. Typically sent as one of the following: • RDM_UPD_EVENT_TYPE_UNSPECIFIED == 0 • RDM_UPD_EVENT_TYPE_QUOTE == 1 seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. conflationCount Optional. If a provider sends a conflated update, conflationCount informs the consumer as to how many updates were included in the conflation. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. conflationTime Optional. If a provider sends a conflated update, conflationTime informs the consumer as to the interval (in milliseconds) over which data was conflated. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. permData Optional. permData contains permissioning information associated only with the contents of this update. extendedHeader Not used. msgKey.serviceId Conditional. msgKey.serviceId is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. msgKey.serviceId specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the data. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Conditional. msgKey.nameType is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. msgKey.nameType must match the name type in the item’s request message (typically RDM_INSTRUMENT_NAME_TYPE_RIC). msgKey.name Optional (Required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request). msgKey.name specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. The order book is represented by an RsslMap, where each map entry (RsslMapEntry) holds information (RsslFieldList) corresponding to an order. Table 56: Market By Order Update Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 99 Chapter 7 7.2.4 Market By Order Domain Market By Order Status Message A Market By Order status message is sent by OMM interactive provider and non-interactive provider applications. This message conveys state change information associated with an item stream. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_STATUS == 3 domainType Required. RSSL_DMT_MARKET_BY_ORDER == 7 state Optional. Specifies the current state information associated with the data and stream. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. groupId Optional. The provider may use this to change the item’s groupId (for details, refer to Section 4.3.1.3). permData Optional. permData specifies any new permissioning information associated with all of the stream’s contents. extendedHeader Not used. msgKey.serviceId Conditional. msgKey.serviceId is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request). msgKey.serviceId specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Conditional. msgKey.nameType is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. msgKey.nameType must match the name type in the item’s request message. If not specified, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional (Required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request). msgKey.name specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 57: Market By Order Status Message Member Use 7.2.5 Market By Order Post Message If support is specified by the provider, consumer applications can post Market By Order data. For more information on posting, refer to the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 100 Chapter 7 7.3 Data 7.3.1 Market By Order Refresh / Update Payload Market By Order Domain The payload of a Market By Order Refresh or Update is an RsslMap. Each RsslMapEntry corresponds to one order, where the entry key is the Order Id. KEY TYPE RSSL_DT_BUFFER, CONTAINER TYPE PERMISSION REQUIRED DATA RSSL_DT_FIELD_LIST Optional RSSL_DT_ASCII_STRING, RSSL_DT_RMTES_STRING Yes DESCRIPTION Contains information on the requested order book. Each RsslMapEntry contains information about a specific order and uses the Order’s ID as its key. Instead of each entry having a copy of the value in its field list, the keyFieldId of the RsslMap can match the fieldId corresponding to the ORDER_ID field. Table 58: Market By Order Map Figure 17. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 101 Chapter 7 7.3.2 Market By Order Domain Summary Data The summaryData of the RsslMap only needs to be present for the first refresh part. Typical fields in the summaryData include: • Permission information (PROD_PERM) • Currency of the orders (CURRENCY) • Trade Units for the precision at which order prices are set (TRD_UNITS) • Market State (MKT_ST_IND) • Identifier of the exchange on which the orders were placed (RDN_EXCHD2) • Price Ranking Rules (PR_RNK_RUL) • Order Ranking Rules (OR_RNK_RUL) • Quote Date (ACTIV_DATE) • RIC of the underlying equity (STOCK_RIC) 7.3.3 RsslMapEntry Contents Each RsslMapEntry contains an RsslFieldList. Each field list contains information about the order. The field list should be decoded using its associated Field Dictionary, indicated by the dictionaryId present in the field list. • For more information, refer to Section 5.2. • For more information about use of the RsslMap and RsslFieldList container types, refer to the Transport API C Edition Developers Guide. The content of each field list typically includes: • Order Price and Side (BID, 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) 7.4 Market By Order Sample XML 7.4.1 Market By Order Request Message Sample XML Figure 18. Market By Order Request Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 102 Chapter 7 7.4.2 Market By Order Domain Market By Order Refresh Message Sample XML Figure 19. Market By Order Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 104 Chapter 8 Market By Price Domain Chapter 8 Market By Price Domain 8.1 Description Market By Price provides access to Level II market depth information. The list of price points is sent in an RsslMap. Each entry represents one price point (using that price and bid/ask side as its key) and contains an RsslFieldList that describes information related to that price point. Note: RsslGenericMsg(s) are not supported for the RSSL_DMT_MARKET_BY_PRICE Reuters Domain Model. 8.2 Usage 8.2.1 Market By Price Request Message A Market By Price request message is encoded and sent by OMM consumer applications. The request specifies the name of an item in which the consumer is interested. To receive updates, a consumer can make a “streaming” request by setting the RSSL_RQMF_STREAMING flag. If the flag is not set, the consumer requests a “snapshot” and the refresh should end the request (updates may be received in either case if the refresh has multiple parts). A consumer can pause an item to stop updates (if the provider supports such functionality). For more information, refer to the Transport API C Edition Developers Guide. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_MARKET_BY_PRICE == 8 qos Optional. Indicates the QoS at which the consumer wants the stream serviced. If both qos and worstQos are specified, this request can be satisfied by a range of QoS. worstQos Optional. Used with qos to define a range of acceptable QoS. When the provider encounters such a range, it should attempt to provide the best QoS possible within that range. This should only be used on services that claim to support it via the SupportsQosRange item in the Source Directory response (for further details, refer to Section 4.3.1.1). priorityClass Optional. Indicates the class of a streams priority. priorityCount Optional. Indicates the count associated with a streams priority. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the requested item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. Typically set to RDM_INSTRUMENT_NAME_TYPE_RIC (the “Reuters Instrument Code”) when consuming from Thomson Reuters sources. If absent, its default value is RDM_INSTRUMENT_NAME_TYPE_RIC. Table 59: Market By Price Request Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 105 Chapter 8 COMPONENT Market By Price Domain DESCRIPTION / VALUE msgKey.name Required in initial request, otherwise optional. Specifies the name of the requested item. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Optional. When features such as View (RSSL_RQMF_HAS_VIEW) or Batch (RSSL_RQMF_HAS_BATCH) are leveraged, the payload can contain information relevant to that feature. For further details, refer to the Transport API C Edition Developers Guide. Table 59: Market By Price Request Message Member Use (Continued) 8.2.2 Market By Price Refresh Message A Market By Price refresh message is encoded and sent by OMM interactive provider and OMM non-interactive provider applications. A Market By Price refresh may be sent in multiple parts. Both update and status messages can be delivered between parts of a refresh message, regardless of streaming or non-streaming request. Providers must set the RSSL_RFMF_CLEAR_CACHE flag on the solicited RsslRefreshMsg. For multi-part refreshes, the RSSL_RFMF_CLEAR_CACHE flag must be set on the first part only. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REFRESH == 2 domainType Required. RSSL_DMT_MARKET_BY_PRICE == 8 state Required. Indicates the state of the stream and data. partNum Optional. Specifies the part number of a multi-part refresh. qos Optional. Specifies the QoS at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. groupId Required. Associates the item with an Item Group (for further information, refer to Section 4.3.1.3). permData Optional. If present, specifies permission information associated with the stream’s content. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. msgKey.nameType should match the msgKey.nameType specified in the request. If absent, this value is assumed to be RDM_INSTRUMENT_NAME_TYPE_RIC. Table 60: Market By Price Refresh Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 106 Chapter 8 COMPONENT Market By Price Domain DESCRIPTION / VALUE msgKey.name Optional. msgKey.flags value of RSSL_MKF_HAS_NAME should be specified, and msgKey.name should match the name specified in the request. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. The order book is represented by an RsslMap, where each entry contains an RsslFieldList which has information about a price point. Table 60: Market By Price Refresh Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 107 Chapter 8 8.2.3 Market By Price Domain Market By Price Update Message A Market By Price update message is encoded and sent by OMM interactive provider and OMM non-interactive provider applications. The provider can send an update message to add, update, or remove price point information. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_UPDATE == 4 domainType Required. RSSL_DMT_MARKET_BY_PRICE == 8 updateType Required. Indicates the general content of the update. Typically sent as one of the following: • RDM_UPD_EVENT_TYPE_UNSPECIFIED == 0 • RDM_UPD_EVENT_TYPE_QUOTE == 1 seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. conflationCount Optional. If a provider sends a conflated update, conflationCount specifies how many updates were included in the conflation. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES to true in the request. conflationTime Optional. If a provider sends a conflated update, conflationTime specifies the time interval (in milliseconds) over which data is conflated. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES to true in the request. permData Optional. Specifies permissioning information for the update’s content. extendedHeader Not used. msgKey.serviceId Conditional. msgKey.serviceId is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Conditional. msgKey.nameType is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. msgKey.nameType should match the msgKey.nameType specified in the item’s request message. If msgKey.nameType is not specified, it uses the default RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Conditional. msgKey.name is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request) Specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. The order book is represented by an RsslMap, where each entry contains an RsslFieldList containing information about a price point. Table 61: Market By Price Update Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 108 Chapter 8 8.2.4 Market By Price Domain Market By Price Status Message A Market By Price status message is encoded and sent by OMM interactive provider and non-interactive provider applications. This message conveys state change information associated with an item stream. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_STATUS == 3 domainType Required. RSSL_DMT_MARKET_BY_PRICE == 8 state Optional. Specifies current state information associated with the data and stream. qos Optional. Specifies the QoS at which the stream is provided. groupId Optional. Specifies the item’s groupId (the provider can use this component to change the item’s groupId). permData Optional. Specifies new permissioning information associated with all contents on the stream. extendedHeader Not used. msgKey.serviceId Optional. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. msgKey.nameType should match the msgKey.nameType specified in the item’s request message. If msgKey.nameType is not specified, it uses the default RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. Specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 62: Market By Price Status Message Member Use 8.2.5 Market By Price Post Message If supported by the provider, consumer applications can post Market By Price data. For more information on posting, refer to the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 109 Chapter 8 8.3 Data 8.3.1 Market By Price Refresh/Update Payload Market By Price Domain The payload of a Market By Price Refresh or Update is an RsslMap. Each price point is contained in an RsslMapEntry which uses the price point and side (buy or sell) as the entry key. KEY TYPE RSSL_DT_BUFFER CONTAINER TYPE PERMISSION DATA RSSL_DT_FIELD_LIST Optional DESCRIPTION Required. Contains information about the known price points. Each RsslMapEntry represents one price point and uses that price (along with the buy/ sell side) as its key. Table 63: Market By Price Map 8.3.2 Summary Data The summaryData of the RsslMap needs to be present only for the first refresh part, which typically includes: • Permission information (PROD_PERM) • Currency of the orders (CURRENCY) • Trade Units for the precision with which order prices are set (TRD_UNITS) • Market State (MKT_ST_IND) • The identifier of the exchange on which the orders were placed (RDN_EXCHD2) • Price Ranking Rules (PR_RNK_RUL) • Quote Date (QUOTE_DATE) 8.3.3 RsslMapEntry Contents The RsslMapEntry key is an RsslBuffer that contains a combination of the price and order side, thus each key is unique within its map. The key should be treated as a single entity and is not meant to be parsed. Each RsslMapEntry houses an RsslFieldList that contains information about the price point. The field list should be decoded using its associated Field Dictionary, indicated by the dictionaryId present in the field list. • For more information on dictionary use, refer to Section 5.2. • For more information about use of the RsslMap and RsslFieldList container types, refer to the Transport API C Edition Developers Guide. The field list typically includes: • Order Price & Side (BID, ASK, or ORDER_PRC and ORDER_SIDE) • Order Size (BIDSIZE, ASKSIZE, or ORDER_SIZE) • Number of aggregated orders (NO_ORD) • Quote Time (QUOTIM_MS) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 110 Chapter 8 • Market By Price Domain A map containing the Market Makers (MMID) and optionally a field list with each of the market makers’ positions at the Order Price point. 8.4 Market By Price Sample XML 8.4.1 Market By Price Request Message Sample XML Figure 20. Market By Price Request Message Sample XML Message Layout 8.4.2 Market By Price Refresh Message Sample XML Figure 21. Market By Price Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 112 Chapter 9 Market Maker Domain Chapter 9 Market Maker Domain 9.1 Description The Market Maker domain provides access to market maker quotes and trade information. The list of market makers is sent in the form of an RsslMap. Each RsslMapEntry represents one market maker (using that market maker’s ID as its key) and contains an RsslFieldList describing information such as that market maker’s bid and ask prices, quote time, and market source. Note: RsslGenericMsg(s) are not supported for the MARKET_MAKER Reuters Domain Model. 9.2 Usage 9.2.1 Market Maker Request Message A Market Maker request message is encoded and sent by OMM consumer applications. The request specifies the name of an item in which the consumer is interested. To receive updates, a consumer can make a “streaming” request by setting the RSSL_RQMF_STREAMING flag. If the flag is not set, the consumer requests a “snapshot,” and the final part of the refresh (i.e., the refresh has the RSSL_RFMF_REFRESH_COMPLETE flag set) indicates all responses have been received for the snapshot. Updates may be received in either case if the refresh has multiple parts. To stop updates, a consumer can pause an item (if the provider supports this functionality). For more information, refer to the Transport API C Edition Developers Guide. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_MARKET_MAKER == 9 qos Optional. Indicates the QoS at which the consumer wants the stream serviced. If both qos and worstQos are specified, this request can be satisfied by a range of QoS. worstQos Optional. Used with qos to define a range of acceptable QoS. If the provider encounters such a range, it should attempt to provide the best possible QoS within that range. This should only be used on services that claim to support it via the SupportsQosRange item in the Source Directory response (for details, refer to Section 4.3.1.1). priorityClass Optional. Indicates the class of a stream’s priority. priorityCount Optional. Indicates the count associated with a stream’s priority. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the requested item. msgKey.serviceId can be left blank if the provider uses a default ID or name. Table 64: Market Maker Request Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 113 Chapter 9 COMPONENT Market Maker Domain DESCRIPTION / VALUE msgKey.nameType Optional. When consuming from Thomson Reuters sources, msgKey.nameType is typically set to RDM_INSTRUMENT_NAME_TYPE_RIC (the “Reuters Instrument Code”). If absent, its value reverts to the default, which is RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Required in initial request, otherwise optional. Specifies the name of the requested item. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Optional. When features such as View (RSSL_RQMF_HAS_VIEW) or Batch (RSSL_RQMF_HAS_BATCH) are leveraged, the payload can contain information relevant to that feature. For more details, refer to Transport API C Edition Developers Guide. Table 64: Market Maker Request Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 114 Chapter 9 9.2.2 Market Maker Domain Market Maker Refresh Message A Market Maker refresh message is encoded and sent by OMM interactive provider and OMM non-interactive provider applications. The Market Maker refresh can be sent in multiple parts. Keep in mind that both update and status messages can be delivered between parts of a refresh message, regardless of streaming or non-streaming request. Providers must set the RSSL_RFMF_CLEAR_CACHE flag on the solicited RsslRefreshMsg. For multi-part refreshes, the RSSL_RFMF_CLEAR_CACHE flag must be set on the first part only. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REFRESH == 2 domainType Required. RSSL_DMT_MARKET_MAKER == 9 state Required. Indicates the state of the stream and data. partNum Optional. Specifies the part number of a multi-part refresh. qos Optional. Specifies the QoS at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. groupId Required. Associates the item with an Item Group (refer to Section 4.3.1.3). permData Optional. Specifies permission information associated with this stream’s content. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. nameType should match the nameType specified in the request. If absent, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. A msgKey.flags value of RSSL_MKF_HAS_NAME should be specified, which should match the requested name. msgKey.filter Not used. msgKey.identifier Not used. Payload Required. The order book is represented by an RsslMap, where each entry contains an RsslFieldList which has information about a market maker. Table 65: Market Maker Refresh Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 115 Chapter 9 9.2.3 Market Maker Domain Market Maker Update Message A Market Maker update message is encoded and sent by OMM interactive provider and OMM non-interactive provider applications. The provider can send an update message to add, update, or remove market maker information. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_UPDATE == 4 domainType Required. RSSL_DMT_MARKET_MAKER == 9 updateType Required. Indicates the general content of the update. Typically sent as one of the following: • RDM_UPD_EVENT_TYPE_UNSPECIFIED == 0 • RDM_UPD_EVENT_TYPE_QUOTE == 1 partNum Not used. qos Optional. Specifies the QoS at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. conflationCount Optional. If a provider sends a conflated update, conflationCount specifies how many updates are in the conflation. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. conflationTime Optional. If a provider sends a conflated update, conflationTime specifies the time interval (in milliseconds) over which data is conflated. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. permData Optional. Specifies permissioning information associated only with the contents of this update. extendedHeader Not used. msgKey.serviceId Conditional. msgKey.serviceId is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. msgKey.serviceId specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Conditional. msgKey.nameType is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. msgKey.nameType must match the name type in the item’s request message (typically RDM_INSTRUMENT_NAME_TYPE_RIC). If absent, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Conditional. msgKey.name is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. msgKey.name specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Table 66: Market Maker Update Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 116 Chapter 9 COMPONENT Payload Market Maker Domain DESCRIPTION / VALUE Required. The order book is represented by an RsslMap, where each entry contains an RsslFieldList which in turn contains information about a market maker. Table 66: Market Maker Update Message Member Use (Continued) 9.2.4 Market Maker Status Message A Market Maker status message is encoded and sent by OMM interactive provider and non-interactive provider applications. This message conveys state change information associated with an item stream. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_STATUS == 3 domainType Required. RSSL_DMT_MARKET_MAKER == 9 state Optional. Specifies current state information associated with the data and stream. qos Optional. Specifies the QoS at which the stream is provided. groupId Optional. The provider can use this component to change the items’ groupId. permData Optional. Specifies new permissioning information associated with all of the stream’s contents. extendedHeader Not used. msgKey.serviceId Optional. msgKey.serviceId specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. msgKey.nameType must match the name type in the item’s request message (typically RDM_INSTRUMENT_NAME_TYPE_RIC). If absent, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. msgKey.name specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 67: Market Maker Status Message Member Use 9.2.5 Market Maker Post Message If the provider supports Market Maker post messages, consumer applications can post Market Maker data. For more information on posting, refer to the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 117 Chapter 9 9.3 Data 9.3.1 Market Maker Refresh/Update Payload Market Maker Domain The payload of a Market Maker Refresh or Update is an RsslMap. Information about each market maker is contained in an RsslMapEntry which uses the market maker ID as its entry key. KEY TYPE RSSL_DT_BUFFER RSSL_DT_ASCII_STRING RSSL_DT_RMTES_STRING CONTAINER TYPE DESCRIPTION RSSL_DT_FIELD_LIST Required. Contains information about known market makers. Each RsslMapEntry identifies one market maker and uses the market maker’s ID as the key. Including permission data is optional. The keyFieldId of the map may be set to the fieldId that corresponds to the MMID or MKT_MKR_ID field, instead of each entry having a copy of the value in its field list. Table 68: Market Maker Map Figure 22. 9.3.2 Summary Data The summaryData of the RsslMap only needs to be present in the first refresh part. Typical fields in the summaryData include: • Permission information (PROD_PERM) • Currency of the orders (CURRENCY) • Trade Units for the precision at which order prices are set (TRD_UNITS) • Identifier of the exchange on which the orders were placed (RDN_EXCHD2) • Market State indicating the state of the market (MKT_ST_IND) • Price ranking rules (PR_RNK_RUL) • Quote Date (QUOTE_DATE) 9.3.3 RsslMapEntry Contents Each RsslMapEntry key is an RsslBuffer, AsciiString, or RmtesString that contains a unique market maker’s ID. Each RsslMapEntry houses an RsslFieldList that contains information about the market maker. The field list should be decoded using its associated Field Dictionary, indicated by the dictionaryId present in the field list. • For more information on dictionary use, refer to Section 5.2. • For more information about use of the RsslMap and RsslFieldList container types, refer to the Transport API C Edition Developers Guide. The field list typically includes: • Bid (BID) • Ask (ASK) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 118 Chapter 9 • 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) 9.4 Market Maker Sample XML 9.4.1 Market Maker Request Message Sample XML Market Maker Domain Figure 23. Market Maker Request Message Sample XML Message Layout 9.4.2 Market Maker Refresh Message Sample XML Figure 24. Market Maker Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 121 Chapter 10 Yield Curve Domain Chapter 10 Yield Curve Domain 10.1 Description The Yield Curve domain shows the relation between the interest rate and the term (time to maturity) associated with the debt of a borrower. The shape of a yield curve can help give an idea of future economic activity and interest rates. Information is sent as an RsslFieldList, where some RsslFieldEntry‘s can contain more complex types such as RsslVector, RsslArray, or RsslElementList. This chapter documents the Yield Curve domain as provided by the ATS. Note: The YIELD_CURVE Reuters Domain Model does not support RsslGenericMsg(s). 10.2 Usage 10.2.1 Yield Curve Request Message A Yield Curve request message is encoded and sent by OMM consumer applications. The request specifies the name and attributes of the curve in which the consumer is interested. To receive updates, the consumer makes a “streaming” request by setting the RSSL_RQMF_STREAMING flag. If the flag is not set, the consumer requests a “snapshot,” and the final part of the refresh (i.e., the refresh has the RSSL_RFMF_REFRESH_COMPLETE flag set) indicates all responses have been received for the snapshot. Updates may be received in either case if the refresh has multiple parts. To stop updates, a consumer can pause an item (if the provider supports the pause feature). For additional details, refer to the Transport API C Edition Developers Guide. COMPONENT DESCRIPTION / VALUE msgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_YIELD_CURVE == 22 qos Optional. Indicates the QoS at which the consumer wants the stream serviced. If both qos and worstQos are specified, this request can be satisfied by a range of QoS. worstQos Optional. Used with the qos member to define a range of acceptable QoS. When the provider encounters such a range, it should attempt to provide the best QoS it can within that range. worstQos should only be used on services that claim to support it via the SupportsQosRange item in the Source Directory response (refer to Section 4.3.1.1). priorityClass Optional. Indicates the class of a streams priority. priorityCount Optional. Indicates the count associated with a streams priority. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the requested item. msgKey.serviceId can be left blank if the provider uses a default ID or name. Table 69: Yield Curve Request Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 122 Chapter 10 COMPONENT Yield Curve Domain DESCRIPTION / VALUE msgKey.nameType Optional. When consuming from Thomson Reuters sources, typically set to RDM_INSTRUMENT_NAME_TYPE_RIC (the “Reuters Instrument Code”). If this is not specified, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Required in initial request, otherwise optional.Specifies the name of the requested item. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Optional. When leveraging such features as View (RSSL_RQMF_HAS_VIEW) or Batch (RSSL_RQMF_HAS_BATCH), the payload can contain information relevant to that feature. For more information, refer to Transport API C Edition Developers Guide. Table 69: Yield Curve Request Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 123 Chapter 10 10.2.2 Yield Curve Domain Yield Curve Refresh Message A Yield Curve Refresh Message is sent by OMM provider and OMM non-interactive provider applications. This message sends all currently available information about the item to the consumer. RsslFieldList in the payload should include all fields that might be present in subsequent updates, even if those fields are currently blank. When responding to a View request, this refresh should contain all fields requested by the specified view. If for any reason the provider wishes to send new fields, it must first send an unsolicited refresh with both the new and currentlypresent fields. Providers must set the RSSL_RFMF_CLEAR_CACHE flag on the solicited RsslRefreshMsg. For multi-part refreshes, the RSSL_RFMF_CLEAR_CACHE flag must be set on the first part only. Warning! Although the payload is an RsslFieldList, some field entries are sent as more complex types such as RsslVector and RsslArray. Encoding and decoding applications should be aware of this and ensure proper handling of these types. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REFRESH == 2 domainType Required. RSSL_DMT_YIELD_CURVE == 22 state Required. Includes the state of the stream and data. partNum Optional. Specifies the part number of a multi-part refresh. qos Optional. Specifies the QoS at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. groupId Required. Associates the item with an Item Group (refer to Section 4.3.1.3). permData Optional. Specifies permission information associated with content on this stream. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. Should match the nameType specified in the request. If this is not specified, nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. msgKey.flags value of RSSL_MKF_HAS_NAME should be specified. This should match the requested name. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. This should consist of an RsslFieldList containing all fields associated with the item. Table 70: Yield Curve Refresh Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 124 Chapter 10 10.2.3 Yield Curve Domain Yield Curve Update Message A Yield Curve Update Message is sent by OMM provider and OMM non-interactive provider applications. It conveys any changes to an item’s data. Warning! Although the payload is an RsslFieldList, some field entries are sent as more complex types such as RsslVector and RsslArray. Encoding and decoding applications should be aware of this and ensure proper handling of these types. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_UPDATE == 4 domainType Required. RSSL_DMT_YIELD_CURVE == 22 updateType Required. Indicates the general content of the update. Typically sent as one of the following: • RDM_UPD_EVENT_TYPE_UNSPECIFIED == 0 • RDM_UPD_EVENT_TYPE_QUOTE == 1 seqNum Optional. A user-specified, item-level sequence number which the application can use to sequence messages in this stream. partNum Not used. conflationCount Optional. If the provider sends a conflated update, conflationCount specifies how many updates are in the conflation. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. conflationTime Optional. If a provider is sending a conflated update, conflationTime specifies the time interval (in milliseconds) over which data is conflated. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES flag in the request. permData Optional. Permissioning information associated with only the contents of this update. extendedHeader Not used. msgKey.serviceId Conditional. msgKey.serviceId is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Conditional. msgKey.nameType is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. Should match the msgKey.nameType specified on the request. If this is not specified, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Conditional. msgKey.name is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. Specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. This should consist of an RsslFieldList with any changed data. Table 71: Yield Curve Update Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 125 Chapter 10 10.2.4 Yield Curve Domain Yield Curve Status Message A Yield Curve status message is encoded and sent by OMM interactive provider and non-interactive provider applications. This message conveys state change information associated with an item stream. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_STATUS == 3 domainType Required. RSSL_DMT_YIELD_CURVE == 22 state Optional. Current state information associated with the data and stream. qos Optional. Specifies the QoS at which the stream is provided. groupId Optional. The provider can use this component to change the item’s groupId. permData Optional. Specifies new permissioning information associated with all contents on the stream. extendedHeader Not used. msgKey.serviceId Optional. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. Should match the msgKey.nameType specified on the request. If this is not specified, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. Specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 72: Yield Curve Status Message Member Use 10.2.5 Yield Curve Domain Post Message If supported by the provider, consumer applications can post Yield Curve data. For more information on posting, refer to the Transport API C Edition Developers Guide. Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 126 Chapter 10 10.3 Data 10.3.1 Yield Curve Refresh/Update Payload Yield Curve Domain The payload of a Yield Curve Refresh or Update is an RsslFieldList. Some RsslFieldEntry contents contain primitive type information to help describe the curve. Examples include the Curve Type (CRV_TYPE), the Algorithm used to calculate the curve (CRV_ALGTHM), and the Interpolation (INTER_MTHD) and Extrapolation (EXTRP_MTHD) methods. Other RsslFieldEntry’s contain more complex information. The more complex entries are broken down into: • Input Entries which define the different input data used to calculate the yield curve. Inputs are represented using nonsorted RsslVector types. Examples of curve inputs would be cash rates (CASH_RATES), future prices (FUTR_PRCS), and swap rates (SWAP_RATES). • Output Entries which define the output of the yield curve calculation. Outputs are represented using non-sorted RsslVector types. An example of curve outputs would be the Yield Curve (YLD_CURVE) itself. • Extra Meta Data (EX_MET_DAT) which provides general data about the yield curve. This is represented using an RsslElementList type. Extra meta data allows users to provide additional curve descriptions without needing to define new fields. Some examples of meta data would be curve creation time or the curve’s owner. Figure 25. Yield Curve Payload Example Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 127 Chapter 10 10.3.2 Yield Curve Domain Summary Data For RsslVector types, summaryData can be included to provide information specific to the RsslVector‘s contents. Any summaryData needs to be present only for the first refresh part that contains the RsslVector. Typical summaryData fields include tenors (TENORS). 10.3.3 Yield Curve Input and Output Entries Each RsslVectorEntry houses an RsslFieldList that contains specific information about the respective input or output. The field list should be decoded using its associated Field Dictionary, indicated by the dictionaryId present in the field list. • For more information on dictionary use, refer to Section 5.2. • For more information about use of the RsslVector and RsslFieldList container types, refer to the Transport API C Edition Developers Guide. The following table contains additional information about input and output entries (all of which are of the RSSL_DT_VECTOR container type with a container entry type of RSSL_DT_FIELD_LIST). NAME FIELD NAME TYPE DESCRIPTION Cash Rates CASH_RATES Input Contains cash rate data used to calculate the yield curve output. This typically includes information like settlement date (CASH_SDATE), maturity date (CASH_MDATE), and other related fields. Future Prices FUTR_PRCS Input Contains future pricing data used to calculate the yield curve output; typically including data such as settlement date (FUTR_SDATE), maturity date (FUTR_MDATE), and other related fields. Swap Rates SWAP_RATES Input Contains swap rate data used to calculate the yield curve output; typically including data such as settlement date (SWAP_SDATE), maturity date (SWAP_MDATE), swap rate value (SWAP_RATE_VAL), and roll date (SWAP_RDATE). Spread Rates SPRD_RATES Input Contains spread rate data used to calculate yield curve output; typically including data such as spread frequency (SPRD_FREQ), maturity date (SPRD_MDATE), spread rate (SPRD_RATE), and roll date (SPRD_RDATE). Yield Curve YLD_CURVE Output Contains calculated Yield Curve data; typically including data such as zero rate (YCT_ZRATE), forward rate (YCT_FWRATE), and discount factor (YCT_DISFAC). Table 73: Yield Curve Inputs and Outputs 10.4 When an application consumes Yield Curve data, the dictionary used by the application must contain certain required FIDs. For further details, Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 128 Chapter 10 10.5 Yield Curve Sample XML 10.5.1 Yield Curve Request Message Sample XML Yield Curve Domain Figure 26. Yield Curve Request Message Sample XML Message Layout 10.5.2 Yield Curve Refresh Message Sample XML Figure 27. Yield Curve Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 131 Chapter 11 Symbol List Domain Chapter 11 Symbol List Domain 11.1 Description The Symbol List domain provides access to a set of symbol names, typically from an index, service, or cache. Content is encoded as an RsslMap, with each symbol represented by a map entry and where the symbol name is the entry key. An entry’s payload is optional, but when present the payload is an RsslFieldList or RsslElementList that contains additional cross-reference information such as permission information, name type, or other venue-specific content. Note: RsslGenericMsg(s) are not supported for SYMBOL_LIST Reuters Domain Model. 11.2 Usage 11.2.1 Symbol List Request Message A Symbol List request message is encoded and sent by OMM consumer applications. The consumer can make a streaming request (set RSSL_RQMF_STREAMING) to receive updates, typically associated with item additions or removals from the list. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REQUEST == 1 domainType Required. RSSL_DMT_SYMBOL_LIST == 10 qos Not used. worstQos Not used. priorityClass Optional. Specifies the class of a stream’s priority. priorityCount Optional. Specifies the count associated with a stream’s priority. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the requested item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. msgKey.nameType should match name type specified in the request. When consuming from Thomson Reuters sources, msgKey.nameType is typically set to RDM_INSTRUMENT_NAME_TYPE_RIC (the “Reuters Instrument Code”). If absent, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Required in initial request, otherwise optional. Specifies the name of the requested item. msgKey.filter Not used. msgKey.identifier Not used. Table 74: Symbol List Request Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 132 Chapter 11 Symbol List Domain COMPONENT DESCRIPTION / VALUE msgKey.attrib Not used. Payload Optional. When leveraging such features as View (RSSL_RQMF_HAS_VIEW), Batch (RSSL_RQMF_HAS_BATCH), or behaviors related to the Symbol List Request, the payload can contain information relevant to that feature. For more detailed information, refer to Transport API C Edition Developers Guide. Table 74: Symbol List Request Message Member Use (Continued) Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 133 Chapter 11 11.2.2 Symbol List Domain Symbol List Refresh Message A Symbol List refresh Message is sent by OMM provider and OMM non-interactive provider applications. This message sends a list of item names to the consumer. A Symbol List refresh can be sent in multiple parts. Update and status messages can be delivered between parts of a refresh message, regardless of streaming or non-streaming request. Providers must set the RSSL_RFMF_CLEAR_CACHE flag on the solicited RsslRefreshMsg. For multi-part refreshes, the RSSL_RFMF_CLEAR_CACHE flag must be set on the first part. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_REFRESH == 2 domainType Required. RSSL_DMT_SYMBOL_LIST == 10 state Required. Indicates the state of the stream and data. partNum Optional. Specifies the part number of a multi-part refresh. qos Not used. Optional. Specifies the quality of service at which the stream is provided. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. groupId Required. Associates the item with an Item Group (refer to Section 4.3.1.3). permData Optional. Specifies the permission information associated with content on this stream. extendedHeader Not used. msgKey.serviceId Required. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. nameType should match the nameType specified in the request. If absent, it is assumed to be RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. A msgKey.flags value of RSSL_MKF_HAS_NAME should be specified, which should match the requested name. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. The payload contains an RsslMap where each entry represents an item in the list. Each map entry contains an RsslFieldList or RsslElementList with additional info about that item. Table 75: Symbol List Refresh Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 134 Chapter 11 11.2.3 Symbol List Domain Symbol List Update Message A Symbol List Update Message is sent by OMM provider and OMM non-interactive provider applications. It adds or removes items from the list. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_UPDATE == 4 domainType Required. RSSL_DMT_SYMBOL_LIST == 10 qos Not used. Optional. Specifies the quality of service at which the stream is provided. updateType Not used. seqNum Optional. A user-specified, item-level sequence number which can be used by the application for sequencing messages within this stream. conflationCount Not used. Optional. If a provider sends a conflated update, conflationCount specifies how many updates are in the conflation. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES is set to true in the request. conflationTime Not used. Optional. If a provider sends a conflated update, conflationTime specifies the time interval (in milliseconds) over which data is conflated. The consumer indicates interest in this information by setting the RSSL_RQMF_CONF_INFO_IN_UPDATES is set to true in the request. permData Optional. Specifies the permission information associated with only the contents of this update. extendedHeader Not used. msgKey.serviceId Conditional. msgKey.serviceId is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Conditional. msgKey.nameType is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. Set this to match the msgKey.nameType in the item’s request message (typically RDM_INSTRUMENT_NAME_TYPE_RIC). If absent, it is assumed to be RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Conditional. msgKey.name is required if RSSL_RQMF_MSG_KEY_IN_UPDATES was set on the request. Specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Required. The payload contains an RsslMap, where each entry represents an item in the list. Each map entry contains an RsslFieldList or RsslElementList with additional information about that item. Table 76: Symbol List Update Message Member Use Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 135 Chapter 11 11.2.4 Symbol List Domain Symbol List Status Message A Symbol List status message is encoded and sent by OMM interactive provider and non-interactive provider applications. This message conveys state change information associated with an item stream. COMPONENT DESCRIPTION / VALUE MsgClass Required. RSSL_MC_STATUS == 3 domainType Required. RSSL_DMT_SYMBOL_LIST == 10 state Optional. Current state information associated with the data and stream. qos Not used. Optional. Specifies the quality of service at which the stream is provided. groupId Optional. The provider can use this to change the item’s groupId. permData Optional. Specifies new permissioning information associated with the stream’s contents. extendedHeader Not used. msgKey.serviceId Optional. Specifies the ID or name (e.g., “ELEKTRON_DD”) of the service that provides the item. msgKey.serviceId can be left blank if the provider uses a default ID or name. msgKey.nameType Optional. msgKey.nameType should match the name type specified on the request. If it is not specified, msgKey.nameType defaults to RDM_INSTRUMENT_NAME_TYPE_RIC. msgKey.name Optional. Specifies the name of the item being provided. msgKey.filter Not used. msgKey.identifier Not used. msgKey.attrib Not used. Payload Not used. Table 77: Symbol List Status Message Member Use 11.3 Data 11.3.1 Symbol List Request Payload A consumer requesting a Symbol List stream may also request additional behaviors from a supporting provider. To do so, the payload of its RsslRequestMsg must contain an RsslElementList list that includes an RsslElementEntry. The entry contains an RsslElementList, in which the consumer encodes entries to request the desired behaviors. The consumer should ensure that the provider supports the requested behavior by checking the Login Refresh sent by the provider. For more information, refer to Section 3.2.4. ELEMENT NAME :SymbolListBehaviors TYPE RsslElementList REQUIRED No DESCRIPTION Describes the enhanced symbol list behaviors the consumer requests. Table 78: Symbol List Behaviors Element Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 136 Chapter 11 11.3.2 Symbol List Domain Symbol List Data Streams A Consumer can request that a provider open data streams for the items included in a Symbol List Refresh or Update. Because data streams are opened by the Provider, the Consumer should expect the Provider to use negative streamId values. To request data streams in this manner, include the following entry in the RsslElementList of the :SymbolListBehaviors entry: ELEMENT NAME :DataStreams TYPE RSSL_DT_UINT REQUIRED DEFAULT No 0x0 RANGE / EXAMPLE 0x1 DESCRIPTION Indicates whether the consumer application is requesting that the provider open data streams for items present in the Symbol List. The following flags are defined: • • • 0x0: The provider should not open any data streams. 0x1: The provider should open streams for items as they are added to the symbol list. 0x2: The provider should send non-streaming responses as items are added or updated in the symbol list. Table 79: Symbol List Behaviors Element Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 137 Chapter 11 11.3.3 Symbol List Domain Symbol List Refresh/Update Payload The Symbol List payload is an RsslMap. The provider may include summaryData that includes the domainType and nameType associated with each entry. Each RsslMapEntry key is the item’s name. The entry’s payload can be empty, contain an RsslFieldList, or contain an RsslElementList, either of which can contain additional information (i.e., permission data and cross-reference information). This information should not update frequently. An RsslFieldList typically includes the fields: • PROV_SYMB (3422): Contains the original symbol as provided by the exchange • PROD_PERM (1): Stores permission information KEY TYPE CONTAINER TYPE RSSL_DT_BUFFER RSSL_DT_NO_DATA RSSL_DT_ASCII_STRING RSSL_DT_FIELD_LIST PERMISSION REQUIRED DATA Optional Yes DESCRIPTION Contains specific information about an item contained in the list. RSSL_DT_RMTES_STRING RSSL_DT_ELEMENT_LIST Table 80: Symbol List Refresh/Update Map 11.4 Symbol List Sample XML 11.4.1 Symbol List Request Message Sample XML Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 129 Chapter 10 Yield Curve Domain Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 130 Chapter 10 Yield Curve Domain Figure 28. Symbol List Request Message Sample XML Message Layout 11.4.2 Symbol List Refresh Message Sample XML Figure 29. Symbol List Refresh Message Sample XML Message Layout Transport API 3.2.x C Edition – Developers Guide ETAC320UMRDM.180 139 Appendix A RDMUpdateEventTypes UPDATE EVENT TYPE VALUE DESCRIPTION RDM_UPD_EVENT_TYPE_UNSPECIFIED 0 Event type of this update is not specified. RDM_UPD_EVENT_TYPE_QUOTE 1 The update message contains quote information. RDM_UPD_EVENT_TYPE_TRADE 2 The update message contains trade information. RDM_UPD_EVENT_TYPE_NEWS_ALERT 3 The update message contains an alert for news information. RDM_UPD_EVENT_TYPE_VOLUME_ALERT 4 The update message contains an alert for volume information. RDM_UPD_EVENT_TYPE_ORDER_INDICATION 5 The update message contains an order indication. RDM_UPD_EVENT_TYPE_CLOSING_RUN 6 The update message is a closing run, intended to reinitialize content between trading days or sessions. RDM_UPD_EVENT_TYPE_CORRECTION 7 The update message contains a correction to previously delivered data. RDM_UPD_EVENT_TYPE_MARKET_DIGEST 8 The update message is a market digest. RDM_UPD_EVENT_TYPE_QUOTES_TRADE 9 The update message contains both trade and quote information. RDM_UPD_EVENT_TYPE_MULTIPLE 10 The update message has multiple update types contained in this event. RDM_UPD_EVENT_TYPE_VERIFY 11 The update message is provided for applications to verify content with the system. Table 1: RDMUpdateEventTypes Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 140 Appendix B Revision History For a list of changes in the Transport API / UPA 7.X documentation, refer to the 7.4 UPA Java Edition and 7.6.1 UPA C++ Edition RDM Usage Guides. RELEASE REVISIONS 3.0.2 • Added update event type values and their descriptions as an Appendix. • General grammar / typo fixes. • Changed the range for the SupportOptimizedPauseResume element. • Corrected some information in Section 4.3.1. 3.0 • Correct cross references referring to ‘Section 0’’ • Add content for Yield Curve domain representation • Indicate that msgKey.name is optional on requests (though required on initial request) and refresh messages. Table 2: Document Revision History Transport API 3.2.x C Edition – RDM Usage Guide ETAC320UMRDM.180 141 © 2015 - 2018 Thomson Reuters. All rights reserved. Republication or redistribution of Thomson Reuters content, including by framing or similar means, is prohibited without the prior written consent of Thomson Reuters. 'Thomson Reuters' and the Thomson Reuters logo are registered trademarks and trademarks of Thomson Reuters and its affiliated companies. Any third party names or marks are the trademarks or registered trademarks of the relevant third party. Document ID: ETAC320UMRDM.180 Date of issue: 27 April 2018
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.6 Linearized : No Author : U0116273 Create Date : 2018:04:20 12:17:18Z Modify Date : 2018:04:20 15:21:35-05:00 Language : en Tagged PDF : Yes XMP Toolkit : Adobe XMP Core 5.4-c006 80.159825, 2016/09/16-03:31:08 Producer : Acrobat Distiller 11.0 (Windows) Creator Tool : FrameMaker 2015.1 Metadata Date : 2018:04:20 15:21:35-05:00 Format : application/pdf Title : ETAC_RDMUsageGuide.book Creator : U0116273 Document ID : uuid:d7e72f7b-5ffd-4ffb-a83e-1acab9db56ee Instance ID : uuid:0c21baeb-3acc-4bb5-81fb-2e2b40705327 Page Mode : UseOutlines Page Count : 151EXIF Metadata provided by EXIF.tools