Every Data Table may be encoded into a string (or decoded from a string). Encoding is used to transfer Data Tables over the network using the AggreGate Communications Protocol, or to define custom context variables, functions and events in AggreGate Agent.
Data Tables may be encoded in two modes:
| • | Using visible separators |
| • | Using invisible separator |
Three special characters are used as separators for encoding:
Visible Separator |
Invisible Separator (character code) |
< |
0x1C |
> |
0x1D |
= |
0x1E |
In this article all examples use visible separators. The only limitation when encoding a table using visible separators is that its different elements, when they are encoded to strings, must not contain these separators.
Elements
Generally, Data Table and its different parts are encoded into string as a number of elements of the following format:
<[element_name=]element_value>
Both the name and value may include any character except for those used by AggreGate Communication Protocol or used to encode the element itself. An element's value may be an encoded list of nested elements.
Here is the format for an encoded data table:
<F=record_format>[<I=>][<R=record>][<R=record>]…
Element Name |
Element Value |
F |
Table format descriptor, defining names and types of all columns in the data table and other table properties. Its encoding is described here. |
I |
Invalidator element. If this element exists in the data table, the whole table is considered as invalid. When AggreGate Server requests a variable value from an Agent, the Agent first acknowledges this request, and then begins polling the records from the hardware device. In the meanwhile, AggreGate Server "knows" that it is receiving a complete and correct table. If at this point there is a sudden failure between the Agent and the hardware device, and for some reason the Agent does not receive the data it should get from the hardware device, the Agent now inserts an Invalidator element into the data table sent to the server. This element is actually the Agent telling AggreGate Server "I cannot fully obtain this data". Having received this element, AggreGate Server now knows the operation could not actually be completed. |
R |
Record of the data table. Records are encoded one by one. Format of encoded records is described below. |
|
Example: <F=<<IP><S><F=C>><M=1><X=1>><R=<192.168.1.88>> This example shows an encoded data table those format defined one string field called "IP", and that contains one record with value "192.168.1.88". See details of record and format encoding below. |
record_format is included in every data table, even if it is empty. It's built like this:
<field_format><field_format>…[<F=flags>][<V=table_validators>][<R=record_validators>][M=min_records][X=max_records][<B=bindings>][<N=naming_expression>]
Elements with no identifiers (as shown in the beginning of the example above, <field_format>) are considered to be encoded formats descriptors of table fields. Field format descriptors are encoded one by one, starting from the first field.
Element Name |
Element Value |
F |
Combination of zero or more of the following flags: “R” (“Reodrerable”) - indicates rows of this table may be reordered by AggreGate users editing it. “U” (“Unresizable”) - indicates that users cannot add/remove rows when editing the table. |
V |
Table validators that help perform complex validation of a whole table. |
R |
Record validators that are used to validate every record. |
B |
Table bindings. |
M |
Minimal allowed number of records in the table. |
X |
Maximal allowed number of records in the table. |
N |
Table naming expression. |
|
Example: <<date><D>><M=1><X=1> This example format described a one-cell table (one field, minimum and maximum record count is also one). The only field's name is "date", and it's type is Date. See details of field format encoding below. |
|
Example: <<id><S><D=Card ID><V=<L=10 10>>><<name><S><D=Cardholder Name>><M=0><X=255> This format describes a two-fields table that may contain from 0 to 255 records. First string field is called "id" and it's description is "Card ID". It has a limits validator that restricts value length to exactly 10 characters. Second field is also of string type, it's called "name". |
field_format is a string describing one field in a Data Table. It's formatted like this:
<name><type>[<F=flags>][<A=default>][<D=description>][<H=help>][<S=selection_values>][<V=validators>][<E=editor>]
The first two elements have no names. The first element is the field name, and the second one contains the field type code (see table below).
Element Name |
Element Value |
F |
Combination of zero or more of the following flags: “N” (“Nullable”) - indicates that column can contain NULL values “O” (“Optional”) - indicates that column in optional “E” (“Extendable selection values”) – indicates that field may contain values that are not listed in selection_values “R” (“Read only”) – indicates that the field value is read only “C” (“Not replicated”) - indicates that value of this field is not replicated during Data Table Copy operations “H” (“Hidden”) – indicates that column should not be visible during Data Table edit operations “K” (“Key field”) - indicates that column is a key field. Key fields are used in data table smart copy operation. Another use is a key fields validator that ensures that table doesn't contain records with equal combinations of all key fields. |
A |
Default value of field encoded into a string as covered in value encoding section. |
D |
Field description. |
H |
Field help (detailed description). |
S |
List of selection values for the field. See encoding rules here. |
V |
List of field validators. See encoding rules here. |
E |
Code of editor/renderer. This element enables custom visual representation of field value. Supported editors and renderers are listed here. |
O |
Editor-specific options. |
I |
String ID of field icon. |
G |
Field group. |
|
Example: <value><I> This is the simplest possible field format descriptor that defines the integer field called "value". |
|
Example: <period><L><A=30000><D=Check Period><V=<L=100 1000000>><E=period><O=0 4> This format descriptor defines a long (64-bit integer) field with default value 30000. Field description is "Check Period". If has a limits validator that restricts values to the range 100..1000000. Editor/renderer type instructs the system to use Time Period editor for editing field value. |
Field Types AND Value ENCODING
Type Code |
Type |
Comments and value encoding rules |
|
S |
String field |
Yes |
Inserted "as is" |
I |
Integer field |
Converted to string |
|
L |
Long field |
Converted to string |
|
B |
Boolean field |
TRUE is encoded as string "1" and FALSE as string "0" |
|
F |
Float field |
Converted to string |
|
D |
Date field |
Converted to string in the form "yyyy-MM-dd HH:mm:ss.SSS", where yyyy is year MM is month dd is day of month HH is hour (0-23) mm is minutes ss is seconds SSS is milliseconds |
|
T |
Data Table field |
Yes |
Nested data table is encoded to string according to the Data Table Encoding rules |
C |
Color field |
Converted to string in the form "#RRGGBB", where RR is red value (0-255) is hex form GG is green value (0-255) is hex form BB is blue value (0-255) is hex form |
|
A |
Data Block field |
Yes |
Selection values for the field are encoded as a list of elements. Each element's name is the selection value's visible description for the user (what the user will see in the listbox). The element's value is the selection value, encoded into a string as described in the value encoding section.
|
Example: A list of three selection values for an integer field may be encoded as follows: <Zero=0><One=1><Two=2> |
Field validators are encoded as a list of elements, one per every validator. The element's name is a type code of the validator while its value contains validator-specific options.
Field Validators
Here is a list of supported field validators:
Type Code |
Description |
Suitable Field Types |
Validator-Specific Options |
L |
Limits Validator. Checks if a value is within the range defined by validator parameters. |
String, Integer, Long, Float, Data |
Validator options are encoded into a string as two integer numbers separated by a space. The first number indicates the minimum value of a range, and the second number specifies the maximum value. These numbers have different meaning for different field types: For String fields, these parameters limit minimal and maximal length of the string. For Integer, Long and Float fields they indicate minimal and maximal value. For Data fields they limit number of bytes that can be contained in the data block. Limits are inclusive for all field types (i.e, a limit of "3" would permit a string such as abc -- containing 3 characters). |
R |
Regular Expression Validator. Checks if a string value matches a regular expression specified by the validator parameter. |
String |
Validator option string contains a regular expression to which the field value will be matched. It may be followed by an optional error message separated from the regular expression by a ^^ string. If validation fails (i.e. string value does not match the regular expression), this error message will be shown to the user. |
|
Example 1: <L=0 255> If this limits validator is added to the format of string field, it will allow only Strings those length is from 0 to 255 characters. It it is defined for an Integer fields, it will restrict field values to the numbers that are greater or equal to 0 and less or equal to 255. Example 2: <R=^[_A-Za-z0-9-]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)*(\\.[_A-Za-z0-9-]+)^^Invalid E-Mail> ^[_A-Za-z0-9-]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)*(\\.[_A-Za-z0-9-]+) is a regex (The first ^ mark belong to it). After this regex, ^^ is used as a separator and is then followed by the text for the error message, "Invalid E-Mail". This regular expression validator checks if a field contains a valid e-mail address and fails with an Invalid E-Mail error if it doesn't. See Regular Expressions Syntax appendix for more information on regular expressions. |
Record Validators
Here is a list of supported record validators:
Type Code |
Description |
Validator-Specific Options |
K |
Key Fields. Checks whether a combination of key field values does not already exists in the table. Applied during record addition. |
None - key fields are marked with Key Field flag of field format. |
Table Validators
Here is a list of supported table validators:
Type Code |
Description |
Validator-Specific Options |
K |
Key Fields. Checks whether combination of key field values if unique for every record. |
None - key fields are marked with Key Field flag of field format. |
E |
Expression Validator. Evaluates an expression having this table as a default table. If expression returns NULL table is considered valid, otherwise expression output is converted to string and used as error text. |
The text of expression. |
|
Example: <E={activationThreshold} > {deactivationThreshold} ? null : 'Activation threshold must be greater than deactivation threshold'> Checks that one field greater than another.
|
A NULL ("<Not set>") value is encoded with a single 0x1A (SUB) character. This rule applies to encoding NULL values of table cells, default values of table fields, selection values and any other place where field values may appear.
If visible separators are used to encode the Data Table, NULL values are encoded as "^" characters.
Field values are transfer-encoded to remove characters used by the Data Table encoding format and AggreGate Communications Protocol. These characters are substituted with special patterns according to the following table:
Character |
Replaced by |
0x25 (%) |
%% |
0x02 (STX) |
%^ |
0x0D (CR) |
%$ |
0x17 (ETB) |
%/ |
0x1C (FS) |
%< |
0x1D (GS) |
%> |
0x1E (RS) |
%= |
Note that the patterns in the Replaced by column are literal strings -- they're just what you see above.
Each data record is encoded into a string according to the following format:
[<I=record_ID>]<field_value><field_value>…
Elements without names are field values. Field values are encoded one by one, in the same order as they appear in the table format descriptor.
Element Name |
Element Value |
I |
Record ID (Long number) |