How to request particular fields of an item (RIC) via RFA API
This article is intended for software users who developing RFA consumer. It is going to explain how to request particular fields of an item(RIC) via RFA. Therefore, the application receives only the fields that it is interested in instead of all fields applicable to the item. This helps to improve the application performance and bandwidth. The users should have a basic understanding of how to consume data using RFA which can be learned from RFA Java Tutorials, RFA C++ Tutorials and RFA.NET Tutorials in Refinitiv Developer Community web site. Anyway, the general techniques outlined below could be applied to any of real-time streaming APIs i.e. ETA C++/Java, EMA C++/Java.
Overview
When an application subscribes an item/RIC to get its data via RFA or other real-time streaming APIs, the application receives all fields applicable to an item. However, a consumer application may not require all of the fields contained in the responses. The Dynamic View feature provided by RFA and other real-time streaming APIs allows a consumer application to request selective fields by specifying the set of interesting fields in a request message.
Requirements
Refinitiv Real-Time Distribution System (formerly known as TREP) facilitates interactions between many different service provider applications and consumer applications. While provider applications implement services and expose a certain set of capabilities or contents e.g. Market Price (level 1 data) or Market by Order (level 2 data), consumer applications consume contents and use them to serve their business requirements. Consumer applications can request data from Refinitiv Real-Time Distribution System to access contents provided by the provider applications.
ADS (Advanced Distribution Server) is one component of Refinitiv Real-Time Distribution System. It interacts with consumer applications directly to deliver data that the consumer applications request.
Normally ADS returns all fields applicable to an item(full image followed by all updates) to the application when the application requests data of an item. Therefore, the application receives all fields as shown in the figure below:
Full image and all updates increase bandwidth. In addition, the decoding time for all fields in the application can impact the application performance. To reduce the bandwidth and improve the application performance by reducing the decode time of received fields), this can be done with Dynamic View feature which will be explained in the next section.
Solution
The Dynamic View feature was introduced to afford applications the ability to specify a limited set of data when requesting an item. A 'View' is a constructed specifying a list of fields or elements that a user wants to receive for a particular item. The View feature can be used for streaming requests or non-streaming requests. After subscribing the request, the application receives response messages that contain only those fields defined by the request as shown in a figure below:
The following figure shows the response message returned from a Normal Request on the left side in comparison with the response message with only 2 fields returned from a View Request on the right side:
Not using view, all fields are returned with the size of 1,384 bytes. While using View, the response contains only specified fields, 21 bytes. Hence, using View saves about 98% for just this message payload. Therefore, the Dynamic View feature can increase consumer application performance by:
- Reduce bandwidth usage (by reducing the size of response message)
- Reduce decoding time at the application (by reducing the number of entries to decode)
To enable Dynamic View on ADS version 2.x, ADS that the application connects to must be installed with the required license, SNAP_AND_DYNAMIC_VIEW license key. Otherwise, the application will get all fields available to the item it requests with View. If the application connects to ADS version 3.x, the license is embedded in ADS already. Please contact Refinitiv account team/representative who can assist to obtain the license or latest version of ADS.
Currently, ADS supports View only for Market Price Level 1 data. As a result, if the application requests level 2 data, e.g. Market By Order with View, it will receive all fields applicable to the item and the state code of the returned message will be UNSUPPORTED_VIEW_TYPE as the example shown below:
This was the response from requesting Market By Order data for field Ids 1,3,15 and 131. However, the application got all fields instead of only requested fields.
Solution Code
The process of submitting a view request follows the general request-making process as shown in RFA Java Tutorials, RFA C++ Tutorials and RFA.NET Tutorials. However, the application’s request message has to set the indication flag/indication mask VIEW(RFA Java) or View(RFA.NET) or ViewFlag(RFA C++) and encode an array of the desired fields in the request message payload. The indication flag/indication mask VIEW/View/ViewFlag indicates the request message contains a payload with view information as explained in the table below:
| Indication Flag/Indication Mask | Description |
| VIEW/View/ViewFlag | Used in streaming and non-streaming REQUEST type message. Indicates that the request message payload may contain a Dynamic View, indicating the specific information the application wishes to receive, or wishes to continue receiving a previously specified View. If this flag is not present, any previously specified view is discarded and the full View will be provided. |
View information in the request message payload contains an element list with the following entries:
| Element Name | Type | Required | Default | RANGE/EXAMPLES | Description |
| :ViewType | UINT | Conditional(see Description) | RDMUser.View.FIELD_ID_LIST(RFA Java) or VT_FIELD_ID_LIST(RFA.C++ and RFA.NET) |
1 = RDMUser.View.FIELD_ID_LIST or 1=VT_FIELD_ID_LIST |
Specifies the content type of the ViewData array. Required when specifying a view or when reissuing while wanting to keep the same view. Not required when re-issuing to remove a view. In this case, do not send a payload or View. |
| :ViewData | OMMArray of INT | Yes | No | Array of field IDs | Field Ids will be encoded as an array of 2 byte fixed length field identifiers. |
Note: RDMUser.View.ELEMENT_NAME_LIST/VT_ELEMENT_NAME_LIST is another ViewType. It indicates that the content type of the ViewData is an array of Element Names. However, ADS does not support this ViewType on Market Price domain. If the application subscribes an item with array of Element Names instead of array of Field Ids, all fields applicable to the item will be returned and the state code of the returned message will be UNSUPPORTED_VIEW_TYPE as the exaxmple shown below:
This was the response from requesting Market Price data for field named DSPLY_NAME and TRDPRC_1. However, the application got all fields instead of only requested fields.
The example request message with View from RFA Java application is shown below. The View contains array of Field Ids that ADS supports.
Msg Type: MsgType.REQUEST
Msg Model Type: MARKET_PRICE
Indication Flags: REFRESH | VIEW
Hint Flags: HAS_ATTRIB_INFO | HAS_QOS_REQ
QosReq: (RT, TbT)
AttribInfo
ServiceId: 2115
Name: TRI.N
NameType: 1 (RIC)
Payload: 38 bytes
ELEMENT_LIST
ELEMENT_ENTRY :ViewType: 1
ELEMENT_ENTRY :ViewData:
ARRAY
ARRAY_ENTRY: 22
ARRAY_ENTRY: 25
The request above is to request Field Id 22 and 25, the Indication Flags of the request message includes VIEW. The payload contains the element named ViewType which is 1 that represents RDMUser.View.FIELD_ID_LIST. The payload also contains the element named ViewData which is an array of the Field Ids.
The code snippet below shows how to create a request with View containing array of Field Ids in RFA Java:
// set VIEW indication flag
ommmsg.setIndicationFlags(otherIndicationFlags | OMMMsg.Indication.VIEW);
// set ommmsg other data elements
// must use encoder to encode payload
encoder.initialize(OMMTypes.MSG, 100);
encoder.encodeMsgInit(ommmsg, OMMTypes.NO_DATA, OMMTypes.ELEMENT_LIST);
encoder.encodeElementListInit(OMMElementList.HAS_STANDARD_DATA, (short)0, (short)0);
//Encode View Request
//1 - viewType:- RDMUser.View.FIELD_ID_LIST
//2 - viewData:- Array of field ids
// the view type is RDMUser.View.FIELD_ID_LIST
{
encoder.encodeElementEntryInit(RDMUser.View.ViewType, OMMTypes.UINT);
encoder.encodeUInt(RDMUser.View.FIELD_ID_LIST);
encoder.encodeElementEntryInit(RDMUser.View.ViewData, OMMTypes.ARRAY);
// assume viewData = {22, 25}
encoder.encodeArrayInit(OMMTypes.INT, 2); // init array
encoder.encodeArrayEntryInit(); // first entry
encoder.encodeInt(22);
encoder.encodeArrayEntryInit(); // second entry
encoder.encodeInt(25);
encoder.encodeAggregateComplete(); //completes the array
encoder.encodeAggregateComplete(); //completes the element list
}
//set the payload containing VIEW request
ommItemIntSpec.setMsg((OMMMsg)encoder.getEncodedObject());
For the complete application source code, please refer to StarterConsumer_BatchView application located in \Examples\com\reuters\rfa\example\omm\batchviewcons. The RFA Java package can be downloaded at RFA Java Downloads page.
StarterConsumer_BatchView application demonstrates how to request view and batch items using RFA Java's OMM consumer model. Please refer to \Examples\com\reuters\rfa\example\omm\batchviewcons\package.html for the help of the application. Requesting batch items is to specify multiple items in a single request message. This is called Batch feature. Anyway, the feature is not in the scope of this article.
StarterConsumer_BatchView application can be run with the following command to send a view request:
java -cp ..\Libs\rfa.jar;..\Examples com.reuters.rfa.example.omm.batchviewcons.StarterConsumer_BatchView -user pimchaya -session myNamespace::consSession -itemName TRI.N -viewData 22,25 -serviceName <service> -enumType ../etc/RDM/enumtype.def -rdmFieldDictionary ../etc/RDM/RDMFieldDictionary -sendReissue false -reissueWithPAR false -reissueWithPriority false -initialRequestPaused false
The example output:
This command requests an item, TRI.N, with Field Id 22(BID) and 25(ASK) and not request reissue. The application connects to a server as specified in a consumer session named myNamespace::consSession.
The application reads a consumer session which is RFA Java Consumer Configuration in the Registry of Windows machine or in the file preference on the Unix machine, the steps to setup the configuration can be found in RFA Java Tutorials 2.
The code snippet to create a request with View containing array of Field Ids(22 and 25) in RFA C++:
ElementList elementList;
//set ViewFlag indication mask
reqMsg.setIndicationMask(reqMsg.getIndicationMask() | rfa::message::ReqMsg::ViewFlag);
ElementEntry element;
ElementListWriteIterator elwiter;
DataBuffer dataBuffer;
elwiter.start(elementList);
//Encode View Request
//1 - viewType:- VT_FIELD_ID_LIST
//2 - viewData:- Array of field ids
element.setName(rfa::rdm::ENAME_VIEW_TYPE);
dataBuffer.setUInt32(rfa::rdm::VT_FIELD_ID_LIST, DataBuffer::UInt32Enum);
element.setData(static_cast<const Data&>(dataBuffer));
elwiter.bind(element);
ArrayWriteIterator arrWIt;
Array elementData;
ArrayEntry arrayEntry;
element.clear();
arrWIt.start(elementData);
// assume viewData = {22, 25}
//first entry
dataBuffer.clear();
arrayEntry.clear();
dataBuffer.setInt32(22, DataBuffer::Int32Enum);
arrayEntry.setData(dataBuffer);
arrWIt.bind(arrayEntry);
//second entry
dataBuffer.clear();
arrayEntry.clear();
dataBuffer.setInt32(25, DataBuffer::Int32Enum);
arrayEntry.setData(dataBuffer);
arrWIt.bind(arrayEntry);
arrWIt.complete();
element.setName(rfa::rdm::ENAME_VIEW_DATA);
element.setData(static_cast<const Data&>(elementData));
elwiter.bind(element);
elwiter.complete();
//set the payload containing VIEW request
reqMsg.setPayload(elementList);
in RFA.NET:
ElementList elementList = new ElementList();
//set View indication mask
reqMsg.IndicationMask = (byte)(reqMsg.IndicationMask | ReqMsg.IndicationMaskFlag.View);
ElementEntry element = new ElementEntry();
ElementListWriteIterator elwiter = new ElementListWriteIterator();
DataBuffer dataBuffer = new DataBuffer();
elwiter.Start(elementList);
//Encode View Request
//1 - viewType:- VT_FIELD_ID_LIST
//2 - viewData:- Array of field ids
element.Name = Reuters.RFA.RDM.RDM.REQUEST_MSG_PAYLOAD_ELEMENT_NAME.ENAME_VIEW_TYPE;
dataBuffer.SetUInt(Reuters.RFA.RDM.RDM.VIEW_TYPES.VT_FIELD_ID_LIST, DataBuffer.DataBufferEnum.UInt);
element.Data = dataBuffer;
elwiter.Bind(element);
ArrayWriteIterator arrWIt = new ArrayWriteIterator();
Reuters.RFA.Data.Array elementData = new Reuters.RFA.Data.Array();
ArrayEntry arrayEntry = new ArrayEntry();
element.Clear();
arrWIt.Start(elementData);
// assume viewData = {22, 25}
//first entry
dataBuffer.Clear();
arrayEntry.Clear();
dataBuffer.SetInt(22, DataBuffer.DataBufferEnum.Int);
arrayEntry.Data = dataBuffer;
arrWIt.Bind(arrayEntry);
//second entry
dataBuffer.Clear();
arrayEntry.Clear();
dataBuffer.SetInt(25, DataBuffer.DataBufferEnum.Int);
arrayEntry.Data = dataBuffer;
arrWIt.Bind(arrayEntry);
arrWIt.Complete();
element.Name = Reuters.RFA.RDM.RDM.REQUEST_MSG_PAYLOAD_ELEMENT_NAME.ENAME_VIEW_DATA;
element.Data = elementData;
elwiter.Bind(element);
elwiter.Complete();
//set the payload containing VIEW request
reqMsg.Payload = elementList;
For the complete application source code, please refer to StarterConsumer_BatchView application located in \Examples\StarterConsumer_BatchView which can be downloaded from RFA C++ Downloads page and RFA.NET Downloads page. Please refer to ReadMe.txt for the help of each application.
Conclusion
If the application uses real-time streaming APIs i.e. RFA Java/C++/.NET, ETA C++/Java, EMA C++/Java and look forward to increasing the application performance and reduce bandwidth quickly, Dynamic Views is a recommended solution. By using this feature, the application receives the interested fields only instead of all fields and that will significantly reduce the bandwidth with the minimal code change.
References
For further details, please check out the following resources:
