User Guide GeoDMS Run

GeoDMSRun (GeoDmsRun.exe) updates tree items without a user interface, from a shell or from a script. It is the tool of choice for batch calculations, nightly runs, CI checks and any "calculate this and write it to its storage" job.

You can drive it from either shell that ships with Windows:

• Command Prompt (cmd.exe) — the classic way; still the right choice for the .cmd / .bat files that many GeoDMS projects already use.
• PowerShell (powershell.exe 5.1, or the modern pwsh.exe 7.x) — the recommended shell for new automation: real error handling, structured output, Tee-Object logging, and no %ErrorLevel% quoting traps.

Both are documented below. Everything about the program (options, item names, exit codes) is identical; only the shell syntax differs.

command line

GeoDmsRun.exe [/L<LogFileName>] [/S<X> /C<X> ...] <ConfigFileName> [<ItemOrCommand> ...]

The arguments are processed strictly left to right.

Argument	Required	Description
/L<LogFileName>	optional	Write a log file. Must be the very first argument. No space between /L and the path (/LC:\tmp\log.txt). Available since version 5.55.
/S<X> / /C<X>	optional	Set or Clear a status flag <X>. Any number of them, in any order, but they must come before the configuration file name. See status flags.
<ConfigFileName>	required	The .dms configuration to load.
<ItemOrCommand>	zero or more	[[Tree item

Anything else that starts with / (on Linux: with -) after the status flags is rejected with "Unknown command-line option …" and exit code 2.

Note — the built-in usage text mentions a /PProjName option. That option is not implemented; use the %projDir% placeholder mechanism instead (see Folders and Placeholders).

status flags

Flag	Meaning
/S1 /S2 /S3	Set multiple-threading level 1, 2 and 3. /C1 /C2 /C3 clear them.
/SW / /CW	Show / hide warnings about deprecated case mix-ups in tokens (item and function names).
/SM / /CM	Set / clear debug mode.
/SA / /CA	Set / clear admin mode.
/SH / /CH	Show / hide the thousand separator in reported numbers.

The remaining flags (/SC, /SV, /SD, /SE, /ST, /SI, /SR, /SS) control GUI elements and have no effect in GeoDmsRun. If no threading flags are given, the settings from the registry are used — the same ones shown in the GeoDMS GUI under Tools > Options > Advanced.

For a reproducible batch run, always set the threading flags explicitly (/S1 /S2 /S3), so the run does not depend on whatever the interactive user last configured.

item names

• Item paths are resolved relative to the configuration's root, which is the desktop root — not relative to the top-level container in the file. For container foo { … export { … } } you write /export, not /foo/export.
• Whole subtrees are allowed: naming a container calculates the container and all its descendants.
• Item names never contain spaces, so they never need quotes in cmd. In PowerShell they do not need quotes either — but see the @ trap below.
• If an item is not found, or fails to calculate, the run continues with the next item and the exit code becomes 1.

item-action commands (@…)

GeoDMS Run accepts a set of action commands prefixed with @. An @… command sets the current action and applies to every item that follows it, until the next @… command. The default action is @commit.

Command	Effect
@commit	(default) Update the item; if it has a writable storage configured, write the data there.
@statistics	Update the item, then print the numeric statistics also shown on the GUI's Statistics detail page (count, min, max, sum, mean, variance, stddev, #nulls, plus a value/count breakdown for boolean/categorical items).
@file <path>	Redirect subsequent @statistics / @histogram / @list output to <path> instead of stdout. Takes the next argument as the file name. Only one output file at a time.
@checkfunctions	Type-check every [[function definition
@dumpconfig <path>	Write the loaded configuration back out in DMS syntax — the same serialization the GUI's Configuration detail page shows. Useful for round-trip checks and for inspecting how items (functions in particular) are represented. Takes the next argument as the file name. (since 20.9.0)
@histogram	(reserved — not yet implemented; currently prints a placeholder line)
@list	(reserved — under construction; currently prints a placeholder line)

Source: enum class itemCmd and the parsing loop in run/exe/src/MainRun.cpp.

exit codes

GeoDmsRun communicates its result through the process exit code — %ErrorLevel% in cmd, $LASTEXITCODE in PowerShell. Always check it; a failed run still ends "normally".

Code	Meaning
0	Success.
1	One or more items were not found or failed to update (or a @checkfunctions definition failed). The configuration itself loaded fine.
2	The configuration could not be read, no arguments were given, an unknown option was passed, or an exception was caught while updating.
3	Unexpected termination (a failed assertion in a Debug build).
-1073741819	Access violation (0xC0000005). Contact Object Vision for support.

---

Running from the Command Prompt (cmd.exe)

Quotes are needed around file names, because those may contain spaces. Item names never need quotes.

1 — Update /result in a configuration

"C:\Program Files\ObjectVision\GeoDms20.8.0\GeoDmsRun.exe" "C:\prj\test\cfg\stam.dms" /result

2 — Update several items in one run

"C:\Program Files\ObjectVision\GeoDms20.8.0\GeoDmsRun.exe" "C:\prj\test\cfg\operator.dms" /Arithmetics/plus/test_attr /Arithmetics/sub/test_attr

3 — Same, with a log file

"C:\Program Files\ObjectVision\GeoDms20.8.0\GeoDmsRun.exe" "/LC:\tmp\log.txt" "C:\prj\test\cfg\stam.dms" /result

4 — Force multi-threading levels 1 and 2 on

"C:\Program Files\ObjectVision\GeoDms20.8.0\GeoDmsRun.exe" /S1 /S2 "C:\prj\test\cfg\stam.dms" /result

5 — Print statistics for an attribute instead of writing storage

"C:\Program Files\ObjectVision\GeoDms20.8.0\GeoDmsRun.exe" "C:\prj\test\cfg\stam.dms" @statistics /results/att

6 — Mix actions on one command line: commit one item, then write statistics of two diagnostic attributes to a file

"C:\Program Files\ObjectVision\GeoDms20.8.0\GeoDmsRun.exe" /S1 /S2 /S3 "C:\prj\test\cfg\main.dms" ^
    /results/output_layer ^
    @file "D:\log\diag.txt" @statistics ^
    /results/dbg/coverage /results/dbg/null_count

The @statistics output reports Minimum, Maximum, #Nulls and (for boolean attributes) the count of False vs True — much faster than re-writing a whole GeoPackage or .fss just to inspect one column.

7 — Check the exit code

"%ProgramPath%" %MT_FLAGS% "%ProjDir%\cfg\main.dms" /WriteBasedata/Generate_Run1
echo ErrorLevel is %ErrorLevel%
if %ErrorLevel% NEQ 0 goto ErrorEnd

batch file (.cmd) example

A typical project batch file collects the settings at the top, calls one or more runs, and ends with a shared error handler.

REM ========== PARAMETER SETTINGS ================
set geodmsversion=GeoDms20.8.0
set exe_dir=C:\Program Files\ObjectVision\%geodmsversion%
set ProgramPath=%exe_dir%\GeoDmsRun.exe
set LocalDataProjDir=C:\LocalData\RSopen

set MT_FLAGS=/S1 /S2 /S3

set CurrentDir=%CD%
CD ..
set ProjDir=%CD%
CD %CurrentDir%
REM ========= END PARAMETER SETTINGS ===========

REM optional: ask the user what to calculate
set AlleenEindjaar=TRUE
if "%1%" equ "" CHOICE /M "Only calculate the final year, i.e. skip 2030 and 2040?"
if ErrorLevel 2 set AlleenEindjaar=FALSE
if "%1%" equ "N" set AlleenEindjaar=FALSE

REM start from a clean BaseData folder
rmdir %LocalDataProjDir%\Basedata /s /q

set RSL_VARIANT_NAME=BAU
call ..\batch\RunVariantData.cmd

call ..\batch\RunImpl.cmd %ProjDir%\cfg\main.dms /WriteBasedata/Generate_Run1
echo "ErrorLevel is " %ErrorLevel%
if %ErrorLevel% NEQ 0 goto ErrorEnd

goto End

:ErrorEnd
echo "ErrorLevel is " %ErrorLevel%

if %ErrorLevel% == 3 (
 echo ERROR: Unexpected termination after loading %1 to update %2.
)
if %ErrorLevel% == 2 (
 echo ERROR: failed to load %1 or caught exception during updating %2.
)
if %ErrorLevel% == 1 (
 echo ERROR: updating of item %2 in %1 failed.
)
if %ErrorLevel% == -1073741819 (
 echo ERROR: Access Violation. Contact Object Vision for support.
)

echo batch will be aborted after pause because of a detected failure
pause
exit /b %ErrorLevel%

:End

---

Running from PowerShell

PowerShell (5.1 or 7.x) is the modern alternative. The arguments are exactly the same; the shell syntax is not.

the four rules

1 — Call the executable with the call operator &. A quoted string on its own is just a string; & tells PowerShell to execute it.

$geoDms = 'C:\Program Files\ObjectVision\GeoDms20.8.0\GeoDmsRun.exe'
& $geoDms 'C:\prj\test\cfg\stam.dms' /result

2 — Quote every argument that starts with @. (the one real trap) In PowerShell @name is the splatting operator, so a bare @statistics is read as "expand the variable $statistics into arguments" — and since that variable normally does not exist, the argument silently disappears. The run then commits the item instead of printing its statistics, with no warning at all. Always write '@statistics', '@file', '@checkfunctions', '@commit'.

# WRONG - @statistics vanishes, the item gets committed instead
& $geoDms $cfg @statistics /results/att

# RIGHT
& $geoDms $cfg '@statistics' /results/att

3 — Check $LASTEXITCODE, not $?. $LASTEXITCODE holds the exit code of the last native program. $? only says "did it run".

4 — Keep /L first, and glue it to the path.

& $geoDms '/LC:\tmp\log.txt' $cfg /result

Paths with spaces are fine inside one quoted string: '/LD:\my logs\run.log'.

examples

1 — Update /result in a configuration

$geoDms = 'C:\Program Files\ObjectVision\GeoDms20.8.0\GeoDmsRun.exe'
& $geoDms 'C:\prj\test\cfg\stam.dms' /result

2 — Update several items in one run

& $geoDms 'C:\prj\test\cfg\operator.dms' /Arithmetics/plus/test_attr /Arithmetics/sub/test_attr

3 — Same, with a log file

& $geoDms '/LC:\tmp\log.txt' 'C:\prj\test\cfg\stam.dms' /result

4 — Force multi-threading levels on, and report the result

& $geoDms /S1 /S2 /S3 'C:\prj\test\cfg\stam.dms' /result
if ($LASTEXITCODE -ne 0) { Write-Error "GeoDmsRun failed with code $LASTEXITCODE" }

5 — Statistics of one attribute, without writing any storage

& $geoDms /S1 /S2 /S3 'C:\prj\test\cfg\stam.dms' '@statistics' /results/some_attribute

6 — Build the argument list first, then splat it

This is where @ is what you want: @dmsArgs expands the array into separate arguments. It keeps long command lines readable and lets you assemble them conditionally.

$dmsArgs = @(
    '/S1', '/S2', '/S3'
    'C:\prj\test\cfg\main.dms'
    '/results/output_layer'
    '@file', 'D:\log\diag.txt'
    '@statistics'
    '/results/dbg/coverage', '/results/dbg/null_count'
)
& $geoDms @dmsArgs

7 — Show live progress on screen and keep a readable log

& cmd /c "`"$geoDms`" /S1 /S2 /S3 `"$cfg`" /result 2>&1" | Tee-Object -FilePath 'D:\log\run.log'

cmd /c "... 2>&1" merges stderr into stdout inside cmd. That avoids Windows PowerShell 5.1 wrapping every native stderr line as a red NativeCommandError. Tee-Object then shows the output live and writes it to a file you can grep afterwards:

Select-String -Path 'D:\log\run.log' -Pattern 'Error|Failure|Warning'

In PowerShell 7 you can usually drop the cmd /c wrapper and redirect directly:

& $geoDms /S1 /S2 /S3 $cfg /result 2>&1 | Tee-Object -FilePath 'D:\log\run.log'

8 — Calculate a list of items, one run each, stop at the first failure

$items = '/WriteBasedata/Generate_Run1', '/WriteBasedata/Generate_Run2', '/Export/Maps'
foreach ($item in $items) {
    Write-Host "=== $item ===" -ForegroundColor Cyan
    & $geoDms /S1 /S2 /S3 $cfg $item
    if ($LASTEXITCODE -ne 0) {
        Write-Error "Aborting: $item failed with exit code $LASTEXITCODE"
        break
    }
}

9 — Type-check all function definitions in a configuration (since 20.9.0)

Handy as a CI / pre-commit gate: it fails on any function definition that does not type-check, including ones nothing in the configuration references yet.

& $geoDms $cfg '@checkfunctions'
if ($LASTEXITCODE -ne 0) { throw "function definition check failed" }

a reusable PowerShell wrapper

The PowerShell equivalent of the classic RunImpl.cmd — one function that runs a config, translates the exit code into a readable message, and throws on failure so a calling script stops.

function Invoke-GeoDmsRun {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)] [string]   $ConfigFile,
        [Parameter(Mandatory)] [string[]] $Item,
        [string]   $GeoDmsVersion = 'GeoDms20.8.0',
        [string]   $LogFile,
        [string[]] $Flags = @('/S1', '/S2', '/S3')
    )

    $exe = Join-Path "C:\Program Files\ObjectVision\$GeoDmsVersion" 'GeoDmsRun.exe'
    if (-not (Test-Path $exe)) { throw "GeoDmsRun not found: $exe" }

    $dmsArgs = @()
    if ($LogFile) { $dmsArgs += "/L$LogFile" }   # /L must stay first
    $dmsArgs += $Flags
    $dmsArgs += $ConfigFile
    $dmsArgs += $Item

    Write-Verbose "& $exe $($dmsArgs -join ' ')"
    & $exe @dmsArgs
    $code = $LASTEXITCODE

    $message = switch ($code) {
        0            { $null }
        1            { "updating of item(s) '$($Item -join ', ')' in $ConfigFile failed" }
        2            { "failed to load $ConfigFile, or an exception was caught while updating" }
        3            { "unexpected termination after loading $ConfigFile" }
        -1073741819  { 'Access Violation. Contact Object Vision for support.' }
        default      { "GeoDmsRun returned $code" }
    }
    if ($message) { throw "GeoDmsRun (exit $code): $message" }

    Write-Host "OK: $ConfigFile $($Item -join ' ')" -ForegroundColor Green
}

Usage:

Invoke-GeoDmsRun -ConfigFile 'C:\prj\test\cfg\main.dms' `
                 -Item '/WriteBasedata/Generate_Run1' `
                 -LogFile 'D:\log\run1.log' -Verbose

PowerShell notes

• Windows PowerShell 5.1 vs PowerShell 7 (pwsh). Both work. PowerShell 7 handles native-command stderr and argument quoting more predictably; 5.1 is what is preinstalled on every Windows machine.
• Make failures terminating. Setting both $PSNativeCommandUseErrorActionPreference = $true and $ErrorActionPreference = 'Stop' (PowerShell 7.3 and later) turns a non-zero exit code from GeoDmsRun into a terminating error, so you no longer have to test $LASTEXITCODE after every call.
• Execution policy. A downloaded .ps1 may be blocked. Run it once with powershell -ExecutionPolicy Bypass -File .\run.ps1, or unblock the file with Unblock-File .\run.ps1.
• Environment variables are $env:ProjDir in PowerShell, not %ProjDir%.
• Line continuation is a backtick ` at end of line, not ^.

---

further notes

• LocalDataDir. Its value is read from the registry key Software\ObjectVision\DMS\LocalDataDir (default C:\LocalData), and can be changed via Tools > Options in the GeoDMS GUI. GeoDmsRun prints the value it uses as the first line of its output.
• Logging. The GUI's logging settings saved in the registry are ignored by GeoDmsRun — use the /L option to enable logging.
• The GUI equivalent. For an interactive session, see User Guide GeoDMS GUI; for scripting the GUI itself, see Gui scripting.