Developer

Rule Data Types

Each term within a rule is evaluated, and then returns a value. The value returned by a given term is in the data type requested by the term caller.

All terms return a value in one of the following data types, which are the only data types available within the rule structure:
  • Boolean
  • Integral Number
  • Decimal Number
  • String
  • Location (or “GPS Location”)
  • Property

This list does not restrict the types of values within the application that may be referenced in rules. Other data types, such as those found in property definitions, are converted to one of the above types when the term referencing the property is evaluated. The function terms available for use within the rule structure will return one or more of the above-listed data types.

Data Type Conversion in Rules

When a data term is evaluated within a rule, it will be asked for one of the data types available within rules. The native data type of the term’s source may not be one of these six data types. This is most likely to be true when working with property or global definitions. There are far more data types for each of these definition types than those for the rule definition.

When a data term is evaluated within a rule and the data type it is asked for is not one of the six for a rule definition, the value of that term will be converted to one of the rule data types assuming that data term supports such a conversion.

The following table contains a cross reference of all property data types and rule data types. Each rule type and property type intersection in the table indicates whether or not the property type can be converted to the rule data type:
From Property Data Type To... Boolean Integral Number Decimal Number String Location Property
Boolean Yes No No Yes* No No
Collection No No No No No Yes
Complex Table Selection No No No Yes No No
Data Table Selection No No No Yes No No
Date No Yes* Yes* Yes No No
Date and Time No Yes* Yes* Yes No No
Decimal Number Yes* Yes* Yes Yes No No
Duration No Yes Yes Yes No No
External Data No No No Yes* No No
Identifier No Yes Yes Yes No No
Image No No No No No No
Integral Number Yes* Yes Yes Yes No No
Location No No No No Yes No
Object No No No No No Yes
Signature No No No No No No
String Yes* Yes Yes Yes No No
Time No Yes* Yes* Yes No No

* - This conversion may not be type safe or requires further explanation on the resulting value from such a conversion. See the description of the rule data type for more information on this conversion.

Boolean Rule Data Type

The Boolean data type within rules is similar to Booleans in all areas of software development, containing a value of true or false.

When converting from an integral or decimal number property type to a Boolean rule type a value of zero is treated as false and a value other than zero is treated as true.

When converting from a string property type to a Boolean rule type, the value of the Boolean will be set to true if the string value is “true.” Any other string value is treated as false.

Integral Number Rule Data Type

The integral number data type within rules stores whole positive and negative values, or zero. This is a 32-bit integer value.

When converting from a date property type, or any other data source of type date, to an integral number rule type the value returned will be the number of days from the epoch date of January 1, 1901. Positive numbers represent the number of days after this date and negative numbers are dates before it.

When converting from a time property type, or any other time data source, to an integral number rule type the value returned will be the number of seconds after midnight. This will always be a positive integer.

When converting from a date and time property type, or any other date and time data source, to an integral number rule type the value returned will be the number of seconds from the Agentry epoch date and time of January 1, 1901 12:00:00 am. A positive number represents a date and time after the epoch date and time, and negative numbers represent a date and time before.

A decimal number property can be converted to an integral number rule type. However this conversion is not considered type safe. Any fractional portion within the source decimal number will be truncated from the resulting integral number.

Decimal Number Rule Data Type

The decimal number rule data type stores numeric values with a fractional portion. This is the equivalent to a 32-bit floating point decimal number.

When converting from a date property type, or any other data source of type date, to a decimal number rule type the value returned will be the number of days from the epoch date of January 1, 1901. Positive numbers represent the number of days after this date and negative numbers are dates before it.

When converting from a time property type, or any other time data source, to a decimal number rule type the value returned will be the number of seconds after midnight. This will always be a positive integer.

When converting from a date and time property type, or any other date and time data source, to a decimal number rule type the value returned will be the number of seconds from the Agentry epoch date and time of January 1, 1901 12:00:00 am. A positive number represents a date and time after the epoch date and time, and negative numbers represent a date and time before.

String Rule Data Type

A string rule data type stores one or more unicode characters as a string value.

When converting a Boolean property to a string rule type, the resulting value of the string will depend on the definition of the Boolean property. The attributes within the Boolean property True Value and False Value contain the text value returned by that property in a string context. A data term for a Boolean property evaluated in a string context will then return the appropriate string depending whether or not the property is set to true or false.

When converting an external data property to a string rule type, the return value will be the full path and file name for the file referenced by the property. If the property does not reference a file, an empty string is returned.

Location Rule Data Type

The location rule type stores a value returned from a GPS unit that includes the latitude, longitude, number of satellites, and precision of the location value. This data type cannot be converted to other data types within the rule and other data types cannot be converted to a location.

There are specific rule functions within the System category of rules provided to work with the Location data type. These include functions for converting two decimal values assumed to be latitude and longitude coordinates to a location value, as well as those for calculating distances between two location values, and a function to retrieve a GPS location from the GPS unit for the client device.

Property Rule Data Type

The property rule data type is unique among the different data types within rules. A property type is the term applied to any point within the rule where a definition is expected. Certain functions are provided to allow for searching object collections, or to work with external data properties. These functions will take one or more parameters of type property and may also return a value of this type.

Many of the different functions for these types are intended for use with certain types of definitions within the application. The information for these functions indicate the expected definition type. The important concept for a property rule type is that what is returned from such a term is the definition itself. When a target path references a definition for a caller expecting a property rule type, that definition is returned, not just its value.