Command-line options

Syntax: qtalh [OPTIONS] [configfile]. One configuration is supported per invocation; the UI can open additional windows. A missing runtime filename means ALH-default.alhConfig. If it does not exist, interactive startup opens a file chooser. The headless validator instead reports the missing file. Configuration filenames and -a/-o arguments beginning with ./ or ../ resolve against the working directory, overriding -f, -l, and ALARMHANDLER. Absolute paths also override those directories; bare filenames use them. INCLUDE paths retain their separate configuration-directory rule.

Option	Meaning and default
-c	Configuration editor; otherwise runtime monitoring.
-global	Use IOC ACKS/ACKT fields for global acknowledgement. Default: local acknowledgement.
-S	Passive mode: suppress CA and pvAccess writes and operator acknowledgement.
-caputackt	In global active mode, write each record's configured transient acknowledgement (ACKT) setting once, when a configured channel first becomes writable after startup or reload. This includes an IOC that connects, or grants write access, later. Force PVs can also write ACKT without it; see $FORCEPV.
-D	Disable alarm and operation file logging. Does not disable CA writes or configured helper queues.
-s	Start with Silence Forever enabled; it can be changed in Setup.
-p file	Play a local audio file instead of the system beep. Formats depend on the installed Qt Multimedia backend; the suite exercises Ogg/Vorbis.
-f dir	Configuration and INCLUDE directory. Default: ALARMHANDLER, or the working directory (.).
-l dir	Log directory. Default: the configuration directory. Create it before starting.
-a file	Alarm filename, relative to the log directory unless absolute or explicitly prefixed with ./ or ../. Default: ALH-default.alhAlarm.
-o file	Operation filename, relative to the log directory unless absolute or explicitly prefixed with ./ or ../. Default: ALH-default.alhOpmod.
-m count	Alarm retention in records; default 2000, or unlimited with -L. An explicit -m overrides either default; 0 means unlimited. Does not bound the operation log. Without -T or -L, startup empties an existing alarm file, as in ALH.
-T	Append .yyyy-MM-dd to each log filename, using local dates. The alarm record limit still applies, including to an existing file for the current day: at the first alarm, a file holding more records than the limit keeps only its newest records, while ALH appends to it. Use -m 0 to keep every record.
-xml	Write legacy XML-like entry records; these are not a complete XML document.
-L	Coordinate master/slave alarm logging with a lock. Alarm retention defaults to unlimited unless -m is supplied.
-Lfile basename	Override the lock basename; requires -L to enable locking. Default: resolved configuration filename.
-B	Enable file-based message, reload, and temporary stop-logging broadcasts.
-P key	Send alarm records to a printer System V queue; positive decimal integer, Linux/macOS only. Unlike ALH, -L is not required; without it every instance sends its alarm records.
-O key	Send database records to a System V queue; positive decimal integer, Linux/macOS only. Unlike ALH, -L is not required; without it every instance sends its alarm records.
-filter no|active|unack	Initial display filter; default no. Active includes active or unacknowledged alarms. Filtering does not stop monitoring.
-mainwindow	Open the main runtime window at startup.
-maskcolor	Color the mask controls.
-noerrorpopup	Suppress error message boxes; errors still appear in the window message area, Qt diagnostic output, and operation log when logging is enabled.
-desc_field	Subscribe to each channel record's .DESC field for descriptions.
-debug	Timestamped startup, alarm, CA, command, logging, and broadcast diagnostics on stderr. Default: off.
-display display, --display display	Set DISPLAY before opening the GUI (for X11).
-geometry geometry	Initial geometry of the compact runtime window, or the main window with -mainwindow or -c. Accepts dimensions and/or position, such as 1000x600+20+20 or -20-20; negative offsets measure from the available screen’s right/bottom edges.
-fn font, -font font	Runtime button font; defaults to ALHMAINFONT when set. XLFD fonts are approximated.
-platform platform	Qt platform selection, for example offscreen or xcb.
-style name, -style=name	Appearance: modern (default), motif (classic ALH look), fusion, or an installed Qt Widgets style. Names are case-insensitive; the last occurrence wins.
-help, --help, -h	Print help without opening a display.
-version, --version, -v	Print the QtALH version, the ALH version it is based on, and the Qt and EPICS versions without opening a display.
--validate	Parse the configuration and includes, report group/channel counts, then exit.
--to-phoebus out.xml	Convert the configuration to Phoebus alarm XML, report unconverted settings, then exit.
--from-phoebus out.alhConfig	Convert the Phoebus XML file given as the configuration argument to an ALH configuration, then exit.
--	End options before the configuration filename.

