Reuters AdfinX Real Time 1.0 Library User Guide (Doc. No. 4510529)

AdfinX Real Time 1.0 Library 

User's Guide

AdfinX Real Time 1.0 Library - User's Guide 


Last Revised 21 May 02 

Copyright © Reuters 2002 All rights reserved. 

Republication or redistribution of Reuters content is expressly prohibited without the prior written consent of Reuters. 

Except as permitted by law, no part of this document may be reproduced or transmitted by any process or means without the 

prior consent of REUTERS Limited. 

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. 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. 

EFFIX, PowerPlus Pro, and Adfin are registered trademarks of the Reuters Group. 

EFFIX Order Management System (OMS), EFFIX Licensing System (ELS), FxNSC, PIXL, PowerBase, and ROMS (Reuters 

Order Management) are trademarks of the Reuters Group. 

IDN, Network Management (NMS), Reuters DTS (Data Transformation System), Reuters DTM (Data Transformation Manager), 

Reuters IPS (Internal Page Server), Reuters DCS (Data Contribution Servers), Reuters OCS (Optimizing Contribution Server), 

Reuters Dealing 2000, Reuters GLCS (Global Limits Control System), Reuters KreditNet, Reuters KVAR+, Reuters News 2000, 

RQF, RSF and Reuters Triarch are trademarks of REUTERS Limited. 

Reuters and the Reuters sphere logo are registered trademarks and trademarks of the Reuters group of companies around the 

world. 

Microsoft Windows, Windows NT, Visual Basic and MS-DOS are registered trademarks, and Microsoft Excel, Microsoft Word, 

and Microsoft Internet Explorer are products of Microsoft Corp. in the United States and other countries. Sun, Sun 

Microsystems, Solaris and SunOS are trademarks of Sun Microsystems Inc. TIB is a registerd trademark, and Rendezvous is a 

trademark of TIBCO Software Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively 

through X/Open Company Limited. 

Published by Reuters Limited, 85 Fleet Street, London EC4P 4AJ 

Reuters Financial Software 

6, rue Godefroy 

F-92821 Puteaux 

France 

Tel: +33 1 47 62 64 66 

Fax: +33 1 47 62 64 99 

Internet: http://www.effix.fr 

Support 

Tel: +33 1 47 62 67 00 

Email: marvin.help@reuters.com 

Subscribe to the Marvin Newsletter: marvin.mailing@reuters.com 

2


TABLE OF CONTENTS 

1. INTRODUCING ADFINX REAL TIME 1.0 LIBRARY ................................................... 7 

1.1. OVERVIEW ............................................................................................................................... 7 

1.1.1. Accessing Real Time Data................................................................................................. 7 

1.1.2. Settings File........................................................................................................................ 7 

1.2. HOW TO USE ADFINX CONTROLS........................................................................................ 7 

1.2.1. Usage ................................................................................................................................. 7 

1.2.2. AdxRtxLib Overview ........................................................................................................... 8 

2. ADXRTLIST............................................................................................................... 10 

2.1. ADXRTLIST PROPERTIES .................................................................................................... 10 

2.1.1. Source .............................................................................................................................. 10 

2.1.2. Mode ................................................................................................................................ 10 

2.1.3. DebugLevel ...................................................................................................................... 11 

2.1.4. ErrorMode ........................................................................................................................ 11 

2.1.5. ErrorCode......................................................................................................................... 11 

2.1.6. ErrorString ........................................................................................................................ 12 

2.1.7. Attribute ............................................................................................................................ 12 

2.1.8. UserTag............................................................................................................................ 12 

2.1.9. ListFields .......................................................................................................................... 13 

2.1.10. ListItems........................................................................................................................... 14 

2.1.11. FieldListCount .................................................................................................................. 15 

2.1.12. ItemListCount ................................................................................................................... 16 

2.1.13. Value ................................................................................................................................ 17 

2.1.14. FieldStatus ....................................................................................................................... 17 

2.1.15. ItemStatus ........................................................................................................................ 18 

2.1.16. ListStatus.......................................................................................................................... 19 

2.1.17. SourceStatus.................................................................................................................... 19 

2.2. ADXRTLIST METHODS.......................................................................................................... 20 

2.2.1. IsRegisteredField ............................................................................................................. 20 

2.2.2. IsRegisteredItem .............................................................................................................. 21 

2.2.3. RegisterItems ................................................................................................................... 22 

2.2.4. UnregisterItems................................................................................................................ 23 

2.2.5. UnregisterAllItems............................................................................................................ 23 

2.2.6. UnregisterFields ............................................................................................................... 24 

2.2.7. StartUpdates .................................................................................................................... 24 

3


2.2.8. StopUpdates..................................................................................................................... 25 

2.2.9. CloseAllLinks.................................................................................................................... 25 

2.3. ADXRTLIST EVENTS ............................................................................................................. 26 

2.3.1. OnUpdate ......................................................................................................................... 26 

2.3.2. OnImage........................................................................................................................... 26 

2.3.3. OnTime ............................................................................................................................ 27 

2.3.4. OnStatusChange.............................................................................................................. 27 

2.4. ADXRTLIST ILISTEVENTS INTERFACE ............................................................................... 27 

2.4.1. ListAdvise ......................................................................................................................... 28 

2.4.2. ListUnadvise..................................................................................................................... 28 

2.4.3. OnUpdate ......................................................................................................................... 29 

2.4.4. OnImage........................................................................................................................... 29 

2.4.5. OnTime ............................................................................................................................ 29 


3. ADXRTCONTRIBUTE ............................................................................................... 31 

3.1. ADXRTCONTRIBUTE PROPERTIES..................................................................................... 31 

3.1.1. ErrorMode ........................................................................................................................ 31 

3.1.2. ErrorCode......................................................................................................................... 31 

3.1.3. ErrorString ........................................................................................................................ 31 

3.1.4. Mode ................................................................................................................................ 31 

3.1.5. Attribute ............................................................................................................................ 32 

3.1.6. Source .............................................................................................................................. 33 

3.1.7. ItemName......................................................................................................................... 33 

3.1.8. RunStatus......................................................................................................................... 33 

3.2. ADXRTCONTRIBUTE METHODS.......................................................................................... 33 

3.2.1. Contribute......................................................................................................................... 33 

4. ADXRTCHAIN ........................................................................................................... 35 

4.1. ADXRTCHAIN PROPERTIES................................................................................................. 35 

4.1.1. Mode ................................................................................................................................ 35 

4.1.2. ErrorMode ........................................................................................................................ 36 

4.1.3. ErrorCode......................................................................................................................... 36 

4.1.4. ErrorString ........................................................................................................................ 36 

4.1.5. Attribute ............................................................................................................................ 36 

4.1.6. Source .............................................................................................................................. 37 

4.1.7. ItemName......................................................................................................................... 37 

4.1.8. Data.................................................................................................................................. 37 

4.1.9. DataStatus........................................................................................................................ 37 

4


4.1.10. RunStatus......................................................................................................................... 38 

4.1.11. SourceStatus.................................................................................................................... 38 

4.2. ADXRTCHAIN METHODS ...................................................................................................... 39 

4.2.1. RequestChain................................................................................................................... 39 

4.3. ADXRTCHAIN EVENTS.......................................................................................................... 39 

4.3.1. OnUpdate ......................................................................................................................... 39 


5. ADXRTHISTORY....................................................................................................... 41 

5.1. ADXRTHISTORY PROPERTIES ............................................................................................ 41 

5.1.1. Mode ................................................................................................................................ 41 

5.1.2. ErrorMode ........................................................................................................................ 42 

5.1.3. ErrorCode......................................................................................................................... 42 

5.1.4. ErrorString ........................................................................................................................ 43 

5.1.5. Attribute ............................................................................................................................ 43 

5.1.6. Source .............................................................................................................................. 43 

5.1.7. ItemName......................................................................................................................... 43 

5.1.8. Data.................................................................................................................................. 43 

5.1.9. DataStatus........................................................................................................................ 44 

5.1.10. RunStatus......................................................................................................................... 44 

5.1.11. ExistingFields ................................................................................................................... 44 

5.2. ADXRTHISTORY METHODS ................................................................................................. 45 

5.2.1. RequestHistory................................................................................................................. 45 

5.2.2. FlushData ......................................................................................................................... 45 

5.3. ADXRTHISTORY EVENTS..................................................................................................... 45 

5.3.1. OnUpdate ......................................................................................................................... 45 

6. ADXRTXLIB PARAMETERS AND CONSTANTS...................................................... 46 

