This section is intended for advanced users who wish to develop custom tools to enhance the functionality of the Insight Diagnostics data collection feature.
The Insight Diagnostics output file format is in XML. Literal tag names and attribute names are shown in bold. Attribute values supplied by specific components are in italics. The simplest style of XML tag, a tag that does not contain sub-tags, is represented with standard XML syntax.
<TAG Attribute1="value" Attribute2="other value"/>
If the tag contains sub-tags, the general names of the sub-tags will be listed in parenthesis between the opening and closing tags.
<TAG
Attribute1="value"
Attribute2="other
value">
( subtag1 | subtag2 )
</TAG>
All XML tag names and attribute names are non-case sensitive. They are displayed in mixed case in the examples in this section for readability.
Most XML tags should contain attributes for name, caption, and description.
The name attribute is similar to a key-word or variable name that uniquely distinguishes tags at the same level of the XML structure. The name attribute is independent of the localized language, meaning that it will not be translated. The name attribute should be treated as non-case sensitive, but should follow the naming rules for C/C++ variables.
<PARENT>
<TAG Name="bert">
<SUBTAG1 Name="fred"/>
<SUBTAG1 Name="barney"/>
</TAG>
<TAG
Name="ernie">
<SUBTAG1 Name="fred"/>
<SUBTAG1 Name="barney"/>
</TAG>
</PARENT>
The caption attribute is a localized, language specific name for the element. The description attribute is a short phrase or sentence that briefly describes the element.
<PROPERTY
name="REV" caption="Revision"
descrption="The element revision
number" value="1.2.3">
<STRUCTURE
name="Structure-Name"
caption="Structure-Caption"
description="A single-line
description">
( property | structure ) ...
</STRUCTURE>
<PROPERTY
name="Property-Name"
caption="Property-Caption"
description="A single-line
description"
value="Property-String"
[raw="RawValue"]/>
Subordinate Tags:
A STRUCTURE tag may contain zero or more PROPERTY tags. A STRUCTURE tag may also contain zero or more subordinate STRUCTURE tags.
A PROPERTY tag may not contain any other tags.
A parser should be able to accept subordinate STRUCTURE and PROPERTY tags in any order. Program-generated XML should present all PROPERTY tags first followed by all STRUCTURE tags.
The value attribute is a string intended for display "as is." The raw attribute may be used to provide a numeric (or other format) value that will probably be re-formatted or interpreted before being displayed.
The diagOutput tag is the root element of the Insight Diagnostics output XML.
<diagOutput
type="Output Type
(for example, idResult or jobStatus)"
language="Language Code
(for example, en, fr, ja)"
timeStamp="program-readable
time stamp"
timeStampCaption="human-readable
time stamp">
The human-readable time stamp is a time that a human can easily interpret. For example, in English it would be m/d/yyyy hh:mm:ss <AM/PM> and in Italian it would be dd/MM/yyyy H.mm.ss.
A CatResult element is generated by a test component in response to a diagCatalog command element. The only attribute is the name of the test component:
<CatResult
name="test-component-name">
( deviceclass ) ...
</CatResult>
A Device element is generated by a test component for each class of device it is capable of supporting.
<DeviceClass
name="dev-class-name"
caption="device-caption"
description="device-descr">
</Device>
The name attribute string should be used as the root string for constructing the names of the devices of the class.
A Device element is generated by a test component for each device that it identifies.
<Device
name="device-name"
class="device-class"
caption="device-caption"
description="device-descr"
refnum="reference-number">
( structure | property | test ) ...
</Device>
The class attribute is the name of the device class. It should be the name attribute of one of the DeviceClass elements returned from a diagCatalog command. The name class attribute should be short and can not contain blank spaces. For example, an ethernet network device might have a class="eth". The class should never be translated because it may be used by test scripts or external parsers to find specific information within the XML.
The caption attribute should be a general name of the device that may be translated into local languages. It should use the same refnum as the name attribute. The network device caption for example:
caption="Network Controller 0"
The description attribute is a longer string that may be translated into the local language. This string may be supplied by the operating system, by the system BIOS, or perhaps from a lookup table within the test component. Avoid using lookup tables. The network controller description for example:
description="Intel(R) 82559 Fast Ethernet Controller"
The refnum is a unique number used to distinguish device elements of the same class. The refnums of the various device elements do not need to be sequential.
The name attribute should be constructed by concatenating the class and refnum attributes.
class="eth" refnum=0 name="eth0"
A Test element is generated by a test component for each test that is supported by a particular device. The test tag should contain all the information needed for a user to select the test and set all of the test's parameters.
<Test
name="test-name"
caption="test-caption"
Description="this is a description
of the test">
( parameter ) ...
</Test>
The following XML example shows usage of many of the tags described in this section. If you are unfamiliar with XML, pay close attention to the difference between <TAG>, </TAG>, and <TAG/>. All XML elements should have beginning tags and ending tags. Empty elements can, optionally, be self-ending. Empty elements are elements that do not have data content between the start and end tags. The Category and Device elements in the example have start and end tags. The Property elements are self-ending.
<category
name="communication"
caption="Communication">
<device name="eth0"
class="networkDevice"
caption="Network
Controller 0" description="Intel Corp. 82557/8/9 [Ethernet Pro 100]"
category="Communication|Network
Controller(s)" component="libtcnetwork.so">
<property name="macAddress"
caption="MAC
Address" value="00-02-A5-8A-A8-B9" />
<property name="ipAddress"
caption="IP
Address" value="16.100.48.169" />
<property name="broadcastIP"
caption="Broadcast
Address" value="16.100.51.255" />
<property name="network"
caption="Network"
value="16.100.48.0"
/>
<property name="netmask"
caption="Netmask"
value="255.255.252.0"
/>
<property name="ipproto" caption="Protocol" value="static" />
<property name="interface"
caption="Interface"
value="eth0"
/>
<property name="dns2"
caption="Secondary
DNS Server" value="16.110.248.22" />
<property name="hostname"
caption="Host
Name" value="linuxdiagnostics32" />
<property name="gateway"
caption="Default
Gateway" value="16.100.48.1" />
</device>
</category>