Command line options

GeoDMS has two executables: the interactive GeoDMS GUI (GeoDmsGuiQt.exe) and the headless GeoDMSRun (GeoDmsRun.exe). Both use the same small command-line grammar and share one set of status flags. This page is the reference for both.

For task-oriented guidance, see User Guide GeoDMS RUN. It covers shell quoting, batch files, exit codes and the @… action commands of GeoDmsRun.

GeoDmsGuiQt.exe

GeoDmsGuiQt.exe [/L<LogFile>] [/T<TestScript>] [/S<X> /C<X> …] [/noconfig] [<ConfigFile.dms> [<Item>]]

The parser processes the arguments strictly from left to right, and it expects them in the order shown above. An option in the wrong place is no longer treated as an option:

  • before the configuration file name, it is rejected as unknown;
  • after the configuration file name, it is silently taken as an item name.
Argument Description
/L<LogFile> Write a session log to <LogFile>. Must be the very first argument. No space between /L and the path (/LC:\tmp\log.txt).
/T<TestScript> Replay a GUI script and exit with its result. Must come after /L and before the status flags. Used by the Release Testing System.
/S<X> / /C<X> Set or Clear status flag <X>. Any number of them, in any order, but they must come before the configuration file name. See status flags.
/noconfig Start with no configuration loaded, even when Reopen last configuration at startup is switched on.
<ConfigFile.dms> The configuration to open at startup. When it is omitted, the GUI starts empty — unless Reopen last configuration at startup is on, in which case the last configuration is reopened.
<Item> The tree item to select as current item once the configuration is loaded.

Any other argument that starts with / (on Linux: with -) before the configuration file name is rejected with “Unknown command-line option …”. The message appears in an error dialog and on standard output, and the GUI exits with code 9.

/F<message> is reserved for internal use. The crash reporter starts the executable again with it to show a fatal-error box. Do not use it interactively.

item paths are resolved from the configuration root

The outermost container of the configuration file is the root, so it is not part of the path. Take container foo { container export { … } } in foo.dms: you write export or /export, and both work. Do not write foo/export: it silently leaves the root selected.

You can give more than one item, but only the last one is used. The earlier ones are ignored.

a hidden item needs /SA

While admin mode is off, you cannot select an item that is hidden or that lives inside a hidden container. The event log then says “cannot set ‘…’ as Current Item, as it is a hidden sub-item of ‘…’“. Put /SA at the start of the command line to open the configuration with hidden items visible:

GeoDmsGuiQt.exe /SA C:\prj\cfg\main.dms /diagnostics/hidden_stuff

GeoDmsRun.exe

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

The same rules apply: /L first, then the status flags, then the configuration, then the items and @… action commands. Unknown options are rejected with exit code 2. User Guide GeoDMS RUN has the full description: action commands, exit codes, and cmd and PowerShell examples.

Here /L does one more thing than in the GUI: it also switches on the TraceLogFile status flag for the run. In the GUI that flag is a separate setting, under Settings > Local machine options.

No option limits the memory of a run. You do that from the outside: start GeoDmsRun.exe inside a Windows Job Object with a memory limit. See capping the memory of a batch run in User Guide GeoDMS RUN and #1257.

log lines while a run computes

GeoDmsRun writes its log lines while it computes. They go to standard output and, with /L, to the log file. Each line is written within about a second of the time it carries. The log file is written to disk as the lines come in, so you can follow the progress of a run with Get-Content -Wait or tail -f.

A script that reads the output should take two things into account:

  • GeoDmsRun’s own lines on standard output and standard error (Update …, Failure: …, the @statistics table) are not in strict time order with the log lines around them. A log line produced just before such a line can appear a fraction of a second after it. Every line is written whole. To order lines by time, use the time that each log line carries.
  • If standard output is redirected to a pipe that nobody reads, the computation does not stop. However, GeoDmsRun cannot end before its output is read. And while standard output is blocked, the log file receives no new lines either.

In the GUI, the GUI thread fills the event log.

the log file and fatal errors

A /L log file survives a fatal error, and it says what caused the error. This applies to both executables.

Log lines are buffered before they are written to disk. A fatal error is an error that reaches a point in the program where nothing can handle it. Even then, the buffer is written. So the log keeps the last messages before the failure, and those are the ones worth reading.

Such a run ends with a block like this. It is written to the log and to standard error, and flushed immediately:

FATAL: ==================================================================
FATAL: std::terminate called on thread 27
FATAL: uncaught task_canceled -- a cancellation escaped its CancelableFrame
FATAL: context chain of this thread (innermost first):
FATAL:   [0] while in ReadData for /SomeContainer/SomeItem
FATAL:   [1] ...
FATAL: see GeoDMS issue #1191; report this log.
FATAL: ==================================================================

