Overview
The broker queue data is available in Refinitiv Real-time feed and can be retrieved by Refinitiv's APIs. In this article, we're going to retrieve the data of Hong Kong Stock Exchange Broker Queue Page by using Refinitiv Real-time SDK (RTSDK): Enterprise Message API (EMA) – Java to create the consumers and use them to subscribe to the data we’re interested “Broker Information” to create mapping between Broker ID and Broker Name/Broker Short Name and the data of “Broker Queue” that contains the broker ID of brokers in the order queue with orders of the best bid/ask price minus/plus 'n' spread(s).
A screenshot of the broker queue data
Refinitiv Real-Time SDK APIs: Enterprise Message API - Java
In this article, we use Enterprise Message API (EMA API) which is a part of Refinitiv Real-Time SDK APIs (RTSDK APIs) - Java Edition to connect to a deployed Refinitiv Real-Time Distribution System (RTDS)
The Refinitiv Real-Time SDK (RTSDK) This SDK encompasses these open-source Real-Time APIs: Enterprise Message API (EMA) and Enterprise Transport API (ETA). This SDK is available for download in the download section and contains pre-built libraries on support platforms and compilers. This SDK is also available on GitHub with instructions to build the libraries.
- The Enterprise Message API (EMA) is an ease-of-use, open-source, OMM API. EMA is designed to provide clients with the rapid development of applications, minimizing lines of code and providing a broad range of flexibility. It provides flexible configuration with default values to simplify use and deployment. EMA is written on top of the Enterprise Transport API (ETA) utilizing the Value Added Reactor and Watchlist.
- The Enterprise Transport API (ETA) is an open-source Refinitiv low-level Transport and OMM encoder/decoder API. It is used by the Refinitiv Real-Time Distribution Systems and Refinitiv Real-Time for the optimal distribution of OMM/RWF data and allows applications to achieve the highest performance, highest throughput, and lowest latency. ETA fully supports all OMM constructs and messages.
The RTSDK currently supports Java and C++ programming languages. For more detail, you may check the resources below
Prerequisite
To be able to execute this example code, the below are required.
- Real-Time-SDK-2.0.7.L1.java
- JaveSE-1.8.
- Deployed RTDS server
- Code editor (Eclipse)
Method
Because data in the broker queue contains only the Broker ID, not the Broker Name, hence, to make the output more detailed and easier to understand, we’re going to retrieve the Broker Name and Short Name of each Broker ID from the mapping we created with the message retrieved from Broker Information RICs (such as HKBK02, HKBK03, …, HKBK50 for Hongkong’s one)
That’s why we’re going to have two types of clients to retrieve the Broker Information (to create the mapping of Broker ID and Broker Name/Short Name) and to retrieve the Broker Queue. First, we're going to subscribe to the Broker Information RICs. Then create a mapping (HashMap) between the Broker ID and Broker Name/Short Name with the messages received from Refinitiv Real-Time data feed by subscribing to the RIC of the Broker Queue Page. Let’s talk about the details of these two steps!
Step 1) Create Broker Information mapping
First, to create the mapping of Broker ID and Broker Names with the data retrieved from Refinitiv Real-time data feed. In this article, we’re focusing on Hong Kong Equities.
You can look up the broker's information via HKBK<xx> page (e.g. HKBK01, HKBK02...)
The data in broker information that we're interested in is contained in fields named below (ROW80_1 - ROW80_25)
- HKBK01 is the page of the Broker ID Code Index of HK Stocks – Broker’s Information.
- HKBK02 - HKBK50 are pages containing the Broker IDs and their Names. The ranges of Broker IDs on each page are listed on the HKBK01 page in the fields below.
- ROW80_1 The title of the Broker's information
- ROW80_2 is the header of the Broker's information
- ROW80_3 - ROW80_24 Broker's information data
- ROW80_25 the footer, consists of the text BROKER ID CODE INDEX with a link to the previous page and a link to the country’s equities menu
Here's a screenshot of the HKBK02 page
Note: An HK/CHAR1 page will give you a basic RIC name convention of the retrieval codes for HK Equities information. Including stock exchange RICs and Brokerage Characters. For example,
If I'd like to get a RIC of Power Assets Holdings Ltd's Broker Queue Page whose stock code is 0006. Broker Queue Page (Level 2 RIC) is Stock Code + bk, which is 0006bk. Then for the stock exchange code, as it said the Broker Queue Page is Level 2 RIC, and the stock exchanges code for Hong Kong Stock Exchange Level 2 RIC is .HKd. Hence, the retrieval code for this is 0006bk.HKd.
Step 2) Print the table of the Broker Queue Page with Broker Information
Next, to print the table of the Broker Queue Page with Broker Names, we’re retrieving the data of the Broker Queue Page and then, use the mapping created in the previous step to show the Broker Name of each Broker ID in the broker queue data.
- Retrieving the data from the Broker Queue page
- Each 4-digit numeric number represents the broker ID of brokers in the order queue with orders of the best bid/ask price minus/plus 'n' spread(s). Read the order queue from the left column vertically. "+1s,-2s,+3s etc" represent the spread. The brokers' Broker ID after e.g. '-1s' are brokers with the best price minus one spread, after '-2s' are brokers with best price minus two spreads.
A screenshot of the Broker Queue page is below
To retrieve the Broker Queue Page, here we're interested in Field IDs 316 to 326 (ROW80_2 - ROW80_12) which contain the list of Broker IDs in both BID and ASK sides.
As the format of the broker Queue data is 8 columns of the Broker ID list, to show the Broker Names, we are going to convert it to the list of Broker IDs and Names. For example, like the format below
- Then we're printing the Broker Queue with the Broker Names looked up from the Broker Information HashMap created in the previous step. (see the result at the bottom of this article)
Now, after we know what needs to be done, let’s check the design of this application.
Application Design
Step 1) Create Broker Information mapping
First, we create the classes Broker Queue and Broker to store the Broker Queue and Broker Information respectively. The value stored in each parameter is as the below
Then, we implement two application clients (Broker ID Client and Broker Queue Client) to retrieve the different types of data implementing the OMM Consumer Client. Let's look into what has been implemented in each client.
The first one is the Broker ID Client Class, which is implemented to retrieve the data of Broker Information and create the mapping (Hash Map) of Broker Information (Broker ID and Broker Name/Short Name). This client contains the parameters
- brokerInfoMapping: create a mapping to store Broker Information
- brokerInfoMappingStatus: create a mapping to check the Broker Info mapping creation status of each Broker Info Page RIC if it's ready. (The status of each RIC is set to ready when the Refresh Message is processed.
- With the isReady method that used to check if all the Broker Info Page RICs are already processed.
and it handles each type of message returned from the real-time feed as below
- Refresh Message: Decode the data returned. Plus, to make sure that the Broker Information is ready for the next step. The mapping between RIC and its message status identifies if the data is already received.
- Update Message: No update is expected as we only use the Refresh one to get the Broker ID/Name/Short Name. Hence, nothing is to be implemented here.
- Method Parse Broker ID: There’s a case when String returned represents more than one number, which can be processed by checking the delimiter(s) in the String. The format of this string is, starting with the first number then the delimiter followed by the last digit of the next number, the delimiter(s) in the String shows how to process the Broker ID list:
- Slash (/): Iterate from the start number to the number whose last digit matched the digit after the delimiter.
- Comma (,): The start number and the number with the same last digit as the digit after the delimiter.
For example,
| String returned | Represent the numbers | Final Broker IDs list |
| 1234 | 1234 | 1234 |
| 1234,8 | 1234 and 1238 | 1234, 1238 |
| 1234/7 | 1234 to 1237 | 1234, 1235, 1236, 1237 |
| 1234/7,9 | 1234 to 1237 and 1239 | 1234, 1235, 1236, 1237, 1239 |
| 1231/4,6/8 | 1231 to 1234 and 1236 to 1238 | 1231, 1232, 1233, 1234, 1236, 1237, 1238 |
The flow's flowchart is below
Step 2) Print the table of the Broker Queue Page with Broker Information
Another client, BrokerQueueClient Class is implemented to print the table of the Broker Queue Page with Broker Names, we’re retrieving the data of the Broker Queue Page and then, use the mapping created in the previous step (with BrokerIDClient) to show the Broker Names of each Broker ID in the broker queue data.
The source code of this part to retrieve and parse the Broker Queue Page data is taken from the article How to parse page-based data using Refinitiv Real-time SDK Java, feel free to check it for more detail on this part. Then after we have the Broker Queue Page data, we process it with the methods:
- brokerQueueObject: create a mapping to store Broker Queue Page
- brokerInformation: is assigned with the BrokerInfoMapping HashMap of BrokerIDClient after the brokerInfoMappingStatus of all Broker Info Page RICs are ready (RIC data is processed).
- pageMap: a map that keeps field ID as a key with RmtesBuffer
More detail on the pageMap mapping and how each message type is handled can be found in the article How to parse page-based data using Refinitiv Real-time SDK Java. However, the decode method in this client is modified to suit our use case by rearranging the 8 columns of Broker ID in the queue to a column of Broker ID so it could be printed together with other information: level (spread), side (BID/ASK), Broker Name, Broker Short Name. Then printing the Broker Queue table out as a formatted String.
Regarding the main function, step of the application is below (Please note that you can use config file instead of hardcoding the config.
For example , you may check this article Enterprise Message API (EMA) - Configuration Overview
Step 1) Retrieve Broker Information Data (output is a mapping of Broker ID, Broker Names)
public static void main(String[] args) {
OmmConsumer consumer = null;
try {
// [ Step 1)] Retrieve Broker Information Data (output is a mapping of Broker ID, Broker Names)
// set the broker RIC Name (Hong Kong) and the RIC length. In this case we'd like to get HKBK02, HKBK03, ..., HKBK49, HKBK50
String brokerRicName = "HKBK";
int brokerInfoLen = 50;
String[] brokerInfoList = returnBrokerInfoPageList(brokerRicName, brokerInfoLen);
// create a client of broker queue
BrokerQueueClient brokerQueueClient = new BrokerQueueClient();
consumer = EmaFactory.createOmmConsumer(
EmaFactory.createOmmConsumerConfig().host("192.168.1.1:14002").username("user"));
BrokerIDClient brokerIDClient = new BrokerIDClient();
// To filter only selected field (example code that is useful, you may check these example files: 360_MP_View, 370 MP_Batch)
// Prepare multiple field IDs in an OmmArray
OmmArray array = EmaFactory.createOmmArray();
array.fixedWidth(2);
// create a client of broker Info (to get only specified fields, which are fields with Broker Information data) [View]
for (int i = 317; i <= 338; i++) {
array.add(EmaFactory.createOmmArrayEntry().intValue(i));
}
// Prepare multiple RICs in an OmmArray [Batch]
OmmArray arrayI = EmaFactory.createOmmArray();
for (String brokerInfo : brokerInfoList) {
arrayI.add(EmaFactory.createOmmArrayEntry().ascii(brokerInfo));
// Add the Broker ID as a key of Hashmap and status if the mapping has been done properly on each Broker Info Page RIC
// initial status is False (it'll be updated to True after the mapping of each RIC is finished)
brokerIDClient.brokerInfoMappingStatus.put(brokerInfo, false);
}
// Combine both Batch and View and add them to ElementList
ElementList batchView = EmaFactory.createElementList();
batchView.add(EmaFactory.createElementEntry().array(EmaRdm.ENAME_BATCH_ITEM_LIST, arrayI));
batchView.add(EmaFactory.createElementEntry().uintValue(EmaRdm.ENAME_VIEW_TYPE, 1));
batchView.add(EmaFactory.createElementEntry().array(EmaRdm.ENAME_VIEW_DATA, array));
// Register a Request Message of the Broker Info
// add Batch and View Request to the Request
consumer.registerClient(
EmaFactory.createReqMsg().serviceName("ELEKTRON_DD").payload(batchView).interestAfterRefresh(false),
brokerIDClient);
Step 2) Retrieve Broker Queue and print the data with Broker Info into the console (an example code output is below)
// Wait until all the Broker information mapping is created
while (!brokerIDClient.isReady()) {
Thread.sleep(1000);
}
// [ Step 2)] Retrieve Broker Queue and print the data with Broker Info into the console (an example code output is below)
// Row BrokerID Level Side Broker Name Broker Short Name
// 1 1836 0 BID INSTINET PACIFIC LTD INSTINET PACIFI
// 2 8578 0 BID HSBC SECURITIES BROKERS (ASIA) LTD HSBC SEC
// set the Broker Information Mapping (copy this variable from broker queue client to broker ID client)
brokerQueueClient.brokerInformation = brokerIDClient.brokerInfoMapping;
// Register a Request Message of the Broker Queue
consumer.registerClient(EmaFactory.createReqMsg().serviceName("ELEKTRON_DD").name("0006bk.HKd"), brokerQueueClient,
0);
Thread.sleep(30000); // API calls onRefreshMsg(), onUpdateMsg() and onStatusMsg()
} catch (InterruptedException | OmmException excp) {
System.out.println(excp.getMessage());
} finally {
if (consumer != null)
consumer.uninitialize();
}
}
Here's an output of the code printed out to the console, consisting of Broker ID, Level (spread), Side (BID/ASK), Broker Name, and Broker Short Name.
Row BrokerID Level Side Broker Name Broker Short Name
1 1196 0 BID CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
2 1196 1 BID CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
3 8914 2 BID BOCI SECURITIES LTD BOCI
4 6998 2 BID CHINA INVESTMENT INFORMATION SERVICES LIMITED CHINA INVESTMEN
5 2311 2 BID HANG SENG SECURITIES LTD HANG SENG
6 1196 2 BID CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
7 7572 3 BID EMPEROR SECURITIES LTD EMPEROR
8 1196 3 BID CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
9 2040 3 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
10 4373 3 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
11 4373 3 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
12 2311 4 BID HANG SENG SECURITIES LTD HANG SENG
13 1799 4 BID BRIGHT SMART SEC INT (H.K.) LTD BRIGHT SMART
14 8577 4 BID HSBC SECURITIES BROKERS (ASIA) LTD HSBC SEC
15 1677 4 BID CHINA TONGHAI SECURITIES LIMITED CHINA TONGHAI S
16 1196 4 BID CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
17 2040 4 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
18 4373 4 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
19 2077 5 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
20 6387 5 BID MORGAN STANLEY HONG KONG SECURITIES LTD MORGAN STANLEY
21 1196 5 BID CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
22 2040 5 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
23 4373 5 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
24 4373 5 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
25 8467 6 BID FUTU SECURITIES INTERNATIONAL (HONG KONG) LIM FUTU SECURITIES
26 1799 6 BID BRIGHT SMART SEC INT (H.K.) LTD BRIGHT SMART
27 1799 6 BID BRIGHT SMART SEC INT (H.K.) LTD BRIGHT SMART
28 8577 6 BID HSBC SECURITIES BROKERS (ASIA) LTD HSBC SEC
29 8574 6 BID HSBC SECURITIES BROKERS (ASIA) LTD HSBC SEC
30 2079 6 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
31 6387 6 BID MORGAN STANLEY HONG KONG SECURITIES LTD MORGAN STANLEY
32 4375 6 BID BARCLAYS CAPITAL ASIA LTD BARCLAYS
33 1196 6 BID CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
34 8550 6 BID ABN AMRO CLEARING HONG KONG LTD ABN AMRO
35 4373 0 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
36 4373 0 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
37 4373 0 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
38 9069 0 ASK UBS SECURITIES HONG KONG LTD UBS SEC
39 6387 0 ASK MORGAN STANLEY HONG KONG SECURITIES LTD MORGAN STANLEY
40 6387 0 ASK MORGAN STANLEY HONG KONG SECURITIES LTD MORGAN STANLEY
41 6387 0 ASK MORGAN STANLEY HONG KONG SECURITIES LTD MORGAN STANLEY
42 2075 0 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
43 2310 1 ASK HANG SENG SECURITIES LTD HANG SENG
44 2077 1 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
45 1196 1 ASK CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
46 8550 1 ASK ABN AMRO CLEARING HONG KONG LTD ABN AMRO
47 4373 1 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
48 2040 1 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
49 4373 1 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
50 2428 1 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
51 5344 2 ASK J.P. MORGAN BROKING (HONG KONG) LTD J.P. MORGAN
52 4375 2 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
53 8130 2 ASK BOCI SECURITIES LTD BOCI
54 1196 2 ASK CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
55 4373 2 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
56 2042 2 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
57 4373 2 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
58 4373 2 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
59 2075 2 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
60 5342 2 ASK J.P. MORGAN BROKING (HONG KONG) LTD J.P. MORGAN
61 5838 3 ASK DBS VICKERS (HONG KONG) LTD DBS VICKERS
62 6387 3 ASK MORGAN STANLEY HONG KONG SECURITIES LTD MORGAN STANLEY
63 6387 3 ASK MORGAN STANLEY HONG KONG SECURITIES LTD MORGAN STANLEY
64 1196 3 ASK CREDIT SUISSE SECURITIES (HONG KONG) LTD CREDIT SUISSE
65 2042 3 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
66 4373 3 ASK BARCLAYS CAPITAL ASIA LTD BARCLAYS
67 1292 4 ASK CMB INTERNATIONAL SECURITIES LTD CMB
68 5838 4 ASK DBS VICKERS (HONG KONG) LTD DBS VICKERS
69 5339 4 ASK J.P. MORGAN BROKING (HONG KONG) LTD J.P. MORGAN
70 5346 4 ASK J.P. MORGAN BROKING (HONG KONG) LTD J.P. MORGAN
Summary
Broker Queue data can be used as information about the broker and the price it sells/buys the equities. In this article, we map the Broker ID with the Broker Names to provide more information and make it easier to understand at a glance. Plus, explain how to retrieve the data of Broker Information and Broker Queue with Real-Time SDK Java - EMA then print it out to a readable format to make it easier to understand. If you have any comments or questions regarding this article, feel free to leave them on our Q&A forum (EMA), we're happy to assist you regarding our APIs usage.
Reference
- Register or Log in to applaud this article
- Let the author know how much this article helped you