6.1. ADXRTXLIB ENUMERATED TYPES...................................................................................... 46 

6.1.1. RT_ItemStatus ................................................................................................................. 46 

6.1.2. RT_FieldStatus................................................................................................................. 46 

6.1.3. RT_SourceStatus............................................................................................................. 46 

6.1.4. RT_ListStatus................................................................................................................... 47 

6.1.5. RT_ItemRowView............................................................................................................. 47 

6.1.6. RT_FieldRowView............................................................................................................ 47 

6.1.7. RT_ItemColumnView ....................................................................................................... 47 

6.1.8. RT_FieldColumnView....................................................................................................... 48 

6.1.9. RT_RunMode................................................................................................................... 48 

5


6.1.10. RT_DataStatus................................................................................................................. 49 

6.1.11. RT_RunStatus.................................................................................................................. 49 

6.1.12. RT_DebugLevel ............................................................................................................... 49 

6.1.13. AdxErrorMode .................................................................................................................. 50 

6.1.14. AdxAttrRtList .................................................................................................................... 50 

6.1.15. AdxAttrRtContribute ......................................................................................................... 50 

6.1.16. AdxAttrRtChain................................................................................................................. 51 

6.1.17. AdxAttrRtHistory............................................................................................................... 51 

6


1. INTRODUCING ADFINX REAL TIME 1.0 LIBRARY 

1.1. OVERVIEW 

1.1.1. Accessing Real Time Data 

The Real Time ActiveX Component Library (AdxRtxLib) provides a number of components allowing 

user applications to retrieve and contribute real time data sources. The components that AdxRtxLib 

supplies provide dual interfaces. 

While it is compatible with most DDE servers, AdfinX Real Time can also be directly interfaced with 

real time data sources, such as Reuters Triarch or TIB/Rendezvous. 

Four data object components are provided. These are AdxRtList, AdxRtContribute, 

AdxRtHistory and AdxRtChain. 

1.1.2. Settings File 

To fit AdfinX Real Time to your needs, the file m_rtuser.dat holds user data settings related to real 

time. This file allows the user to define Real Time drivers, field separators, and the path for the log file. 

1.2. HOW TO USE ADFINX CONTROLS 

1.2.1. Usage 

Registration 

Following are the main ways to reference AdfinX controls in different languages: 

Visual Basic 

To be able to use the components from the Visual Basic IDE, use the “Project Components…” 

menu item, and, in the “Controls” property page tab of the dialog, tick the entry for the “AdfinX Real 

Time Type Library” — this will add the four Real Time objects to your component toolbox. You will be 

able to find them with the Object Browser too. 

VBA (Microsoft Excel) 

On the Tools menu, click References and then select the modules you want to use. Click OK. 

VBA (Microsoft Visual Basic) 

On the Project menu, click References and then select the modules you want to use. Click OK. 

In order to use the AdfinX Real Time controls in your application, you must then: 

On the Project menu, click Components and then select the modules you want to use. Click OK. 

C++ (Microsoft Visual C++) 

Use the #import directive to incorporate information from a type library which describes the COM 

interface. 

For example, the AdfinX Real Time module is referenced as follows: 

#import “..\\..\\..\\rtx.dll 

7


Microsoft FrontPage Editor 

On the Insert menu, click Advanced and then click AdfinX Real Time 1.0 Library control. 

HTML 

The AdxRtList control is referenced as follows: 

 

The clsid is the unique identifier for the AdfinX Real Time library. 

1.2.2. AdxRtxLib Overview 

The AdxRtxLib component provides a way of accessing real time market data from within Windows 

applications using standard ActiveX technology. 

Real time market data are organized as items, which are in turn composed of fields that hold individual 

atomic values. An item might represent the information concerning an individual bond, for example. 

Items are themselves provided by data sources. When the data in an item needs to change, its source 

updates the required fields, keeping their values up to date. 

Real time market data 

The AdxRtxLib component allows a program to retrieve the field values from market data items 

and can inform the program when the source changes them. Using this component, the program 

can perform a variety of tasks: 

Maintaining lists of items providing real time market data; 

Managing the list of fields within those items whose values are required; 

Handling updates made to field values by the data source; 

Allowing the retrieval of a single item image (“snapshot”), which will not be kept up to date. 

Historical market data 

Some data sources also allow historical data concerning individual items; the AdxRtxLib 

component provides a mechanism for retrieving such data. 

Contribution 

Some data sources also allow contribution, whereby new values are supplied for item fields. All 

consumers of the source will be informed of updates to those items in the usual way. Once again, 

the AdxRtxLib component allows a program to contribute data in this way. 

The AdxRtxLib Objects 

To support this functionality within a program, the AdxRtxLib component provides objects of the 

following types: 

The AdxRtList object represents a collection of items, every item being a collection of fields. By 

iterating through the collection, the program can retrieve information about any item or any field. 

The AdxRtContribute object enables the contribution of new values for a set of fields in an item. 

The AdxRtHistory object allows the program to request historical data concerning an item. 

The AdxRtChain object allows for the retrieval of chains: these are lists of item names provided by 

the data source. 

8


The following figure illustrates the AdxRtxLib architecture: 

Each of the objects provided is described in the following chapters. 

The AdxRtxLib component functionality is provided using ActiveX interfaces. These are implemented 

by the RTX.DLL file. 

9


2. ADXRTLIST 

2.1. ADXRTLIST PROPERTIES 

2.1.1. Source 

Source 

Name of the data source as a string. 

Arguments 

None 

Error Handling 

Depends on the value of the DebugLevel general property, as follows: 

RT_DEBUG_NO 

If the source is already known as invalid or down, an exception is raised. If the status of the 

source is unknown, then the process continues without any warning or error. 

RT_DEBUG_IMMEDIATE 

When using SSL, the source is checked for validity. If it is not valid an exception is raised 

before setting a new property value. 

If the source is unknown or down an exception is raised. 

It is important to note that in this mode the setting of the Source property could be very slow. 

Example 

Public list as AdxRtList 

Set list = New AdxRtList 

'Declare as global variable' 

'Create an instance of the list object. This syntax is more 

efficient than when only the new instruction is used. Otherwise, 

before execution, Visual Basic will test each statement 

containing list for the value Nothing. ' 

list.Source = "IDN_SELECTFEED" 

'Set the source name to "IDN_SELECTFEED"' 

2.1.2. Mode 

Mode 

This property describes various behavioural aspects of the AdxRtList object. In particular, it 

determines how the list object will deliver data update events to the client application. The allowed 

parameters are: 

FRQ : The frequency of regularly generated events. If the list’s StartUpdates 

method was called with the run mode value RT_MODE_ONTIME or 

RT_MODE_ONTIME_IF_UPDATED, OnTime events will be triggered at this 

frequency. The minimum frequency is one event per second. 

FRQ:iH set a frequency of one event every i hours. 

FRQ:iM set a frequency of one event every i minutes. 

FRQ:iS set a frequency of one event every i seconds. 

The default frequency is one event every 10 seconds. 

10


TIMEOUT : The maximum time in seconds to allow for the arrival of data images for the 

items of the list. 

TIMEOUT:i set a timeout period of i seconds. 

By default, its value is zero, indicating that no timeout is in effect. 

Arguments 


Example 



'Declare as global variable' 

'Create an instance of the list object. This syntax is more 

efficient than when only the new instruction is used. Otherwise, 

before execution, Visual Basic will test each statement 

containing list for the value Nothing. ' 


'Set the source name to "IDN_SELECTFEED"' 

list.StartUpdates RT_MODE_TIME 

list.Mode = "FRQ:10s" 

2.1.3. DebugLevel 

DebugLevel 

This property defines the support for debugging provided by the AdxRtList object. It takes a value 

from the RT_DebugLevel enumeration. 

Arguments 


2.1.4. ErrorMode 

ErrorMode 

This property sets the error mode for the object. When an error is detected, this property is consulted 

to see what action should be taken by the object to inform the user of the application. It must be 

assigned a value from the AdxErrorMode enumeration. 

By default the error mode is set to EXCEPTION. 

Arguments 


2.1.5. ErrorCode 

ErrorCode 

This property retrieves the error code of the latest error encountered by the object as an integer value. 

If the ErrorMode property of the object is set to NO_EXCEPTION, this value must be consulted by the 

client application to determine whether an error has occurred. 

11


Arguments 


2.1.6. ErrorString 

ErrorString 

This property retrieves a string describing the latest error encountered by the object. If the ErrorMode 

property of the object is set to NO_EXCEPTION, this value can be consulted by the client application 

when the ErrorCode property indicates that an error has occurred. 