Local mode keeps acknowledgements in this runtime. Global active mode can write ACKS/ACKT and configured acknowledgement, severity, and heartbeat PVs. Passive mode still monitors alarms and can log them. It does not disable configured shell commands; -D and -s also leave command execution enabled.

EPICS Base reads the standard EPICS_CA_* environment variables. QT_QPA_PLATFORM selects Qt's display backend; QT_PLUGIN_PATH can locate plugins from a separate SDK. On Windows, COMSPEC selects the command shell (default cmd.exe). Sound paths and an explicit relative -Lfile basename resolve from the process working directory, rather than -f or -l. Unknown switches and arbitrary Xt resource overrides are errors. CDEV and CMLOG extensions are not supported by QtALH.

Operator tools

The runtime's View menu adds tools that ALH does not have; they work in every appearance:

• Active Alarms… (Ctrl+L): a sortable, filterable table of every channel in alarm or awaiting acknowledgement, with Acknowledge, Guidance, Details and Show in Tree.
• Find Alarm… (Ctrl+F, also in the editor): search names, aliases, PVs and paths, and select the match in the tree.
• Alarm Details… (Ctrl+D): live state, configured versus runtime settings, an explanation of why the channel alarms, and the record's alarm limits read from the IOC.
• Runtime Overrides…: masks, beep severities, Force PVs, NoAck timers and shelves that differ from the configuration, with Restore Selected. Restoring a mask, NoAck timer or Force PV acts like the matching Action command, so in global active mode it can write ACKT, ACKS, $ACKPV and $SEVRPV. Restoring a mask set by an active Force PV overrides that Force PV. Failed $ACKPV submissions also appear here. Retry ACKPV submits one failed action per selected row without repeating ACKS; retries are explicit.
• Alarm Summary Panel…: a tile per top-level group with alarm counts.

File → Import/Export Phoebus XML… and --to-phoebus/--from-phoebus convert to and from the Phoebus alarm-server format. See Active alarms, search & details and Phoebus XML import & export.

Other menu commands follow ALH. View → Configuration File shows the loaded configuration as read-only text with Find. Setup → New Alarm Log File… and Setup → New Operation Modification Log File… switch this runtime's log files; see Read alarm logs. The editor's File → Report…, File → Print…, File → Close All, and Insert → Configuration File… are described in Create & edit a configuration.

Choosing an appearance

QtALH starts with its modern appearance. It keeps ALH's two alarm panes, row layout, menus, keyboard shortcuts, alarm colors and letters, mask and count notation, and the actions of every dialog it provides, with a cleaner presentation: flat severity chips, a tinted selection, a frameless status area, an expandable alarm legend, tabbed Properties, a state-showing Modify Mask Settings dialog, a tabular Current Alarm History, and a shared find bar in text viewers. The palette follows a dark desktop. Modeless dismiss buttons are labeled Close; Apply, Cancel, and Reset retain their behavior. Neither appearance has ALH's Modify NoAck Mask dialog; see NoAck for One Hour under Selection and alarm silence.

Use qtalh -style motif -mainwindow facility.alhConfig (or qtalh -c -style motif facility.alhConfig for the editor) to retain the original Motif-influenced appearance. -style fusion or another installed Qt Widgets style applies that style's controls and the desktop palette to the modern layouts. Selection applies to this process, including runtime windows opened from the editor; it is not saved in the alarm configuration or user preferences.

Other styles depend on the Qt installation and operating system. Unknown names produce an error listing available styles before any PV connections are made. Help, version, and configuration validation do not require a display and do not check style availability. QT_STYLE_OVERRIDE does not change the appearance. -fn/-font and ALHMAINFONT continue to affect only the compact runtime button.

Outside Motif mode, fonts default to one point smaller than the system font sizes (with a minimum of 6 points). An explicitly configured runtime-button font keeps its requested size. Ctrl+- decreases the font size, Ctrl++ (or Ctrl+=) increases it, and Ctrl+0 restores the startup size. Use Command instead of Ctrl on macOS. Each press changes the size by one point, with a UI range of 6–72 points. Changes apply throughout the process, including open dialogs and newly opened windows; monospace text and custom runtime-button fonts retain their families. Font sizes are not saved between launches. Bare + and - continue to expand and collapse the alarm tree. These font shortcuts are disabled in Motif mode.

See appearance details and screenshots for the dialog layouts and legacy comparison.