XML configuration syntax

The GeoDMS can read a configuration, or a part of one, written in XML instead of in the Configuration file syntax. It is an alternative notation for the same tree of tree items, it is read by a reader of its own, and it is rarely used: almost every configuration is written in .dms syntax. It is described here because the reader ships with every version and a fragment can be included in any configuration.

including a fragment

An Include statement whose file name ends in .xml is read by the XML reader instead of by the .dms parser. The fragment is added to the container the include statement appears in, exactly as a .dms include is:

container region_data
{
   #include <region.xml>
}

The folder rule is the same as for a .dms include: the included file lives in the subfolder named after the including configuration file, without its extension.

A whole configuration can also be written in XML and named on the command line:

GeoDmsRun.exe /Lrun.log region.xml /nr

The outermost element is then the configuration root, so its own name is not part of an item path, the same rule that holds for the top level container of a .dms configuration.

The GeoDMS GUI offers only .dms files in its open dialog, so an XML configuration is opened through the command line or through an include.

syntax

A fragment starts with a version header and holds one outermost element:

<? xml version = "1.0" ? >
< TreeItem name = "region" >
< / TreeItem >

The reader splits the markup on whitespace, so <, ?, /, >, =, element names and quoted values must each be separated by spaces. The compact spellings that other XML tools accept are rejected: <TreeItem name="xz"/> ends the read with FormattedInpStream Error: expected '='.

That rule is about the markup only. The text between an opening and a closing tag is read as it stands, so an Expression inside an element needs no extra spaces.

items

Three element names create a tree item. Any other element is read as a Property of the item that its enclosing element created.

element	creates	attributes
TreeItem	a container or any other tree item	name
unit	a Unit	name, ValueType
DATAITEM	a Data item	name, DomainUnit, ValuesUnit, ValueComposition

properties

Every Property is written as a child element, never as an attribute. < TreeItem name = "x" Descr = "..." > is refused with XML Element property Descr seen as attribute for x: TreeItem, and the same holds for StorageName and StorageType:

< TreeItem name = "region" >
< Descr > the study area < / Descr >
< StorageType > gdal.vect < / StorageType >
< StorageName > %projDir%/data/region.gpkg < / StorageName >
< / TreeItem >

entities

The XML entities & < > ' " are decoded in element text. They are not decoded in attribute values: an entity in an attribute stays there literally, so ValueType = "uint32&" is reported as Unknown ValueType 'uint32&'.

Since GeoDMS 20.20.0 the character that follows an entity is kept. Before that release < Descr > a &amp; b < / Descr > gave a &b: the character right after the ; was swallowed, so a text lost one character per entity it contained, and two entities in a row turned the second one into literal text (x && y gave x & y). A configuration that compensated for this, by doubling the character after an entity, now has one character too many.

errors

An error inside an included fragment is reported in the Eventlog as an [E] line, but it does not fail the load by itself. The run fails later, at the point where something refers to an item the fragment did not create. So when a fragment does not do what you expect, read the eventlog rather than the exit code.

example

example.dms:

container region_data
{
   #include <region.xml>
   container checks
   {
      parameter<uint32> total := sum(region/nr), IntegrityCheck = "total == 33";
   }
}

example/region.xml, the subfolder named after the configuration file:

<? xml version = "1.0" ? >
< TreeItem name = "region" >
< Descr > read from an xml fragment < / Descr >
< unit name = "id" ValueType = "uint32" >
< Expr > range(uint32, 0, 3) < / Expr >
< / unit >
< DATAITEM name = "nr" DomainUnit = "id" ValuesUnit = "uint32" >
< Expr > id(id) + 10 < / Expr >
< / DATAITEM >
< / TreeItem >

This configures the same tree as:

container region_data
{
   container region: Descr = "read from an xml fragment"
   {
      unit<uint32> id := range(uint32, 0, 3);
      attribute<uint32> nr (id) := id(id) + 10;
   }
}