Install Toolkit: This link will launch VI Package Manager and install the latest GXML package.
Alternative Download: If you require a direct download, you can access the VIP file from our FTP directory. We recommend the VIP file with the highest version number or most recently modified date.
- Application Software: LabVIEW Development System 2010 SP1
- Toolkits and Addons: VI Package Manager (Community)
2. Using XML Files for System Configuration
XML's hierarchical structure makes it a favorable candidate for encoding complex data structures. XML data is also human-readable from a variety of freely available applications (including MS Explorer, MS WordPad, and MindFusion XML Viewer).
Figure 1: Using GXML to Convert a LabVIEW Cluster to an XML String
Figure 2: Example of GXML Data Conversion
Figure 2 shows a simple example of how GXML's custom schema represents data hierarchy within a cluster. Furthermore each control in the cluster is represented by only one line in the XML string. This format improves human readability and makes the XML data easier to work with. Figure 3 demonstrates how the XML string is parsed into a usable format.
Figure 3: Using a Type Definition to Parse the XML String
The cluster type definition's structure is a basis for how the XML string will be searched and parsed. Furthermore the type definition is used to convert the GXML variant output to a usable data type.
3. GXML VIs
Using a custom XML schema, gxml_Generator.vi converts LabVIEW data into an XML string. Data elements within any compound structure (such as multidimensional arrays, sub-clusters, or arrays of clusters) are represented with an appropriate hierarchy. The name of each LabVIEW control directly maps to the name of each XML element.
These VIs convert an XML string into a user specified LabVIEW data type. The data structure is defined by the input TypeDesc and its elements must have the same name and hierarchy as the elements in the XML string. The parsers use a custom XML schema so they can only decode XML strings created by gxml_Generator.vi.
gxml_SearchParser.vi uses a recursive searching algorithm to parse the string so the order of the elements is not important, only their hierarchy. Furthermore since this VI recursively searches for XML content by name, the XML file is allowed to have extra items not referenced by the type definition.
gxml_QuickParser.vi should only be used if you are certain that the type definition exactly matches the data type used to create the XML string. The limitation exists because the VI uses no recursion, it simply iterates through the XML string line by line and flattens any data into a binary array. This VI is much faster than its recursive-searching counterpart; however since it does not use the type definition to parse the XML string, it cannot give complete error information (like mismatched data types or incorrect order of elements etc.).
XML File IO:
gxml_WriteXMLtoFile.vi prepends the input string with an XML file header and writes everything to a text file with an XML extension.
gxml_ReadXMLfromFile.vi opens and reads all data out of an XML file. It strips the file header from the XML string so that the first line of the text string is the opening tag of the first data element.
4. Supported Data Types
GXML supported data types include:
Signed Integer (I8, I16, I32, I64)
Unsigned Integer (U8, U16, U32, U64)
Floating Value (SGL, DBL, EXT)
Complex Value (CSG, CDB, CXT)
Enum (U8, U16, U32)
Timestamp (XML string represents time in 24 hour clock, HH:MM:SS MM/DD/YYYY format)
5. Encoding Individual Elements and Arrays of Elements
The XML representation of individual data elements includes a type attribute to describe the data type of the control when it was converted from LabVIEW to XML. For example in Figure 2 the Rate control is represented as:
The type attribute ensures its data will be correctly formatted when it is scanned back into LabVIEW.
When an enum is encoded a second attribute is used. Consider an enum control whose items are the days of the week; GXML would represent the Tuesday selection like so:
<Due_Date type='Enum U16' sel='Tuesday'>2</Due_Date>
The XML string shows us that the enum Due_Date contains a U16 integer of value 2. The sel attribute defines what the text selection was for value 2 when the XML string was generated. This attribute is important because when the XML string is parsed, we need to make sure the type definition uses the same enum item. If the type definition's enum has a something other than "Tuesday" for value 2 then the GXML parser will generate an error.
Arrays and Multidimensional Arrays
GXML supports arrays of elements and multidimensional arrays of elements. When GXML encounters an array it first creates an open tag with the array name and then inserts attributes that describe both the shape of the array and data type of its elements. Figure 4 is an example of a two dimensional boolean array named Control Array.
Figure 4: GXML Representation of Two Dimensional Boolean Array
Notice the type attribute has been moved to the array's open tag and that the open tag also has an attribute named dim. The information inside dim's square brackets describe the number of elements in each dimension (in this case two rows and three columns).
6. Compound Data Structures
GXML takes a similar approach when it encounters an array of clusters. Figure 5 is an example of a three dimensional array of clusters where each cluster element contains a boolean, a string, and an array of DBLs.
Figure 5: GXML Representation of a Three Dimensional Array of Clusters
Notice the Control_Array open tag has the aforementioned dim attribute (3D array with one element) but this time the data type attribute is defined as a cluster. The cluster is named Desc and has a mems attribute to describe how many elements (or members) the cluster contains. The mems attribute is only included to aid a human reader, it is not used during parsing. Notice the cluster's encapsulated members Toggle, Desc, and Mag_Array all have the same hierarchy within the XML string. Cluster element Mag_Array represents another encapsulating data structure so its individual DBL elements exist one level deeper within the hierarchy.
7. Valid Control/Element Names
Names of the LabVIEW controls map directly to the element names in the XML string. Valid names must begin with a letter. Subsequent characters may be letters, numbers, a period, a dash, or an underscore. Any whitespace within a control name will be automatically converted to underscores. Any control or item name with illegal characters (i.e. ampersands, parenthesis, brackets, etc) will cause an error to be thrown.
Furthermore no two items of the same hierarchy may have the same name. In Figure 5 (above) the cluster Desc and the string control Desc exist in different levels so duplicate names are permitted.
8. Special Characters for Stings and Paths
XML specifications reserves five special characters which must be honored by all XML processors. When GXML encounters one of these five special characters in a string or path it automatically converts them to the appropriate escape code.
|Special Character||Escape Code|
For example if a LabVIEW string control named Details contains the string LabVIEW & "XML", GXML would represent that control and data like so:
<Details type='String'>LabVIEW & "XML"</Details>
When GXML parses the sting it recognizes the escape code and displays the string with the original special characters.
9. Discussion and Feedback
This reference library was created by the NI Systems Engineering group.
We do not regularly monitor Reader Comments posted on this page. Please submit your feedback to the GXML discussion forum.