Using "Element" objects

An element is a variant type. That is they can represent any of the data types supported by the blpapi. Elements can represent simple scalar values like (float, string), arrays of simple types, complex values (sequences/choices), and arrays of complex values.

Accessing Elements

Elements are used when accessing messages received from the API, and when preparing requests for API services. There are two classes of accessor/manipulators that are used to access/manipulate elements. When accessing simple values and arrays, the "GetValueAsX" family of functions are used where 'X' is the target data type(e.g., "GetValueAsInt32"). For simplicity, all "GetValueAsX" functions can optionally be supplied with an index parameter to access elements of an array. For scalar elements, index should not be supplied, or zero should be supplied. The following are examples of accessing simple and array elements.

This example shows how to access the value of a scalar element as an integer number. Then goes on to show how to access the same element as a String

	Copy
Element e; ... int x = e.GetValueAsIn32(); System.Console.WriteLine(e.GetValueAsString()); (or) System.Console.WriteLine(e.GetValueAsString(0));

The following example shows how to access array elements

	Copy
int count = e.NumValues; for (int i = 0; i < count; ++i) { System.Console.WriteLine(e.GetValueAsString(i)); }

Use NumValues to determine the number of values available. For scalar values, it will return either 0 or 1. For arrays it will return the actual number of values in the array.

Complex elements contain named sub-elements. Sub-elements are accessed using the "GetElement", and "GetElementAsX" accessor functions. To demonstrate, the following example shows how to access the "city" sub-element of an "address" element:

	Copy
Element address; ... address.GetElement("city");

The following example retrieves the value of the "city" sub-element as a string value.

	Copy
address.GetElementAsString("city");

To determine the number of available sub elements in a given element, the "NumElements" accessor can be used. To retrieve the Nth available sub-element of a complex element, the "GetElement(int)" accessor can be used. For example:

	Copy
int numElements = address.NumElements; for (int i = 0; i < numElements; ++i) { Element e = address.GetElement(i); System.Console.WriteLine(e.Name + " = " + e.GetValueAsString()); }

Manipulating Elements

Elements are also used to submit input for API services (e.g., preparing a reference data request). Just as when accessing element values, there are two types of manipulators used to set elements. To set the value of simple elements, and arrays of simple elements, the "SetValue", and "AppendValue" manipulator are used. For example

	Copy
Request request; ... Element securitiy = request.GetElement("security"); security.SetValue("IBM UN Equity"); Element fields = request.GetElement("fields"); fields.AppendValue("DS003"); fields.AppendValue("PX_LAST");

request.SetElement("security", "IBM UN Equity");

Methods which specify a Element name come in two forms. One which takes a Name as a parameter and one which takes a String. The form which takes Name is more efficient. However, it requires the Name to have been created in the global name table.

Type Conversions

The API will convert data types as long as there is no loss of precision involved. So
- A BOOL can be returned as bool, char, Int32, Int64, Float32, Float64, String (the string will be "true" or "false")
- A BOOL can be set from bool, String (if it has a value of "y", "n", "yes", "no", "true" or "false")
- A CHAR can be returned as char, Int32, Int64, Float32, Float64, String
- A CHAR can be set from char
- An INT32 can be returned as Int32, Int64, Float64, String
- An INT32 can be set from char, Int32
- An INT64 can be returned as Int64, String
- An INT64 can be set from char, Int32, Int64
- A FLOAT32 can be returned as Float32, Float64, String
- A FLOAT32 can be set from char, Float32
- A FLOAT64 can be returned as Float64, String
- A FLOAT64 can be set from char, Float32, Float64