tree item name - ObjectVision/GeoDMS GitHub Wiki

tree item names

1. may contain (alpha)numeric characters A..Z, a..z, 0..9, _(underscore, U+005F)
2. may not start with a numeric character
3. UTF characters U+0080 and higher codes are also allowed, such as: €, °, ß, π, δ, Δ
   • Mathematical characters are also allowed (with or without sub and superscripts), such as: σₓ, σᵧ, σₓᵧ, α, β, ŷ, ȳ, x̄, ∑
4. The following characters cannot be used in tree item names:
   • Characters with specific meaning in calculation rules, more specifically: all operators , ( ) and [ ] brackets, comma (U+002C), quotes, spaces (U+0020).
   • Characters that have specific meaning in the GeoDms language, more specifically: {, }, ;, and "
   • Control characters (U+0000 .. U+001F)
5. The following character is reserved for future use and should not be used in item names: @ (U+0040)

Tree item names are case insensitive with regard to the UTF alphabetical characters below U+0080, thus A is identified with a, B with b , ... and Z with z. Other characters, such as from the Greek alphabet are case sensitive.

We advise to use upper or lowercase characters consistently in tree item names as we are preparing and planning to make tree item names and GeoDMS configurations case sensitive, possibly with a fallback option during a migration period.

The GeoDMS keeps one case-folded table of names, shared by the engine, the standard prelude and your configuration. The first spelling of a name that is read becomes the canonical one, and any later spelling of that same name that differs only in case is reported in the event log as Depreciated mix-up of cases. That row of the event log filter switches these off, as does the /CW command line option for a single run.

Since GeoDMS 20.19.0 the engine's own names are canonically lower case: unit, value, item, nrofrows, and the value types bool, uint32, float32, void and their siblings. Writing them that way - which naming conventions already advised for keywords - reports nothing.

Before 20.19.0 the engine registered Unit, Value and NrOfRows in mixed case, and its own shipped RewriteExpr.lsp and prelude.dms disagreed with the lower-case value types, so every configuration was greeted with about a dozen of these warnings before it had done anything wrong. A warning now means your configuration is inconsistent, not the engine.

What you may notice after upgrading: a configuration that writes NrOfRows, Unit or Value where it was silent before now reports a case mix-up once for each such name. The spelling still works - names remain case insensitive - but the lower-case form is the one the engine records, so it is the one to migrate to.

The recorded spelling is not only what the event log and the GUI show: it is the name the engine writes into exported data. An attribute you named Value or Attr is emitted as a column named value / attr - in a gdalwrite.vect CSV header, in a GeoPackage column, and in the item paths of an @statistics page (User Guide GeoDMS Run).

Measured on the same three-column export, written by two builds of the same configuration:

column as configured	written by 20.18.0	written by 20.19.0 and later
Woningen (collides with nothing)	Woningen	Woningen
Value	Value	value
Attr	Attr	attr

So a consumer that reads an exported file by exact column name - a pandas/geopandas df['Value'], an ArcGIS or QGIS field mapping, a SQL query against a GeoPackage - can stop finding its column after an upgrade to 20.19.0, even though nothing in the configuration changed. Only names that case-fold onto one of the engine's own names are affected; every other name is written exactly as configured. Reading is not affected: a source column spelled Value still binds to an attribute declared Value, because field matching stays case insensitive.

If downstream consumers depend on the old spelling, rename the item to a name that does not collide with an engine name (Woningen, sel_value, ...) rather than relying on its capitalisation, since the case-folded table makes the engine's spelling win.

For the naming of tree items see naming conventions.

The checking of treeItem names is done by the functions itemNameFirstChar_test and itemNameNextChar_test, defined in %geodmsfolder%\rtc\dll\src\utl\Encodes.h