Command line options
Both GeoDMS executables — the interactive GeoDMS GUI (GeoDmsGuiQt.exe) and the headless GeoDMSRun (GeoDmsRun.exe) — are driven from the same small command-line grammar and share one set of status flags. This page is the reference for both.
For task-oriented guidance, including shell quoting, batch files, exit codes and the @… action commands of GeoDmsRun, see User Guide GeoDMS RUN.
GeoDmsGuiQt.exe
GeoDmsGuiQt.exe [/L<LogFile>] [/T<TestScript>] [/S<X> /C<X> …] [/noconfig] [<ConfigFile.dms> [<Item>]]
Arguments are processed strictly left to right, and the order shown above is the order the parser expects. An option that arrives out of turn stops being an option: before the configuration file name it is rejected as unknown, and after it, it is silently swallowed 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. |
Anything else that starts with / (on Linux: with -) before the configuration file name is rejected with “Unknown command-line option …”, 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 re-invokes the executable 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. For container foo { container export { … } } in foo.dms you write export or /export — both work — but not foo/export, which silently leaves the root selected.
More than one item may be given, but only the last one is used; the earlier ones are ignored.
a hidden item needs /SA
Selecting an item that is hidden (or that lives inside a hidden container) fails while admin mode is off — the event log then says “cannot set ‘…’ as Current Item, as it is a hidden sub-item of ‘…’“. Prefix the command line with /SA 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> …]
Same rules: /L first, then the status flags, then the configuration, then the items and @… action commands. Unknown options are rejected with exit code 2. The full description — action commands, exit codes, cmd and PowerShell examples — is in User Guide GeoDMS RUN.
Here /L does one thing more than in the GUI: it also switches on the TraceLogFile status flag for the run. The GUI has that flag as a separate setting, under Settings > Local machine options.
Up to and including version 20.17, the built-in usage text of GeoDmsRun mentioned a /PProjName option. That option was never implemented and has been removed from the text; use the %projDir% placeholder mechanism instead, see Folders and Placeholders.
the log file and fatal errors
Since GeoDMS 20.18.0 a /L log file survives a fatal error, and says what caused it. This applies to both executables.
Log lines are buffered before they are written to disk. Until 20.18.0 that buffer was only emptied when the log was closed in an orderly shutdown, so a run that ended in a fatal error — an error reaching a point in the program where it could no longer be handled — lost everything still in the buffer. In practice that meant the log of a crashing run stopped well before the crash, and the last messages before the failure, the ones worth reading, were exactly the ones thrown away.
Such a run now ends with a block like this, 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, which for a calculation thread is the item and operation being computed. When reporting a problem, send this block: it is the part that identifies where the failure happened.
The process then ends with exit code 3 — see the exit-code table in User Guide GeoDMS RUN — the same code a failed assertion in a Debug build gives. Before 20.18.0 it ended with -1073740791 (0xC0000409) and no message at all — so an automated run saw a crash where it now sees an ordinary non-zero exit code, and a batch file that checks %ErrorLevel% or $LASTEXITCODE keeps working unchanged.
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, switched on with /S and off with /C. They are the command-line face of the StatusFlags registry value (see (Registry) Settings), which is also what the checkboxes in the GUI’s options dialogs write.
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. (since 20.10.0) | GUI, Run |
/SQ / /Sq / /CQ /Cq | Enable resource-aware scheduling for this run in enforce (/SQ) resp. shadow, log-only (/Sq) mode; /CQ or /Cq switch it off. Off by default. (since 20.10.0) | 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. (since 20.10.0) | 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. (since 20.11.0) | GUI, Run |
accepted, but without effect
/SV /SD /SE /ST /SI /SR (and their /C… counterparts) set the TreeView, Details, EventLog, Toolbar, CurrentItemBar and DynamicROI flags. These date from the MFC GUI; nothing in the current Qt GUI or in GeoDmsRun reads them. They are still accepted, so existing scripts keep working, but they change nothing. Panel visibility is a per-user setting of the GUI itself.
unrecognised letters
A letter that is not in the list above does not abort the run: it is reported as “Unrecognised command line Set option /S…” and parsing continues with the next argument. Check the event log or console output if a flag seems to have no effect — a typo is silent apart from that one line.
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 touched. Two consequences worth knowing:
- A flag on the command line always wins over the registry, whatever the user last configured. This is what makes it usable in a shortcut or a batch file.
- But it is not a read-only override. During the session the user can flip the same switch in the GUI, and if they open Settings > GUI Options and press OK, all of that dialog’s checkboxes — including the value that came from the command line — are written to the registry, and thus become the new default for that user. The same holds for the parallel-processing options.
The value does not travel with the configuration. Opening the same configuration by double-clicking a .dms file, through the recent-files list, or through Reopen last configuration at startup uses the registry setting, not the flags of some earlier command line. For Show hidden items there is a way around that: a configuration can carry the setting itself as ConfigSettings/Overridable/ShowHiddenItems, which is applied on every load of that configuration and overruled by /SA or /CA. See Config Options dialog.
seeing which flags are active
The GUI appends 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, and [,] when the thousand separator is on.
For the complete picture, the System info section of the detail pages 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).