Data Record XML Details
Introduction
Most Galil controllers have a data record. The data record is a binary representation of much of the hardware's current state. By analyzing this controller snapshot, much information can be obtained about the machine.
GDK uses record.xml to determine how to dissect the binary data record.
The Element Tags
<records version="6">
This is the XML root element. It contains the version of the record syntax.
<vmap>
<vmap name="SC">
Provides a value map used to map a data record value to a human-readable string. This is useful for data such as stop code. Value maps must be defined prior to any use in a field element.
The <vmap> element has one mandatory attribute, name. This is the name used to reference the value map.
<map>
<map in="31" out="PVT completed normally" />
<map> is a sub-element of <vmap>. It represents a value-string mapping for the value map.
The mandatory attribute in defines the input to the mapping, namely the value.
The mandatory attribute out defines the output from the mapping, namely the string.
<script>
<script>function aq_p(){ return (aq==3)?5:4; }</script>
The <script> element holds JavaScript functions for use by data record fields whose meaning depends on controller settings. For instance, analog inputs depend on the value of the AQ command.
The content of the <script> element will be added to the JavaScript engine used to parse <g> getter elements and value attributes below.
<record>
<record key="DMC40_0, DMC41_3, DMC42_0, DMC50_0, DMC52_0, DMC18_6">
Defines the beginning of a data record definition. All the following elements are sub-elements of <record>.
<shift>
<shift key="DMC18_6">-4</shift>
Defines a value to add to all data record offsets in the <o> element that occur after this element.
<f>
<f s="_TC" vmap="TC"><d>Error Code</d><o>50</o><t>201</t></f>
Defines a data record field. A field is a single piece of information extracted from a data record.
The mandatory attribute s must be a unique string that serves as the key for identifying the field. This s key is used by GDK tools to reference the field.
The optional attribute vmap contains the name of the value map associated with this field.
<d>
<d>Thread 7 Running</d>
Mandatory sub-element of <f>. Defines the human-readable description of the field.
<u>
<u>counts</u>
Optional sub-element of <f>. Sets the units of the field. If omitted, the units are unspecified, i.e. an empty string.
<o>
<o>148</o>
Mandatory sub-element of <f>. Defines the offset, in bytes, from the beginning of the data record to the beginning of the data referenced in the field. The offset value is modified by the <shift> element.
<g>
<g property="aq">"MG_AQ1"</g>
Optional sub-element of <f>. Defines the getter for this field that informs GDK how to interpret the field's data. The interpretation of some data record fields depend on a controller parameter. For instance, analog inputs have different meanings based upon the AQ command. The text of this element will be polled on the controller and the response will be saved into the JavaScript engine used by the code in <script> tags and value attributes below.
The mandatory attribute property defines the variable name that will be set in the JavaScript context.
Each of the following xml elements may have the optional value attribute. The contents of the value attribute will be evaluated in the JavaScript engine. If a value is returned, that value will be used for the element's value. If the evaluation fails, the element's value will be determined as if the value element was absent.
See the end of this document for an example of using the <script>, <g>, and value elements.
<t>
<t>200</t>
Mandatory sub-element of <f>. Defines the data type of the data referenced in the field. The type is defined by a numeric code as shown in the following table.
| Type | Width (Bits) | Minimum Value | Maximum Value | <t></t> Type Tag Value |
|---|---|---|---|---|
| Byte | 8 | -128 | 127 | 200 |
| Unsigned Byte | 8 | 0 | 255 | 201 |
| Single Bit, Bit 0 | 1 | 0 | 1 | 1 |
| Single Bit, Bit 1 | 1 | 0 | 1 | 2 |
| Single Bit, Bit 2 | 1 | 0 | 1 | 4 |
| Single Bit, Bit 3 | 1 | 0 | 1 | 8 |
| Single Bit, Bit 4 | 1 | 0 | 1 | 16 |
| Single Bit, Bit 5 | 1 | 0 | 1 | 32 |
| Single Bit, Bit 6 | 1 | 0 | 1 | 64 |
| Single Bit, Bit 7 | 1 | 0 | 1 | 128 |
| 12 Bit Value * | 16 | -2048 | 2047 | 204 |
| Unsigned 12 Bit Value * | 16 | 0 | 4095 | 205 |
| Word | 16 | -32768 | 32767 | 202 |
| Unsigned Word | 16 | 0 | 65535 | 203 |
| Long | 32 | -2147483648 | 2147483647 | 206 |
* The 12 Bit Value type is specially designed for 12 bit Analog I/O. The storage width is 16 bits, but the lower 4 bits are shifted out when determining the value.
<m>
<m>0.00030517578125</m>
Optional sub-element of <f>. Defines the slope of the linear equation, y = mx + b. In some contexts, GDK will apply the linear transform to scale the field's value for the user. This is useful for scaling DAC and ADC counts to volts, and scaling values to user units. If omitted, the default value is 1.0.
<b>
<b>-32767.0</b>
Optional sub-element of <f>. Defines the y-intercept of the linear equation, y = mx + b. In some contexts, GDK will apply the linear transform to scale the field's value for the user. This is useful for scaling DAC and ADC counts to volts, and scaling values to user units. If omitted, the default value is 0.0.
<p>
<p>4</p>
Optional sub-element of <f>. Sets the precision of the number produced from the linear transform. If omitted, the default value is 0, indicating the value should have no fractional digits. Used in Viewer displays and Scope cursors.
JavaScript Example
The decimal precision of an analog input depends upon the analog to digital configuration (AQ). By default, AQ's setting is 2 providing a range of -10V to 10V. For 16 bit ADCs, this provides a resolution of 0.0003 Volts per bit. A precision of 4 will cover this range.
Setting AQ to 3, switches the ADC range to 0 to 5v, or ~0.00008 volts per bit. A precision of 5 is desirable for this range.
We define the following script element.
<script>function aq_p(){ return (aq==3)?5:4; }</script>
In the <f> element for analog input 1, we define the following getter.
<g property="aq">"MG_AQ1"</g>
Finally, we instruct the <p> element to evaluate its value.
<p value="aq_p();">4</p>
If the evaluation fails, a default of 4 will be used.