Arguments 


2.1.7. Attribute 

Attribute(AttrID) 

Allows the consultation of various settings applying to the object. These are the settings that can be 

changed for the object by assigning values to the Mode property. 

Arguments 

AttrID 

An identification of the attribute, passed as a Variant. This can be either an 

identifying code taken from the AdxAttrRtList enumeration or a string 

containing the keyword used to set the attribute using the Mode property. 

Return Value 

The value of the requested attribute of type Variant. 

2.1.8. UserTag 

UserTag(ItemName, FieldName) 

Allows information to be associated with an item or with a single field of an item in the list. The value is 

held in the association as a Variant. 

Different user tag values associated with items and fields can be consulted using ListItems and 

ListFields. The tag associated with an item is also provided as a parameter to the OnUpdate event 

callback function. 

Note that user tag values related to fields must be integer values (of type Long). 

Arguments 

ItemName 

FieldName 

The name of the required item as a string. 

The name of the field to which the user tag will apply. If FieldName has the 

form "" (the empty string) or "*" then the user tag is applied to the whole 

item, otherwise it concerns the field itself. 

Return Value 

When used to fetch the user tag, a Variant value is returned. 

12



An error exception may be thrown in the following cases: 

If the Source has not been set (i.e. the source is in the state RT_SOURCE_NOT_SET) an error 

exception is thrown. 

If either the ItemName or the FieldName has not been registered in the AdxRtList object (using 

RegisterItems), an exception will be thrown indicating the invalid argument. 

If the user tag is not an integer value and the FieldName indicates a valid field, an exception will 

be thrown indicating the invalid argument. 

If the DebugLevel general property is RT_DEBUG_NO, and either the ItemName or the 

FieldName is already known to be invalid, an exception will be thrown indicating the invalid 

argument. 

If the DebugLevel general property is RT_DEBUG_IMMEDIATE, the program waits for a callback to 

determine the validity of either ItemName or FieldName. If either is invalid, an exception will be 

thrown indicating the invalid argument. Note that this approach is inherently slow. 

Example 



list.UserTag("RTR.L", "") = "Port:cld" 

'Associate the string value "Port:cld" with the item "RTR.L" 

of list‘s item list. When the OnUpdate event associated with 

this item is handled, this string value is passed as the UserTag 

parameter to the callback function. ' 

list.UserTag("DEM=", "BID") = 100 

'Associate the integer value 100 with the item "DEM=" of list‘s 

item list. ' 

2.1.9. ListFields 

ListFields(ItemName, RView, CView) 

This property supplies an item’s field information in a two dimensional array of Variant. The array 

can have up to four columns. The first column identifies the fields. Other, optional columns supply field 

data values, field status (see the RT_FieldStatus enumeration) and user tag (see the UserTag 

property) values. 

The RView and CView parameters control the contents of the array. 

Arguments 

ItemName 

RView 

CView 


One of the values from the RT_FieldRowView enumeration. This specifies 

that the array should contain a row for each field supplied by the item, or 

each registered field of the item, or only each updated field of the item 

(changed since the last update was handled). 

A combination of values from the RT_FieldColumnView enumeration. This 

specifies which of the three optional columns will be supplied: data, status 

and user tag. The enumeration values should be combined by adding them 

together. 

13


Return Value 

The property is supplied as a variant array of fields or an empty variant if an error has occurred. 



If RView is set to RT_FRV_UPDATED and the property is queried outside of an event callback (i.e. 

one of OnImage, OnUpdate or OnTime), the return array will be empty. In this case an error 

exception will be thrown. 

If RView is set to RT_FRV_EXISTING and CView includes the RT_FCV_USERTAG flag, an error 

exception will be thrown because user tags can be set only for registered fields. 

If either RView or CView contain invalid values, an error exception will be thrown. 

Notes 

By default, RView is set to RT_FRV_ALL, and CView to the combination (RT_FCV_VALUE + 

RT_FCV_USERTAG). 

It should be noted that the RT_FRV_EXISTING mode is only valid with certain platforms such as 

SSL. 

Example 



Dim MyArray as Variant 

MyArray = list.ListFields("DEM=", RT_FRV_ALL, RT_FCV_VALUE) 

'The returned array will contain the names and values of all 

fields available in the "DEM=" item. ' 

FieldName = MyArray(2, 0) 

FieldData = MyArray(2, 1) 

'FieldName contains the value of the third element of the first 

column of the array; this is the third field’s name. ' 

'FieldData contains the value of the third element of the 

second column of the array; this is the third field’s value. ' 

2.1.10. ListItems 

ListItems(RView, CView) 

This property supplies item information in a two dimensional array of Variant. The array can have up 

to three columns. The first column identifies the items. Other, optional columns supply item status (see 

the RT_ItemStatus enumeration) and user tag values for each item (see the UserTag property) 

values. 

The RView and CView parameters control the contents of the array. 

Arguments 

RView 

CView 

One of the values from the RT_ItemRowView enumeration. This specifies 

that the array should contain a row for each registered item, or only a row for 

each item that has been updated. 

A combination of values from the RT_ItemColumnView enumeration. This 

specifies which of the two optional columns will be supplied: status and user 

tag. The enumeration values should be combined by adding them together. 

14


Return Value 

The property is supplied as a variant array of items or an empty variant if an error has occurred. 



If RView is set to RT_IRV_UPDATED and the property is queried outside of an event callback (i.e. 

one of OnImage, OnUpdate or OnTime), the return array will be empty. In this case, an error 

exception will be thrown. 

If either RView or CView contain invalid values, an error exception will be thrown. 


By default, RView is set to RT_IRV_ALL, and CView to RT_ICV_USERTAG. 

It should be noted that the RT_IRV_ALL mode is only valid with certain platforms (all except DDE). 

Example 




MyArray = list.ListItems(RT_IRV_UPDATED, RT_ICV_USERTAG) 

'The returned array will contain the names and user tags of all 

updated items in list. ' 

ItemName = MyArray(2, 0) 

ItemTag = MyArray(2, 1) 

'ItemName contains the value of the third element of the first 

column of the array; this is the third item’s name. ' 

'ItemTag contains the value of the third element of the second 

column of the array; this is the third item’s user tag. ' 

2.1.11. FieldListCount 

FieldListCount(ItemName, RView) 

This property supplies the number of fields described by the ListFields property for a particular 

item. 

Arguments 

ItemName 

RView 


One of the values from the RT_FieldRowView enumeration. This specifies 

how the counting should be performed: one row for each updated field, one 

row for each registered field, or one row for each field supplied by the 

identified item. 

Return Value 

The number of fields counted is supplied as an integer. This will be zero if an error occurs. 



If RView is set to RT_FRV_UPDATED and the property is queried outside of an event callback (i.e. 

one of OnImage, OnUpdate or OnTime), the return value will be 0. In this case, an error exception 

will be thrown. 

15


If RView contains an invalid value, an error exception will be thrown. 

Example 




MyArray = list.ListFields("DEM=", RT_FRV_ALL, RT_FCV_VALUE) 

NumFields = list.FieldListCount("DEM=", RT_FRV_ALL) 

'NumFields holds the number of rows (fields) contained in 

MyArray. ' 

2.1.12. ItemListCount 

ItemListCount(RView) 

This property supplies the number of items described by the ListItems property. 

Arguments 

RView 

One of the values from the RT_ItemRowView enumeration. This specifies 

how the counting should be performed: one row for each updated field, one 

row for each registered field, or one row for each field supplied by the 

identified item. 

Return Value 

The number of items counted is supplied as an integer. This will be zero if an error occurs. 



If RView is set to RT_IRV_UPDATED and the property is queried outside of an event callback (i.e. 

one of OnImage, OnUpdate or OnTime), the return value will be 0. In this case, an error exception 

will be thrown. 

If RView contains an invalid value, an error exception will be thrown. 

Example 




MyArray = list.ListItems(RT_IRV_ALL, RT_ICV_USERTAG) 

ListCount = list.ItemListCount(RT_IRV_ALL) 

'ListCount holds the number of rows (items) contained in 

MyArray. ' 

16


2.1.13. Value 

Value(ItemName, Field) 

This property returns a variant containing the current value of the field specified by ”FieldName”of the 

item specified by ”ItemName”. 

If the data is not available or one of the parameters is invalid an empty variant is returned. 

Arguments 

ItemName 

Field 

The name of the item as a string. 

Either the name of the field whose value to retrieve as a string or its numeric 

identifier. 

Return Value 

Returns the value of the identified field or an empty variant if the value is still unkown or invalid. 

