wwtools/aot/dev-guide/appendix-d-data-types.md

ArchestrA Data Types

Objects that you create using the ArchestrA Object Toolkit can have attributes of any standard data type that is supported in the ArchestrA environment. This appendix describes the available data types and provides some notes on their recommended use.

List of ArchestrA Data Types

The ArchestrA environment supports the following data types. The defaults are used at startup time or when there is no data available. For notes on using each type correctly, see Using Data Types Correctly.

For additional information on the operations supported by each data type, see the class documentation in the ArchestrA Object Toolkit Reference Guide.

Data Type	Valid Values	Notes
Boolean	True, False (default: False)
Integer	-2147483648 to 2147483647, signed (default: 0)
Float	3.40282 E+38 to -3.40282 E+38, signed (default: NaN)	32-bit IEEE single-precision floating point, used when 6-7 significant digits are needed. Smallest representable absolute value is 1.175 E-38.
Double	1.79769 E+308 to -1.79769 E+308, signed (default: NaN)	64-bit IEEE double-precision floating point, used when 15-16 significant digits are needed. Smallest representable absolute value is 2.23 E-308.
String	0 to 1024 characters, default: empty string	Variable-length Unicode string, size: 4 + 2*n bytes (n = number of characters)
Time	Microsoft FILETIME values (default: “zero time”)	64-bit FILETIME value in UTC (Coordinated Universal Time). Represents the number of 100-millisecond ticks since January 1, 1601, 00:00:00 (“zero time”).
Elapsed Time	Number of 100-ms ticks, signed (default: 0)	Stored as a 64-bit FILETIME structure. For example, -1 corresponds to a duration of “-00:00:00.0000001”.
Attribute Reference	Valid reference strings (default: empty string and null handle)	Standard structure containing a reference string and MxHandle (bound or unbound). A string of "---" results in a null handle, and no warning is generated when the object is validated (that is, when the user saves the object configuration). A string of "---.---" results in a null handle, but a warning is generated on validation.
MxStatus	Default: Success	Standard structure containing access status information for a Message Exchange call.
Data Type	Enumeration, see notes (default: MxNoData)	Data type of an attribute. Valid enumeration values are: MxNoData, MxBoolean, MxInteger, MxFloat, MxDouble, MxString, MxTime, MxElapsedTime, MxReference, MxStatus, MxDataType, MxSecurityClassification, MxQuality, MxCustomEnum, MxCustomStruct, MxInternationalizedString and MxBigString.
Custom Enumeration	Default: ordinal=1, String=String1	Enumerations start at the value 1. Zero is not a valid ordinal value for an enumeration.
Custom Structure	Default: GUID = 0, length = 0.	Provides support for custom data in the form of a GUID and byte array.
Internationalized String	0 to 1024 characters, default: empty string	A vector of strings and corresponding locale IDs in the configuration database. An MxString at runtime.
Big String	0 to 2147483647 characters, default: empty string	Variable-length Unicode string, size: 4 + 2*n bytes (n = number of characters)
Variant	N/A	Use this data type if the actual type of an attribute cannot be determined in advance.

Coercion Rules for ArchestrA Data Types

In some cases, ArchestrA data types can be “coerced” when reading from or writing to an attribute. This means that the client can specify a different data type than the attribute actually has. The value is implicitly converted from the specified data type to the data type required by the attribute.

For example, if an output configured for Boolean values sends a value to an Integer attribute, the write operation succeeds and the Boolean value is automatically converted to a 0 or 1.

Coercion is only supported for some combinations of data types. Trying to use coercion for unsupported combinations results in an exception being thrown. Also, coercion generally fails in case of an overflow, that is, if the value is outside the valid range of the target type.

The following tables list the supported combinations and required value formats.

Coercion from Boolean Values

To ...	Values / Notes
Integer	False = 0, True = 1
Float, Double	False = 0.0, True = 1.0
String, Big String	“false” or “true”

Coercion from Integer Values

To ...	Values / Notes
Boolean	0 is False, non-zero is True.
Float, Double	Value is preserved as is.
String, Big String	Value is formatted as string.
Elapsed Time	Interpreted as number of seconds.
Enumeration types	Interpreted as ordinal value of enumeration.

Coercion from Float or Double Values

To ...	Values / Notes
Boolean	0.0 is False, non-zero is True.
Double (from Float)	Value is preserved as is.
Float (from Double)	Values less than the minimum absolute Float value of 1.17549E-38 result in a value of Float 0.0, that is, precision may be lost.
Integer	Value is rounded.
String, Big String	Value is formatted as string.
Elapsed Time	Value is interpreted as number of seconds and rounded.
Enumeration types	Interpreted as ordinal value of enumeration.

Coercion from String or Big String Values

