Insight Diagnostics Output File Format

This section is intended for advanced users who wish to develop custom tools to enhance the functionality of the Insight Diagnostics data collection feature.

Document Notation

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.

General Guidelines

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 and Property Tags

<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 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.

DiagOutput Tag

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 program-readable time stamp is produced by the C function time(), which returns an integer value equal to the number of seconds elapsed since Jan 1, 1970.

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.

CatResult Tag

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>

DeviceClass Tag

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.

Device Tag

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"

Test Tag

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>

Sample XML DiagOutput

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>