Error handling 

If the item or the field has not been registered or the field is not in the field dictionary, an exception 

is thrown notifying the user that the argument is not valid. 

Example 



Dim ItemList(0 To 1) as Variant 

ItemList(0) = "EUR=" 

ItemList(1) = "JPY=" 

Dim FieldList(0 To 1) as Variant 

FieldList(0) = "BID" 

FieldList(1) = "ASK" 

Dim Data As Variant 

'The returned value can be either a string or a numeric value. ' 

list.RegisterItems ItemList, FieldList 

Data = list.Value("EUR=", "BID") 

'The latest value of the "BID" field of the item "EUR=" is stored 

in Data. ' 

2.1.14. FieldStatus 

FieldStatus(ItemName, FieldName) 

This property returns a value from the RT_FieldStatus enumeration. 

Arguments 

ItemName 

FieldName 


The name of the field as a string. 

17


Return Value 

Returns the status of the field in the item. 




Example 










list.StartUpdates RT_MODE_IMAGE 

Data = list.value("EUR=", "BID") 

FStatus = list.FieldStatus("EUR=", "BID") 

'Sets FStatus to RT_FIELD_OK or RT_FIELD_UNKNOWN' 

2.1.15. ItemStatus 

ItemStatus(ItemName) 

This property returns a value from the RT_ItemStatus enumeration. 

Arguments 

ItemName 


Return Value 

Returns the status of the item. 




18


Example 










IStatus = list.ItemStatus("EUR=", "BID") 

'Sets IStatus to the status of the item, such as RT_ITEM_OK 

or RT_ITEM_STALE' 

2.1.16. ListStatus 

ListStatus 

This property returns a value from the RT_ListStatus enumeration. This value reflects the status of 

the AdxRtList object itself. 

Arguments 


Return Value 

Returns the status of the list. 




Example 



Status = list.ListStatus 

'Sets Status to the status of the list object; this will be 

RT_LIST_INACTIVE if no items have been registered. ' 

2.1.17. SourceStatus 

SourceStatus 

This property returns a value from the RT_SourceStatus enumeration. This value reflects the status 

of the source defined by the Source property of the AdxRtList object. 

19


Arguments 


Return Value 

Returns the status of the source of the list object. 




Example 




Status = list.SourceStatus 

'Sets Status to the status of the "IDN_SELECTFEED" source; 

this might be RT_SOURCE_UP or RT_SOURCE_DOWN, for 

example' 

2.2. ADXRTLIST METHODS 

2.2.1. IsRegisteredField 

IsRegisteredField(ItemName, FieldName) 

This property returns a Boolean value which is True if the designated field is contained in the given 

item of the AdxRtList object. Otherwise it returns False. 

Arguments 

ItemName 

FieldName 


The name of the field as a string. 

Return Value 

True if the field was found, False otherwise. 

20


Example 










TestBid = list.IsRegisteredField("EUR=", "BID") 

'Sets TestBid to True' 

TestDName = list.IsRegisteredField("JPY=", "DISPLAY_NAME") 

'Sets TestDName to False' 

2.2.2. IsRegisteredItem 

IsRegisteredItem(ItemName) 

This property returns a Boolean value which is True if the designated item has been registered in the 

AdxRtList object. Otherwise it returns False. 

Arguments 

ItemName 


Return Value 

True if the item was found, False otherwise. 

Example 







TestEUR = list.IsRegisteredItem("EUR=") 

'Sets TestEUR to True' 

TestCHF = list.IsRegisteredItem("CHF=") 

'Sets TestCHF to False' 

21


2.2.3. RegisterItems 

RegisterItems(ItemList, FieldList) 

This method adds a list of items with a corresponding list of associated fields to the AdxRtList 

object. Registering the items allows for retrieval of item data from the object’s data source (defined by 

the Source property). 

Arguments 

ItemList 

FieldList 

An array of variant of one or more item names. 

An array of variant of one or more field names. It is possible, by specifying 

the single value "*", to request all fields present in the items. (This 

functionality depends on the system used to provide access to the data 

sources.) 

Return Value 

If successful, this method returns RT_OK, otherwise it returns the error status RT_ERR. An error means 

that the FieldList is not correctly set and that at least one field is undefined (has a field status of 

RT_FIELD_UNDEFINED). 


Depends on the value of the DebugLevel general property, as follows: 

RT_DEBUG_NO 

If one of the items in the ItemList or one of the fields in the FieldList is already known 

to be invalid, an exception is thrown notifying the user about it. 

RT_DEBUG_IMMEDIATE 

On direct API platforms, for each item in the ItemList, an initial event callback is used to 

determine whether the item or any of the requested fields within it is invalid. If so, an 

exception is thrown accordingly. It is important to note that in this mode the registration 

process can be very slow. 

Example 










'Adds the items "EUR=" and "JPY=" to the list list. For each 

of these items, the fields "BID" and "ASK" are required. ' 

22


2.2.4. UnregisterItems 

UnregisterItems(ItemList) 

This method removes a list of items from the AdxRtList object which were previously registered with 

RegisterItems. If the object is receiving events (data have been requested using the 

StartUpdates method), no more information will be received by the object concerning these items. 

Arguments 

ItemList 

A list of one or more names as a variant, identifying the items to remove from 

the list. 


If one of the item names in ItemList has not previously been registered in the list object, an error 




Example 



Dim ItemList as Variant 

ItemList = Array("EUR=", "JPY=") 

list.UnregisterItems ItemList 

'Removes the item "EUR=" from the list list. ' 

2.2.5. UnregisterAllItems 

UnregisterItems() 

This method removes all items from the AdxRtList object which were previously registered with 

RegisterItems. If the object is receiving events (data have been requested using the 

StartUpdates method), no more information will be received by the object, as if the StopUpdates 

method were called. 

Arguments 





Example 



list.UnregisterAllItems 'Removes all registered items from the list list. ' 

ItemCount = list.ItemListCount 

'This sets ItemCount to 0. ' 

23


2.2.6. UnregisterFields 

UnregisterFields(ItemList, FieldList) 

This method removes the fields identified by FieldList from the items in ItemList, which should have 

been registered in the AdxRtList object earlier using RegisterItems. If by using this method all 

registered fields are removed for an item, this does not unregister the item itself. 

Arguments 

ItemList 

FieldList 

A list of one or more names as a variant, identifying the items whose fields 

should be removed. 

A list of one or more names as a variant, identifying the fields to remove. 

These must be fields which were named explicitly using the 

RegisterItems FieldList parameter. 


If one of the item names in ItemList or one of the field names in FieldList has not previously 

been registered in the list object, an error exception is thrown. 



Example 



Dim ItemList as Variant 

ItemList = "EUR=" 

Dim FieldList as Variant 

FieldList = "ASK" 

list.UnregisterFields ItemList, FieldList 

'Removes the "ASK" field from the item "EUR=" of the list 

list. ' 

2.2.7. StartUpdates 

StartUpdates(Mode) 

This method starts the real time update of data for the items registered using RegisterItems in the 

AdxRtList object. It also establishes the update mode. 

Arguments 

Mode 

A value from the RT_RunMode enumeration. 


If Mode contains an invalid value, an error exception is thrown. 



24


Example 



list.StartUpdates RT_MODE_IMAGE 

'Requests all items registered in the list list from its source. 

Once a data image has been received for each of the objects 

(or a time-out occurs), no more data will be received. This 

supplies a snapshot of the items. ' 

2.2.8. StopUpdates 

StopUpdates() 

This method stops the delivery of all updates of items registered in the AdxRtList object to the 

program but without closing the underlying data stream unless the StartUpdates mode was 

RT_MODE_IMAGE or the AdxRtList object is in the RT_LIST_LINKS_CLOSED state. This allows 

updates to be stopped momentarily. To resume updates, the StartUpdates method should be called 

again. 

Arguments 





Example 



list.StopUpdates 

'Stop the delivery of data for all items registered in the list list.' 

2.2.9. CloseAllLinks 

CloseAllLinks() 

This method stops the delivery of all updates for items registered in the AdxRtList object to the 

program and closes down the underlying data stream by informing the data source as required that no 

more updates will be necessary for those items. 

Arguments 





25


Example 



list.CloseAllLinks 

'Stop the delivery of data for all items registered in the list list 

and tell the source that they are no longer required. ' 

2.3. ADXRTLIST EVENTS 

2.3.1. OnUpdate 

OnUpdate(ItemName, UserTag, ItemStatus) 

When StartUpdates has been called with either the RT_MODE_ONUPDATE or 