To ...	Values / Notes
Boolean	“False” (any case) is False, “True“ (any case) is True. All other values result in an error.
Float, Double	String must use the following format: [whitespace][sign][digits][.digits] [{d|D|e|E}][sign][digits]. Precision may be lost. A string of “NaN” (any case) results in an IEEE NaN value.
Integer	String must represent a valid signed or unsigned Integer.
Elapsed Time	String must use the following format: [-[DDDDDD.] [HH:MM:]SS[.fffffff], where DDDDDD is from 0 to 999999, HH is from 0 to 23, MM is from 0 to 59, SS is from 0 to 59, fffffff is fractional seconds (one through seven digits). Parts in brackets are optional.
Time	String must use correct date/time syntax for the current locale.
Data Type	String must be a valid enumeration label (“MxInteger”, “MxFloat”, etc.)
Custom Enumeration	Interpreted as string part of enumeration. No checking is done to determine if the string is valid.
Reference	String is set as reference string. No syntax checking is done.

Coercion from Time Values

To ...	Values / Notes
String, Big String	Value is formatted according to the time format specified by the current locale. “Zero time” (1/1/1601, 00:00:00) results in a blank string.

Coercion from Elapsed Time Values

To ...	Values / Notes
Integer	Converted to number of seconds.
Float, Double	Converted to number of seconds.
String, Big String	String uses the following format: [-]DDDDDD HH:MM:SS.fffffff

Coercion from MxStatus Values

To ...	Values / Notes
String, Big String	String is generated from the Category and Detail information of the MxStatus value. If Category is OK, the string is empty.

Coercion from Data Type Values

To ...	Values / Notes
Integer, Float, Double	Converted to ordinal value.
String, Big String	Converted to type label, for example, “MxInteger”
Elapsed Time	Value is interpreted as number of seconds and rounded.
Enumeration types	Interpreted as ordinal value of enumeration.

Coercion from Custom Enumeration Values

To ...	Values / Notes
Integer, Float, Double	Converted to ordinal value.
String, Big String	Converted to string value, for example, “MyEnum1”

Coercion from Custom Structure Values

To ...	Values / Notes
String, Big String	Qualifier (GUID) is converted to string.

Using Data Types Correctly

Follow these guidelines on using specific data types.

Custom Enumeration vs. Integer

When defining an attribute that contains enumeration values, use the Custom Enumeration data type, not Integer.

There are two criteria to distinguish an enumeration attribute from a simple Integer attribute:

• In an enumeration, each possible value has a specific meaning and represents a mode, state, etc.
• The values of an enumeration cannot be meaningfully compared using comparison operators (>, <, <=, >=).

For each Custom Enumeration attribute, you must define a second attribute containing an array of strings that defines the possible enumeration values. Often, these values shouldn’t be changed by the end user. If this is the case, set the array attribute’s category to Constant so that users can’t modify it.

Absolute and Elapsed Times

Use the Elapsed Time data type for storing an “elapsed time,” that is, an amount of time. Avoid using Integer or Float attributes with associated units of measure (like seconds, minutes...) for this purpose. The only exception is very short amounts of time expressed in milliseconds. These can be stored as an Integer value.

Elapsed Time and Time attributes have a standard string representation. The ArchestrA framework automatically converts them to and from strings. They do not require an associated engineering unit.

Internationalized String

Use the Internationalized String data type to define string attributes that contain translations of a string for multiple target languages. A good example would be attributes containing an Engineering Unit name.

Use the Object Designer to define the default value for US English.

At config time, you can use the methods of the CMxInternationalizedString class to get and set the string values for each locale. For more information, see the ArchestrA Object Toolkit Reference Guide. For example:

//Get a string value using locale 1033
string temp = Attribute1.GetString(1033);
//Write a string value using locale 1033
Attribute1.SetString(1033, "MyString");
//Create a local copy of an Internationalized String
InternationalizedString[] temp = Attribute1.GetInternationalizedStrings();

You can’t modify InternationalizedString attributes at run time.

Big String

The Big String data type is designed to let you create reasonably large strings beyond the 1,024 character limitation of the String data type. Theoretically, it allows you to create strings up to 2,147,483,647 characters in length. In practice, available system memory and system performance impose much lower limits. A reasonable practical maximum for a single attribute of this type would be around 10 MB.

Attribute References

Use the Attribute Reference data type to store the fully qualified name of an attribute. For example, the Input and Output primitives use attributes of this type to hold the input source or output destination.

You can read and write attribute references as strings. However, they are different from strings. They also include binding (location) information to improve the startup performance of the messaging system. Therefore, don’t use simple strings to store reference information.

You can use two default values for an attribute reference to indicate that the reference is unspecified:

• Use “---.---” to indicate that the user must specify a reference. If the user doesn’t specify a reference, this default value causes a warning when the object’s configuration is validated.
• Use “---” to indicate that the reference is optional. This default value does not cause a warning when the object’s configuration is validated.

You will rarely need to create attributes of this data type. In most cases, you will simply use the existing Input and Output primitives for communicating with other objects.

Variant (Unspecified) Data Type

Use the Variant data type if the actual type of an attribute cannot be determined in advance. You can then include custom config time code that lets the user select the actual data type while configuring the object. The data type can also be modified when the object starts up at runtime.

An example of this is the Input primitive. This primitive gets data from another object, regardless of its type, and stores the value in its “Value” attribute. The data type of the value attribute therefore depends on the type of data that the input primitive is being used to retrieve.

In certain cases, it may be helpful to configure and persist the datatype itself (Boolean, Float, String, etc.) as an attribute. To do this, there is a special data type called “Data Type.” For example, the Input and Output primitives include an attribute of this type to configure the desired type of their value attribute.

Arrays

You can configure attributes of any data type as arrays. When defining your object in the Object Designer, you can specify the initial number of elements and the initial value of each element.

The size of an array can be changed at config time or run time. If you want to fix the size of an array, you must create config time and run time set handlers that ensure that the size of the array is not changed.