XML Toolbox

Introduction

The XML Toolbox for Matlab allows users to convert and store variables and structures from the Matlab workspace into the plain text XML format, and vice versa. This XML format can be used to store parameter structures, variables and results from engineering applications in non-proprietary files, or XML-capable databases, and can be used for the transfer of data across the Grid. The toolbox contains bi-directional conversion routines implemented as four small intuitive and easy-to-use Matlab functions. As an additional feature, this toolbox allows the comparison of internal Matlab structures by comparing their XML representation, which was not previously possible.

Almost any type of XML document can be read and converted into Matlab's struct format or cell data type.
Matlab structures and variables can be stored in a non-proprietary format and used by other tools.
XML representations can be stored and queried using the functions provided by the Geodise Database Toolbox.
The ability to leverage XML and database technologies makes the data available beyond the Matlab environment, and facilitates data sharing and reuse between users.
Access to XML data-driven tools such as Web Services becomes more transparent to engineering users.

The following definitions are valid for XML Toolbox Version ³ 2.0 (2.0, 2.1, 2.2, 3.0a, 3.1, 3.2). The size of data structures the XML Toolbox can deal with is only limited by the available memory; as an indication, 60MB large data structures can be easily converted on a 256MB PC running Matlab.

xml_format	Converts Matlab data to an XML string
xml_formatany	Converts Matlab data to an XML string with user-defined attributes
xml_parse	Converts an XML string into Matlab data
xml_parseany	Converts an XML string with attributes into Matlab data
xml_load	Loads an XML file and returns Matlab data
xml_save	Saves Matlab data into an XML file
xml_help	Displays help for each xml_ function

Table 6 XML Toolbox functions

Tutorial

The XML Toolbox for Matlab can be used independently of the Compute and Database Toolboxes. No proxy certificate is required to make use of its functionality.

Converting Matlab data types to XML

All common Matlab data types can be converted into XML with the simple-to-use commands xml_format (with or without attributes) or xml_formatany. We highlight the differences in XML output structure in the following three examples.

>> v.a = 1.2345

>> v.b = [1 2 3 4; 5 6 7 8]

>> v.c = 'This is a string.'

>> v.d = {'alpha','beta'}

>> v.e = (1==2)

>> v.f.sub1.subsub1 = 1

>> v.f.sub1.subsub2 = 2

>> v.g(1).aa(1) = {'g1aa1'}

>> v.g(1).aa(2) = {'g1aa2'}

>> v.g(2).aa(1) = {'g2aa1'}

This first example shows the formatting of the Matlab variable with no additional input parameters specified. The XML is formatted in such a way that any subsequent parsing of the created XML string with xml_parse reconstructs an exact copy of the original Matlab variable.

>> xmlstr = xml_format(v)

xmlstr =

1 5 2 6 3 7 4 8

<c idx="1" type="char" size="1 17">This is a string.</c>

<item idx="1" type="char" size="1 5">alpha</item>

</d>

</sub1>

</f>

</aa>

</aa>

</g>

</root>

The Matlab-specific attributes idx, type and size, which allow the exact reconstruction of the Matlab data types, can be turned off by specifying the second parameter in the xml_format function call as 'off'. This results in a more generic formatting of the structure, however, the XML contents are now interpreted purely as strings when parsed back into Matlab as type and size information are lost:

>> xmlstr = xml_format(v,'off')

xmlstr =

<root>

1 5 2 6 3 7 4 8

<c>This is a string.</c>

<d>

<item>alpha</item>

</d>

<f>

<sub1>

</sub1>

</f>

<g>

<aa>

</aa>

<aa>

</aa>

</g>

</root>

The user can write the XML representation of a Matlab variable immediately into a XML file using the command xml_save. This command uses the same XML format as the function xml_format.

If the user wishes to define XML attributes other than the default idx, type and size parameters, these can be added using a substructure called 'ATTRIBUTE' in the Matlab structure and performing the formatting with the command xml_formatany.

This command converts Matlab cell data vectors into several XML elements with the same name tag without using the 'item' tag as in the previous example.

xml_formatany may be preferable to xml_format when converting Matlab data into XML which is processed in other applications, however, some of the information about the original data types may be lost when converting the XML back into Matlab using xml_parseany:

>> xmlstr = xml_formatany(v)

xmlstr =

<root>

1 5 2 6 3 7 4 8

<c>This is a string.</c>

<d>alpha</d>