RT_MODE_ONTIME_IF_UPDATED mode, events of this type will be sent to the user application when 

data updates from the source are received for any of the items registered by the object. 

An event is generated for each item whose data have been updated by the data source, either as soon 

as the change is received (when RT_MODE_ONUPDATE is used), or if the change occurred during the 

period between regular checks controlled by a timer (when RT_MODE_ONTIME_IF_UPDATED is used). 

User code should provide a callback function to handle these events. In this function, the ListFields 

method can be called to determine which fields in the item have changed, and what the new field 

values are. 

Arguments 

ItemName 

UserTag 

ItemStatus 

The name of one of the items registered in the list object. The update event 

is associated with this item. 

The user tag associated with the item, if one was supplied using the 

UserTag method. This parameter should be treated as constant: it must not 

be changed by the application code. 

The status of the item, a value from the RT_ItemStatus enumeration. 

2.3.2. OnImage 

OnImage(DataStatus) 

This event is delivered once a data image has been received for each of the registered items of the 

AdxRtList object which is receiving data following a call to StartUpdates using the 

RT_MODE_IMAGE mode. It is also called if a time-out occurred (set using the "TIMEOUT" attribute of 

the Mode property) before all data images could be received. 

User code should provide a callback function to handle these events. In this function, the ListItems 

method can be used to see which items have a data image associated with them; for each of these, 

ListFields method can be called to obtain the values of its fields. 

Arguments 

DataStatus 

The status of the registered items, a value from the RT_DataStatus 

enumeration. This will have the value RT_DS_FULL if data have been 

received from the source for all registered items, or RT_DS_PARTIAL if at 

least one of the items still has no associated data at the end of the time-out 

period. 

26


2.3.3. OnTime 

OnTime() 

This event is generated regularly by a timer at a frequency determined by the "FRQ" attribute 

parameter (see the Mode property) on behalf of the AdxRtList object which is receiving data 

following a call to StartUpdates using the RT_MODE_ONTIME mode. 

User code should provide a callback function to handle these events. In this function, the ListItems 

method can be used to see which items have changed since the last OnTime event; for each of these, 

ListFields method can be called to obtain the values of the updated fields. 

Arguments 


2.3.4. OnStatusChange 

OnStatusChange(ListStatus, SourceStatus, RunMode) 

This event is generated every time a change occurs that affects the status of the AdxRtList object as 

a whole. Such events are: 

The Source property is changed. 

The RT_RunMode changes (through a call to the StartUpdates method). 

The real time data streams are stopped (through external events) or closed (through a call to the 

CloseAllLinks method). 

The AdxRtList object goes from empty to non-empty. 

User code should supply a callback function to handle these events within the program. 

Arguments 

ListStatus 

SourceStatus 

RunMode 

The current status of the AdxRtList object. This is a value from the 

RT_ListStatus enumeration. 

The current status of the data source (identified by the Source property). 

This is a value from the RT_SourceStatus enumeration. 

The current update mode, usually changed through the StartUpdates 

method. This is a value from the RT_RunMode enumeration. 

2.4. ADXRTLIST ILISTEVENTS INTERFACE 

A user application can use the IListEvents interface as an alternative to the standard event 

(connection point) interface associated with an object of type AdxRtList. To use this alternative 

interface, the user application must associate an object which implements the IListEvents interface 

with the AdxRtList object or objects. This is done using the AdxRtList object’s ListAdvise 

method. The association can be broken by calling the ListUnadvise method. 

Once an association of this type has been established, the various events delivered for the 

AdxRtList object will cause the corresponding methods of the IListEvents object to be called. 

Using this interface allows methods to be dispatched using a vtable mechanism. This is a much faster 

process than that of using the connection point mechanism, improving the user application’s 

performance. 

27


Example 

A Visual Basic implementation of an object providing the IListEvents interface involves using a 

class module. This will look something like the following: 

Implements IListEvents 

Dim list as AdxRtList 


list.ListAdvise Me 

'This declares that the object implemented by the class module 

contains a list object…' 

'… which is created here. ' 

'This associates the object with the list item it knows about, 

list. In other words, list ‘s events will be sent to the object 

containing it. ' 

list.StartUpdates RT_MODE_ONUPDATE 

'Ask for updates for items registered by the list. ' 

'The following event callback for the interface can be created by the Visual Basic editor. ' 

Sub IListEvents_OnUpdate(ByVal MyList as AdxRtxLibCtl.IAdxRtList, _ 

ItemName as String, UserTag as Long, ItemStatus as RT_ItemStatus) 


MyArray = MyList.ListItems(RT_IRV_UPDATED, RT_ICV_USERTAG) 

'The objects list (a property of the class module’s object) and 

MyList (received as a parameter to this function) are in fact the 

same. ' 

End Sub 

2.4.1. ListAdvise 

ListAdvise(pListEvents) 

This method allows the user application to receive events for the AdxRtList object though an 

alternative interface. The event callback functions are methods of an object implementing the 

IListEvents interface. 

When the AdxRtList object’s StartUpdates method is called, the events will be delivered to the 

methods of the interface object. 

Arguments 

pListEvents 

A pointer to an object implementing the IListEvents interface. This object 

need not be unique for all AdxRtList objects. 

2.4.2. ListUnadvise 

ListUnadvise() 

This method detaches the AdxRtList object from an object implementing the IListEvents 

interface. 

Arguments 

None. 

28



OnUpdate(MyList, ItemName, UserTag, ItemStatus) 

The OnUpdate event causes a call to this method of the object providing the IListEvents interface 

for the AdxRtList object. 

The two objects were linked through a call to the AdxRtList object’s ListAdvise method. 

Arguments 

MyList 

ItemName 

UserTag 

ItemStatus 

A pointer to the IAdxRtList interface of the AdxRtList object for which 

the event was delivered. 

The name of one of the items registered in the list object identified by 

MyList. The update event is associated with this item. This parameter 

should be treated as constant: it must not be changed by the application 

code. 

The user tag associated with the item, if one was supplied using the 

UserTag method. This Variant value should be treated as constant. 

The status of the item, a value from the RT_ItemStatus enumeration. 

2.4.4. OnImage 

OnImage(MyList,DataStatus) 

The OnImage event causes a call to this method of the object providing the IListEvents interface 

for the AdxRtList object. 


Arguments 

MyList 

DataStatus 



The status of the registered items, a value from the RT_DataStatus 

enumeration. This will have the value RT_DS_FULL if data have been 

received from the source for all registered items, or RT_DS_PARTIAL if at 

least one of the items still has no associated data at the end of the time-out 

period. 

2.4.5. OnTime 

OnTime(My List) 

The OnTime event causes a call to this method of the object providing the IListEvents interface for 

the AdxRtList object. 


Arguments 

MyList 



29



OnStatusChange(MyList,ListStatus, SourceStatus, RunMode) 

The OnStatusChange event causes a call to this method of the object providing the IListEvents 

interface for the AdxRtList object. 


Arguments 

MyList 

ListStatus 

SourceStatus 

RunMode 



The current status of the AdxRtList object. This is a value from the 

RT_ListStatus enumeration. 



The current update mode, usually changed through the StartUpdates 

method. This is a value from the RT_RunMode enumeration. 

30


3. ADXRTCONTRIBUTE 

3.1. ADXRTCONTRIBUTE PROPERTIES 


ErrorMode 





Arguments 



ErrorCode 




Arguments 



ErrorString 




Arguments 


3.1.4. Mode 

Mode 

This property describes various behavioural aspects of the AdxRtContribute object. In particular, it 

determines how the contribution object will deliver data update events to the client application. The 

allowed parameters are: 

FORMAT : The format applied to a numeric data contributed to a page. 

FORMAT:i: j set a format with a total field width of i characters and 

a decimal precision of j digits. 

31


FTC : The fields to contribute when several fields have been specified. 

FTC:ALL 

send all field values (the default). 

FTC:CHANGED send only those field values that have changed. 

FORMAT:i-j,k always send those fields in positions i to j and position 

k in the field list, along with any others in the list whose 

values have changed. 

LIFETIME : The period following local contribution during which values contributed are 

kept as current (in preference to updated values coming from the specified 

data source). At the end of this period, a contributed value will be dropped in 

favour of the data source’s value. 

LIFETIME:ALWAYS keep the contributed values indefinitely. 

LIFETIME: iH keep the contributed values for i hours. 

LIFETIME: iM keep the contributed values for i minutes. 

LIFETIME: iS keep the contributed values for i seconds. 

OPERATION : The type of operation required in the case of page-based contribution. 

OPERATION:CONTRIBUTION contributes to the page. 