The context chain names what the failing thread was working on. For a calculation thread, that is the item and the operation being computed. When you report a problem, send this block: it is the part that shows where the failure happened.

The process then ends with exit code 3. A failed assertion in a Debug build gives the same code; see the exit-code table in User Guide GeoDMS RUN. So an automated run sees an ordinary non-zero exit code, which a batch file can check with %ErrorLevel% or $LASTEXITCODE.

A fatal error is a defect in GeoDMS, not a configuration error. Errors in a configuration are reported as ordinary errors, in the Eventlog and with exit code 1 or 2.

status flags

A status flag is a single character. You switch it on with /S and off with /C. The flags are the command-line form of the StatusFlags registry value (see (Registry) Settings). The checkboxes in the GUI’s options dialogs write that same value.

in force

Option Effect Honoured by
/SA / /CA Admin mode: show / hide items configured with the Property IsHidden = "True", and their sub-items, in the TreeView. The same switch as Show hidden items in the GUI Options dialog. On when the registry holds no StatusFlags value yet. A configuration can carry its own value for this one, as ShowHiddenItems — see Config Options dialog — and the flag given here wins over it. GUI
/SC / /CC Show / hide the state colours of tree items in the TreeView. GUI
/SM / /CM Set / clear debug mode, which adds internal detail to the detail pages and to some diagnostics. GUI, Run
/SH / /CH Show / hide the thousand separator in reported numbers. GUI, Run
/SW / /CW Show / hide warnings about deprecated case mix-ups in tokens (item and function names). Note the direction: the stored flag is HideDepreciated, so /SW shows them and /CW hides them. GUI, Run
/SS /S0 / /CS /C0 Multi-threading level 0: let a running calculation be interrupted by the main thread, so the window keeps responding. GUI
/S1 /S2 /S3 / /C1 /C2 /C3 Multi-threading levels 1, 2 and 3. For a reproducible batch run, always set these explicitly, so the run does not depend on whatever the interactive user last configured. GUI, Run
/SP / /CP Switch performance logging on / off (off by default). With /SP, each operation and storage read logs a timing and memory-estimate line under the [performance] tag, and the memory diagnostics (huge alloc, census:, alloc histogram) are logged as well. GUI, Run
/SQ / /Sq / /CQ /Cq Enable resource-aware scheduling for this run, in enforce mode (/SQ) or in shadow, log-only mode (/Sq); /CQ or /Cq switch it off. Off by default. GUI, Run
/SB<MB> / /CB Cap the admission memory budget of resource-aware scheduling at <MB> megabytes, e.g. /SB65536 for 64 GB. No space before the number, like /L. /CB restores the budget derived from the machine. GUI, Run
/SF / /CF Switch free-store drainage on (the default) / off. With drainage on, freed memory blocks are handed back to the operating system once memory use passes the MemoryFlushThreshold percentage, instead of being kept in the free store for re-use. See MemoryDrainage in (Registry) Settings. GUI, Run

unrecognised letters

A letter that is not in the list above does not stop the run. It is reported as “Unrecognised command line Set option /S…”, and parsing continues with the next argument. If a flag seems to have no effect, check the event log or the console output: apart from that one line, a typo gives no sign.

these flags apply to one run, not to the user

/S… and /C… set an override for the running process only. The registry is not changed. This has two consequences:

  • A flag on the command line always wins over the registry, whatever the user last configured. That is why you can use it in a shortcut or a batch file.
  • But the override is not read-only. During the session the user can change the same switch in the GUI. If they then open Settings > GUI Options and press OK, all checkboxes of that dialog are written to the registry. This includes the value that came from the command line, which then becomes the new default for that user. The same holds for the parallel-processing options.

The value does not travel with the configuration. You can open the same configuration by double-clicking a .dms file, through the recent-files list, or through Reopen last configuration at startup. In all these cases the registry setting is used, not the flags of an earlier command line.

For Show hidden items there is a way around this. A configuration can carry the setting itself, as ConfigSettings/Overridable/ShowHiddenItems. It is applied every time that configuration is loaded, and /SA or /CA overrule it. See Config Options dialog.

seeing which flags are active

The GUI adds markers to its window caption:

  • [Hiding] when admin mode is off;
  • [HSC] when state colours are off;
  • [TL] when the trace log is on;
  • [C0] … [C3] for each multi-threading level that is off;
  • [,] when the thousand separator is on.

For the complete picture, see the System info section of the detail pages. It reports the StatusFlags value together with the names of the flags that are set.

source

The authoritative definitions live in rtc/dll/src/utl/Environment.cpp (RTC_ParseRegStatusFlag, the status-flag letters), qtgui/exe/src/main_qt.cpp (interpret_command_line_parameters, the GUI arguments) and run/exe/src/MainRun.cpp (the GeoDmsRun arguments).