<f>

<sub1>

</sub1>

</f>

<g>

</g>

<g>

</g>

</root>

We can specify additional attributes for the subfields f.sub1 and g(2)

>> v.f.sub1.ATTRIBUTE.fontname = 'Helvetica'

>> v.g(2).ATTRIUTE.fontname = 'Helvetica2'

which then results in the following XML string:

>> xmlstr = xml_formatany(v)

xmlstr =

<root>

[...]

<f>

</sub1>

</f>

<g>

</g>

</g>

</root>

Converting XML to Matlab data types

As XML can contain any arbitrary contents as long as they follow the W3C XML Recommendation (www.w3.org), parsing and translating of these constructs into a Matlab-specific environment can be complex. The functions xml_parse and xml_parseany allow the conversion of XML strings into Matlab data structures in a sensible way.

There are three distinct ways of importing XML into Matlab data structures. These correspond to the techniques shown above for xml_format and xml_formatany. (There are actually four ways; however, we no longer support the old method from version 1.x).

If the XML contains Matlab specific descriptors, such as created by xml_format with attributes switched on (i.e. the idx, type, size attributes), the XML Toolbox will be able to re-create exactly the Matlab data type and content described by the XML string.

For example,

>> xmlstr = ...

1 5 2 6 3 7 4 8

<c idx="1" type="char" size="1 17">This is a string.</c>

<item idx="1" type="char" size="1 5">alpha</item>

</d>

</sub1>

</f>

</aa>

</aa>

</g>

</root>

can be parsed using the command

>> v = xml_parse(xmlstr)

and returns the structure

v =

a: 1.2345

b: [2x4 double]

c: 'This is a string.'

d: {'alpha' 'beta'}

e: 0

f: [1x1 struct]

g: [1x2 struct]

which corresponds exactly to the Matlab variable used in xml_format to create the XML string.

If we use the same command, xml_parse, but tell the parser to ignore the attributes with the command

>> v_wo_att = xml_parse(xmlstr,'off')

we obtain a structure where types and sizes of the data will not be adapted to match standard Matlab data types, that means that all alphanumeric content will be returned as strings.

v_wo_att =

a: '1.2345'

b: '1 5 2 6 3 7 4 8'

c: 'This is a string.'

d: {'alpha' 'beta'}

e: '0'

f: [1x1 struct]

g: [1x2 struct]

The structural information (in fields f and g) is still preserved, although matrix contents, such as in field b, and numeric values, such as in fields a and e, are returned as pure strings.

The third possibility is to use xml_parseany which is able to convert most XML strings to Matlab data structures while taking care of namespaces and attributes. As the structure in XML strings can be very complex (for example in WSDL documents), the variable returned is a struct variable with sub-structures defined as cells.

If we parse, for example,

>> xmlstr = ...

<gem:project name="MyProject">

<date_created type="date">2004-10-12</date_created>

</parameters>

</project>

with

>> v = xml_parseany( xmlstr )

we obtain the variable

v =

ATTRIBUTE: [1x1 struct]

username: {[1x1 struct]}

date_created: {[1x1 struct]}

description: {[1x1 struct]}

parameters: {[1x1 struct]}

with the following variable structure

v.ATTRIBUTE(1).name MyProject

v.ATTRIBUTE(1).NAMESPACE gem

v.username{1}.ATTRIBUTE.type string

v.username{1}.CONTENT Me

v.date_created{1}.ATTRIBUTE.type date

v.date_created{1}.CONTENT 2004-10-12

v.description{1}.ATTRIBUTE.fontsize 10

v.description{1}.CONTENT cool!

v.parameters{1}.eps1{1}.ATTRIBUTE.type dielectric

v.parameters{1}.eps1{1}.ATTRIBUTE.units 1

v.parameters{1}.eps1{1}.CONTENT 8.92

v.parameters{1}.eps2{1}.ATTRIBUTE.type dielectric

v.parameters{1}.eps2{1}.ATTRIBUTE.units 1

v.parameters{1}.eps2{1}.CONTENT 1.00

v.parameters{1}.StT{1}.ATTRIBUTE.type structuretype

v.parameters{1}.StT{1}.CONTENT rod

v.parameters{1}.nofEV{1}.ATTRIBUTE.type numeric

v.parameters{1}.nofEV{1}.CONTENT 47

v.parameters{1}.ATTRIBUTE.n 4

gd_unmarkfordeletion

contents

xml_format