OPERATION:DELETE deletes the page. 

OPERATION:LIVE for live page creation. 

OPERATION:STATIC for static page creation. 

POS : The position in a line at which the value should be written, for contribution to 

a page. 

POS:i 

the (formatted) field value will be pasted over the 

contents of the destination line starting at the i th 

character position. 

SCOPE : The scope for the contribution. Either the contribution is made only to the 

local cache, in which case only local applications sharing that cache will see 

the results of the contribution; or the contribution is sent directly to the 

selected source’s server. 

Arguments 


SCOPE:L or SCOPE:LOCAL the contribution should be local. 

SCOPE:S or SCOPE:SERVER the contribution should be made to the 

source’s server. 





Arguments 

AttrID 


identifying code taken from the AdxAttrRtContribute enumeration or a 

string containing the keyword used to set the attribute using the Mode 

property. 

Return Value 

The value of the requested attribute of type variant. 

32


3.1.6. Source 

Source 

Name of the data source as a string to which the contribution request will be addressed. 

Arguments 


3.1.7. ItemName 

ItemName 

This property provides the name of the item as a string which identifies the item to which to contribute. 

It must be set in order to be able to perform the contribution. 

Arguments 


3.1.8. RunStatus 

RunStatus 

This property allows the application to know whether the object is currently performing contribution. 

Arguments 


Return Value 

This function returns a one of the values listed in the RT_RunStatus enumeration. 

3.2. ADXRTCONTRIBUTE METHODS 

3.2.1. Contribute 

Contribute(FieldNameArray, FieldValueArray) 

This method contributes multiple field values for the item given by the ItemName property. 

Arguments 

FieldNameArray 

FieldValueArray 

A variant, typically an array of field names as strings. 

A variant, typically an array of field values of type variant. There should be 

one field value for each field name given in FieldNameArray. 

Return Value 

Returns True if the contribution has been sent successfully, False otherwise. 

33


Example 

Dim contrib as AdxRtContribute 

Set contrib = New AdxRtContribute 

contrib.Source = "DDS" 

contrib.ItemName = "EUR=" 

ret = contrib.Contribute("BID", "1.0512") 

'Contribute a "BID" field value for the item "EUR=" directly. ' 

Dim FieldNameArray(0 to 1) as Variant 

Dim FieldValueArray(0 to 1) as Variant 

contrib.ItemName = "FRF=" 

FieldNameArray(0) = "BID" 

FieldNameArray(1) = "ASK" 

FieldValueArray(0) = 5.8910 

FieldValueArray(1) = 5.8950 

ret = RtObject.Contribute(FieldNameArray, FieldValueArray) 

'Contribute "BID" and "ASK" field values for the item "FRF=" 

using arrays. ' 

34


4. ADXRTCHAIN 

4.1. ADXRTCHAIN PROPERTIES 

4.1.1. Mode 

Mode 

This property describes how the Data property is to present its results. It is a string which should 

contain a sequence of parameter settings. The allowed parameters are: 

IGNE : The Ignore Empty parameter determines whether empty elements of the 

returned chain contents are removed. 

IGNE:YES 

remove empty entries from the array. 

IGNE:NO 

leave empty entries in the array. 

LAY : The Layout parameter determines how the elements will be arranged in the 

returned array. 

LAY:HOR or LAY:H returns items in a horizontal layout. 

LAY:VER or LAY:V returns items in a vertical layout. 

LIVE : The Live parameter determines whether the chain should continue to be 

supplied with updates once the initial chain data have been fully received. 

This allows an application to decide whether to track changes to the contents 

of the chain coming from the data source. 

LIVE:YES 

continue to receive updates once the chain has been 

received completely. 

LIVE:NO 

supply no more updates once the chain data are 

complete (the default). 

RET : The Return parameter allows the size of the returned array to be controlled. 

RET:An 

return the first n entries of the array as an array. 

RET:n 

return only the n th entry of the array (entries are 

numbered from 1). 

By default no return array size is defined. 

SKIP : The Skip parameter allows various entries in the chain to be skipped before 

returning a reduced array. Entries are numbered from 1. 

SKIP:n 

remove the n th entry from the array. 

SKIP:i-j 

remove all entries from the i th to the j th (inclusive) from 

SKIP:i-j,k 

the array. 

different entries or ranges to skip can be combined in 

a comma-separated list. 

By default no elements are skipped. Often the first few entries of a chain do 

not contain item names. 

UWC : The Update When Completed parameter determines whether update events 

will be signalled to the application through the OnUpdate event callback 

while the different constituent parts of the chain are being retrieved. 

Arguments 


UWC:NO 

UWC:YES 

signal an update event for the retrieval of each part of 

the chain. 

wait until the chain has been retrieved completely 

before generating an update event. 

By default this parameter is active (UWC:YES). 

35



ErrorMode 





Arguments 



ErrorCode 




Arguments 



ErrorString 




Arguments 






Arguments 

AttrID 


identifying code taken from the AdxAttrRtChain enumeration or a string 


Return Value 


36


4.1.6. Source 

Source 

The name of the data source as a string. It must be set in order to be able to request the chain. 

Arguments 



ItemName 

This property provides the name of the item as a string which identifies the chain. It must be set in 

order to be able to request the chain. 

Arguments 


4.1.8. Data 

Data 

This property returns the contents of the chain, as a variant array. 

Arguments 


Return Value 

Returns a one-dimensional array of Variant. The elements contain the names of the items making up 

the chain as strings. The Mode property determines various presentational options. 

Example 

Dim chain as AdxRtChain 

Set chain = New AdxRtChain 

chain.Source = "IDN" 

chain.ItemName = ".FCHI" 

chain.Mode = "IGNE:YES" 

Chain.RequestChain 

ret = chain.Data 

'Set the chain item’s source.' 

'Set the chain item’s name.' 

'Remove empty entries.' 

'Retrieve the list of items in the ".FCHI" chain.' 

4.1.9. DataStatus 

DataStatus 

This property returns the status of the chain’s data received from the source. 

37


Arguments 


Return Value 

This property returns a value taken from the RT_DataStatus enumeration. 


RunStatus 

This property allows the application to know whether the object is currently retrieving chain data. 

Arguments 


Return Value 


4.1.11. SourceStatus 

SourceStatus 

This property returns a value from the RT_SourceStatus enumeration. This value reflects the status 

of the source defined by the Source property of the AdxRtChain object. 

Arguments 


Return Value 

Returns the status of the source of the list object. 




Example 

Public chain as AdxRtChain 


chain.Source = "IDN_SELECTFEED" 

Status = chain.SourceStatus 

'Sets Status to the status of the "IDN_SELECTFEED" source; 

this might be RT_SOURCE_UP or RT_SOURCE_DOWN, for 

example.' 

38


4.2. ADXRTCHAIN METHODS 

4.2.1. RequestChain 

RequestChain() 

This method fetches the data for the chain specified by the Source and ItemName parameters. This 

action occurs asynchronously; the arrival of chain data, or an indication of a request error, causes the 

OnUpdate event to occur. 

Arguments 


Example 

Dim chain as AdxRtChain 


chain.Source = "IDN" 

chain.ItemName = ".FCHI" 

chain.Mode = "IGNE:YES" 

chain.RequestChain 

'Set the chain item’s source.' 

'Set the chain item’s name.' 

'Remove empty entries.' 

'Ask for the chain data.' 

4.3. ADXRTCHAIN EVENTS 


OnUpdate(DataStatus) 

This callback handles updates to the requested data. If the Update When Completed attribute is in 

effect (see the "UWC" keyword of the Mode property), this will occur only once all chain data have been 

retrieved, or some request error occurs. Otherwise, the event may be called a number of times before 

all data have arrived. 

If the Live attribute is active (see the "LIVE" keyword of the Mode property), updates may continue to 

arrive following the completion of the chain’s data, as the source sends changes to the chain’s 

contents. 

Arguments 

DataStatus 

The status of the data retrieved by the request. This is a value taken from the 

RT_DataStatus enumeration. 


OnStatusChange(SourceStatus) 

This callback is called every time a change occurs to the status of the data source specified by the 

Source property while there is an outstanding RequestChain request. 

39


Arguments 

SourceStatus 



40


5. ADXRTHISTORY 

5.1. ADXRTHISTORY PROPERTIES 

5.1.1. Mode 

Mode 

This property describes how the Data property is to present its results. It is a string which should 

contain a sequence of parameter settings. It also allows the definition of the range of dates over which 

historical data is to be retrieved. The allowed parameters are: 

