Command: xmlread

Syntax

xmlread <xmlfile>,<ident>

Description

Read an XML file into a Fire object.

Parameters

• <xmlfile>
  The XML file to read. This can be a local file or any URL.

• <ident>
  A structure object. The xml file is parsed and the data values loaded into the members of this object. Without the -auto switch this identifier must already exist. With the -auto switch an object with this name of a suitable class will be created automatically, or updated if it already exists.

Switches

• -auto
  This switch enables an object to be created without knowing its Fire class. This is only possible if the xml file conforms to an xml schema which has already been processed into Fire classes (see the xsdread command). xsd schema's and root-level tags are remembered by the system, so when an xml data file is read with this switch, a check is made to see whether the combination of its xsd schema and root-level tag has been used to create a Fire class. If it has, then an object of that class is created and named <ident>.

• -es=<ident>
  Record parsing errors in a string array identifier. If the identifier does not exist, a new string array is created using current scope rules. Each error is recorded in a separate array element. If this switch is included, errors are directed to the error log.

• -g=<groups>
  If any graphic entities are created as a result of reading the xml data, the entities are added to this (or these) groups.

• -pad
  Pad any concatenated text data values, removing multiple whitespace and ensuring that the only whitespace between items is a space. The default behavior is to read data as is which can result in unwanted CR/LF sequences in text data values.
  This option is ignored when xml validation is applied (-v).

• -tag=<string>
  The default behavior is for the parser to use the xml tag defined for the object's class when checking the outer tag name for validity. This tag name can be overridden by this switch. If no such xml tag has been defined for the objects's class and this switch is not present, then the outer tag name will not be checked, thus allowing any outer tag name to be accepted. Tag name checks are case insensitive.

• -v
  Validate the xml file. If the file is found not to be a well-formed XML file an error is recorded. The default behavior is not to validate.

Notes

XML parsing is performed using the Xerces SAX parser.

XML comments, DTD and XSL specifications are ignored during parsing.

Data values may be loaded into structure members of the following types: string, numeric, point, time and blob. Appropriate data coercion will be done automatically.

When the destination object <ident> already exists, its member values will be updated by data from the xml file. However, the object is not zeroized first, and member array lengths will not be reset. It is therefore best practice to delete and recreate the object prior to this command.

Example

Read a schema-less xml file into a Fire object. First we must create a destination class.

# Define an appropriate Fire structure
    atable mytab
    structure ~mytab.poi_t,-tag='poi' {
        string name
        time date
        numeric id
        point location
    }

# Create an object of the type
    ~mytab.poit_t warmem
# Read xml file contents into it, the outer tag must be poi
    xmlread  warmem.xml,warmem

An example xml file for use with the above, named warmem.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<poi>
    <name>War Memorial</name>
    <date>18-Dec-1919</date>
    <id>6512</id>
    <location>(25466,71625)</location>
</poi>

See Also