END : The End Date parameter fixes the last date for which historical data should 

be retrieved. 

END:ddmmmyy sets an end date of ddmmmyy. 

By default data will be retrieved up to the current date. 

HEADER : The Header attribute determines whether a “header” row of field names 

should be returned with the data. 

HEADER:YES include a header row. 

HEADER:NO do not include a header row (default). 

If the keyword HEADER is present on its own, it is treated as HEADER:YES. 

FRQ : The Frequency parameter establishes the predefined time-series to consult. 

FRQ:D 

Fetch daily data (default). 

FRQ:W 

Fetch weekly data. 

FRQ:M 

Fetch monthly data. 

FRQ:other 

Fetch data of the frequency specified by the letter 

other. This frequency must be supported by the 

source. 

LAY : The Layout attribute determines how the elements will be arranged in the 

returned array. 

LAY:HOR or LAY:H returns items in a horizontal layout. 

LAY:VER or LAY:V returns items in a vertical layout. 

NBEVENTS : The Number of Events parameter limits the number of historical events that 

will be retrieved. 

NBEVENTS:n return data for no more than n events. 

The default value depends on the frequency setting as follows: 

NBEVENTS:25 with a daily frequency (FRQ:D). 

NBEVENTS:52 with a weekly frequency (FRQ:W). 

NBEVENTS:12 with a monthly frequency (FRQ:M). 

NBEVENTS:25 with any other frequency (FRQ:other). 

EVENTS : Exact number of historical data retrieved {i with i as integer} 

EVENTS:i to retrieve i data points (see the NBEVENTS keyword and the 

Note section below.) 

NULL : The Null attribute dictates how empty entries should be handled. 

NULL:NA 

provide the string value "#N/A ND" instead of null 

values (default). 

NULL:REPEAT copy earlier valid values to this entry, if any. 

NULL:SKIP drop the entry in the returned array. 

RET : The Return parameter allows the size of the returned array to be controlled. 

RET:An 

return the first n entries of the array as an array. 

RET:n 

return only the n th entry of the array (entries are 

numbered from 1). 

By default no return array size is defined. 

41


SORT : The Sort attribute determines how the elements will be sorted in the returned 

array. 

SORT:ASC 

returns event data in ascending (chronological) order. 

SORT:DES 

returns event data in descending (reversechronological) 

order (default). 

START : The Start Date parameter fixes the first date for which historical data should 

be retrieved. 

START:ddmmmyy sets a start date of ddmmmyy. 

There is no default start date. If not constrained by other parameters, the 

whole history is retrieved. 

ZERO : The Zero attribute dictates how entries containing zero values should be 

handled. 

ZERO:NA 

provide the value 0 (zero) for zero values (default). 

ZERO:REPEAT copy earlier valid non-zero to this entry, if any. 

ZERO:SKIP drop the entry in the returned array. 

Arguments 



The NULL keyword defines the action taken only where date entries with null data are encountered. 

Dates before the start date or following the end date of the time series are always ignored. 

The application of the NBEVENTS limit involves counting date entries with null data when the 

NULL:NA or NULL:REPEAT condition is used; these entries are ignored if NULL:SKIP is used. 


ErrorMode 




By default the error mode is set to NO_EXCEPTION. 

Arguments 



ErrorCode 




Arguments 


42



ErrorString 




Arguments 






Arguments 

AttrID 


identifying code taken from the AdxAttrRtHistory enumeration or a string 


Return Value 


5.1.6. Source 

Source 

The name of the data source as a string. It must be set in order to be able to request the time series 

information. 

Arguments 



ItemName 

This property provides the name of the item for which the historical time series is to be retrieved. 

Arguments 


5.1.8. Data 

Data 

This property returns the historical data, as a variant array. 

43


Arguments 


Return Value 

Returns a two-dimensional array of Variant. The elements contain values for the fields listed in 

ExistingFields for each date entry retrieved from the time series. The Mode property determines 

various presentational and selection filtering options. 

5.1.9. DataStatus 

DataStatus 

This property returns the status of the historical data received from the source. 

Arguments 


Return Value 

This property returns a value taken from the RT_DataStatus enumeration. 


RunStatus 

This property allows the application to know whether the object is currently retrieving historical data. 

Arguments 


Return Value 


5.1.11. ExistingFields 

ExistingFields 

This property indicates which fields have been supplied in the returned historical data entries. 

Arguments 


Return Value 

Returns a one-dimensional array of Variant. The elements contain the names of the fields contained in 

each date entry of the Data property, as returned by the time series data source. 

44


5.2. ADXRTHISTORY METHODS 

5.2.1. RequestHistory 

RequestHistory(FieldList) 

This method causes a request for time series data concerning the item identified by the ItemName 

property. Historical data is retrieved for the fields listed in the parameter FieldList, if possible (the 

actual list of fields retrieved will be stored in the ExistingFields property). This action occurs 

asynchronously; the arrival of history data, or an indication of a request error, causes the OnUpdate 

event to occur. 

Arguments 

FieldList 

An array of field names as strings, identifying the fields for which historical 

values should be retrieved. If empty, all fields available in the time series will 

be retrieved. 

5.2.2. FlushData 

FlushData() 

This method causes the history object to forget all data retrieved through a previous call to 

RequestHistory. 

Arguments 

None. 

5.3. ADXRTHISTORY EVENTS 


OnUpdate(DataStatus) 

This callback handles updates to the requested historical data, following a call to the 

RequestHistory method. It may be called a number of times as updates occur, filling the Data 

property with historical event information, before the retrieved time series is complete (according to the 

constraints applied using the Mode property). 

Arguments 

DataStatus 

The status of the data retrieved by the request. This is a value taken from the 

RT_DataStatus enumeration. 

45


6. ADXRTXLIB PARAMETERS AND CONSTANTS 

6.1. ADXRTXLIB ENUMERATED TYPES 

6.1.1. RT_ItemStatus 

RT_ItemStatus 

The property ItemStatus and the ItemStatus parameter to the OnUpdate event handler of the 

AdxRtList object use these values to indicate the status of an individual item retrieved from the 

source. 

Values 

RT_ITEM_OK : The item is valid. 

RT_ITEM_INVALID : The item is not available from the source or is not registered. 

RT_ITEM_UNKNOWN : The item is temporarily in an unknown state. 

RT_ITEM_STALE : The item is known by the source but is not available; data 

associated with it may be out of date. 

6.1.2. RT_FieldStatus 

RT_FieldStatus 

The property FieldStatus of the AdxRtList object uses one of these values to indicate the status 

of a field within an item retrieved from the source. Fields must be defined in the data dictionary file 

(global.mfl), otherwise they will not be recognised. 

Values 

RT_FIELD_OK : The field is present in the field list of its item. 

RT_FIELD_INVALID : The field is not present in the item. 

RT_FIELD_UNKNOWN : The field is temporarily in an unknown state. 

RT_FIELD_UNDEFINED : The field is not defined in the field dictionary of the source. 

6.1.3. RT_SourceStatus 

RT_SourceStatus 

The properties AdxRtList SourceStatus and AdxRtChain SourceStatus, as well as the 

SourceStatus parameter to the AdxRtList OnUpdate event handler, use these values to indicate 

the status of the source used to retrieve the requested information. 

Values 

RT_SOURCE_UP : The data source is available. 

RT_SOURCE_DOWN : The data source is unavailable. 

RT_SOURCE_INVALID : The data source is invalid on this system. 

RT_SOURCE_UNDEFINED : The data source has not yet been defined. 

RT_SOURCE_NOT_SET : The Source property of the object has not been assigned. 

46


6.1.4. RT_ListStatus 

RT_ListStatus 

The property ListStatus and the ListStatus parameter to the OnStatusChange event handler 

of the AdxRtList object use these values to indicate the status of the object itself. 

Values 

RT_LIST_INACTIVE : No real time data items are being requested at present. 

RT_LIST_RUNNING : Real time data items are receiving data images or updates. 

RT_LIST_UPDATES_STOPPED : Update events for real time data items have been 

temporarily stopped. 

RT_LIST_LINKS_CLOSED : Updates for the real time data items are no longer being 

supplied by the source. 

6.1.5. RT_ItemRowView 

RT_ItemRowView 

These values are used as parameters to the AdxRtList ListItems and ItemListCount 

properties to specify how items in the list should be selected. 

Values 

RT_IRV_UPDATED : The item array will contain rows only for those items in the 

list that have been updated. 

RT_IRV_ALL : The item array will contain rows for all items in the list. 

6.1.6. RT_FieldRowView 

RT_FieldRowView 

These values are used as parameters to the AdxRtList ListFields and FieldListCount 

properties to specify how fields in an item should be selected. 

Values 

RT_FRV_EXISTING : The field array will contain rows for all fields in the item. 

RT_FRV_UPDATED : The field array will contain rows only for those fields in the 

item that have been updated. 

RT_FRV_ALL : The field array will contain rows for all fields registered in the 

list for the item. 

6.1.7. RT_ItemColumnView 

RT_ItemColumnView 

These values are used as parameters to the AdxRtList ListItems property to specify which 

information relating to the items in the list should be selected. 

47


Values 

RT_ICV_USERTAG : The item array will contain a column for the item user tags 

set using the UserTag property. 

RT_ICV_STATUS : The item array will contain a column holding the status of 

each item as a value from the RT_ItemStatus 

enumeration. 

6.1.8. RT_FieldColumnView 

RT_FieldColumnView 

These values are used as parameters to the AdxRtList ListFields property to specify which 

information relating to the fields in the item should be selected. 

Values 

RT_FCV_USERTAG : The field array will contain a column for the field user tags 

set using the UserTag property. 

RT_FCV_STATUS : The field array will contain a column holding the status of 

each field as a value from the RT_FieldStatus 

enumeration. 

RT_FCV_VALUE : The field array will contain a column holding the value of 

each field as a variant. 

6.1.9. RT_RunMode 

RT_RunMode 

Values of this type are used by AdxRtList StartUpdates to specify how update signalling should 

be performed. They are also passed to the OnStatusChange event callback for information. 

Values 

RT_MODE_ONTIME_IF_UPDATED : At regular intervals, defined by the "FRQ" attribute of the 

Mode property, all registered items will be checked to see if 

any have been updated by the data source since the 

previous check. For each updated item an OnUpdate event 

will be generated. 

RT_MODE_ONTIME : OnTime events will be generated at regular intervals, defined 

by the "FRQ" attribute of the Mode property, whether or not 

any data updates have been received for the items in the list. 

RT_MODE_ONUPDATE : OnUpdate events will be generated for each item in the list 

every time data updates are received for that item from the 

source. 

RT_MODE_IMAGE : An OnImage event will be generated once a single data 

image has been received for each of the items in the list, or 

after a time-out. 

RT_MODE_NOT_SET : No update run mode has been set using the StartUpdates 

method. 

48


6.1.10. RT_DataStatus 

RT_DataStatus 

This enumeration lists the different values used to describe the status of data retrieved by the objects. 

Values of this type are passed as parameters to the event callback functions AdxRtList OnImage, 

AdxRtHistory OnUpdate, and AdxRtChain OnUpdate. The values are also those used by the 

AdxRtHistory DataStatus and AdxRtChain DataStatus properties. 

Values 

RT_DS_FULL : This value indicates that all desired data have been retrieved 

and are available. 

RT_DS_PARTIAL : This value indicates that some of the requested data are 

available, but that the request has not yet been entirely 

satisfied. 

RT_DS_NULL_ERROR : This value indicates that an error has occurred and that, 

consequently, no data are available. 

RT_DS_NULL_EMPTY : This value indicates that the request returned no data. 

RT_DS_NULL_TIMEOUT : This value indicates that a timeout occurred before any data 

could be retrieved. 

6.1.11. RT_RunStatus 

RT_RunStatus 

This enumeration lists the different states of an object regarding its requests of the source. The 

properties AdxRtContribute RunStatus, AdxRtHistory RunStatus and AdxRtChain 

RunStatus return these values. 

Values 

RT_RS_READY : The object is ready to be used to make a request for data 

from a data source. 

RT_RS_BUSY : The object is currently awaiting a response from the server. 

For objects that accept multiple data updates from the 

source, this means that more update events can be 

expected. 

RT_RS_NOT_INIT : The object does not have enough information to be able to 

make a request. 

6.1.12. RT_DebugLevel 

RT_DebugLevel 

This enumeration lists the valid values for the DebugLevel property of the AdxRtList object. 

Values 

RT_DEBUG_NO : No debug messages will be sent. Exceptions indicate invalid 

parameters and object event interfaces are used to signal 

system errors. 

49


RT_DEBUG_IMMEDIATE : The validity of all parameters is checked before the client 

application’s actions are allowed to proceed. This may 

require waiting for responses from remote data sources. 

Debug messages will be generated immediately following the 

actions that provoked them. 

6.1.13. AdxErrorMode 

AdxErrorMode 

This enumeration lists the valid values for the ErrorMode property in each of the AdxRtxLib objects. 

Values 

NO_EXCEPTION : No action is taken when an error is detected. In this mode, 

the client application must consult the value of the 

ErrorCode property to know if an error has been 

encountered. 

DIALOGBOX : A dialog box is displayed when an error occurs. 

EXCEPTION : An exception is thrown an error occurs. 

6.1.14. AdxAttrRtList 

AdxAttrRtList 

This enumeration provides identifiers for the AdxRtList object’s attributes. These are changed 

indirectly by supplying a new string to the object’s Mode property. 

Values 

ATTR1L_RTLIST_FRQ : This value identifies the frequency of regular OnTime events. 

In the Mode string, this is set using the "FRQ" keyword. 

ATTR1L_RTLIST_TIMEOUT : This value identifies the length of the timeout period after 

which requests for item data images will be abandoned. In 

the Mode string, this is set using the "TIMEOUT" keyword. 

6.1.15. AdxAttrRtContribute 

AdxAttrRtContribute 

This enumeration provides identifiers for the AdxRtContribute object’s attributes. These are 

changed indirectly by supplying a new string to the object’s Mode property. 

Values 

ATTR1E_RTCTRB_SCOPE : This value determines whether the contribution should be 

local (updating a value in the local cache) or should be sent 

to the server. In the Mode string, this is set using the 

"SCOPE" keyword. 

50


6.1.16. AdxAttrRtChain 

AdxAttrRtChain 

This enumeration provides identifiers for the AdxRtChain object’s attributes. These are changed 


Values 

ATTR1E_RTCHAIN_IGNE : This value identifies the Ignore Empty attribute. In the Mode 

string, this is set using the "IGNE" keyword. 

ATTR1E_RTCHAIN_LAY : This value identifies the Layout mode. In the Mode string, this 

is set using the "LAY" keyword. 

ATTR1E_RTCHAIN_LIVE : This value identifies the Live attribute. In the Mode string, this 

is set using the "LIVE" keyword. 

ATTR1S_RTCHAIN_RET : This value identifies the Return attribute. In the Mode string, 

this is set using the "RET" keyword. 

ATTR1S_RTCHAIN_SKIP : This value identifies the Skip attribute. In the Mode string, 

this is set using the "SKIP" keyword. 

ATTR1E_RTCHAIN_UWC : This value identifies the Update When Completed attribute. 

In the Mode string, this is set using the "UWC" keyword. 

6.1.17. AdxAttrRtHistory 

AdxAttrRtHistory 

This enumeration provides identifiers for the AdxRtHistory object’s attributes. These are changed 


Values 

ATTR1E_RTHIST_HEADER : This value identifies the Header attribute. In the Mode string, 

this is set using the "HEADER" keyword. 

ATTR1E_RTHIST_LAY : This value identifies the Layout attribute. In the Mode string, 

this is set using the "LAY" keyword. 

ATTR1E_RTHIST_NULL : This value identifies the Null attribute. In the Mode string, this 

is set using the "NULL" keyword. 

ATTR1S_RTHIST_RET : This value identifies the Return parameter. In the Mode 

string, this is set using the "RET" keyword. 

ATTR1E_RTHIST_ZERO : This value identifies the Zero attribute. In the Mode string, 

this is set using the "ZERO" keyword. 

ATTR1E_RTHIST_SORT : This value identifies the Sort attribute. In the Mode string, this 

is set using the "SORT" keyword. 

ATTR1D_RTHIST_END : This value identifies the End Date parameter. In the Mode 

string, this is set using the "END" keyword. 

ATTR1E_RTHIST_FRQ : This value identifies the Frequency parameter. In the Mode 

string, this is set using the "FRQ" keyword. 

ATTR1I_RTHIST_NBEVENTS : This value identifies the Number of Events parameter. In the 

Mode string, this is set using the "NBEVENTS" keyword. 

ATTR1D_RTHIST_START : This value identifies the Start Date parameter. In the Mode 

string, this is set using the "START" keyword. 

51

Reuters AdfinX Real Time 1.0 Library User Guide (Doc. No. 4510529)

Create successful ePaper yourself

Delete template?

Save as template?