Configuration format

Declarations and directive names are case-sensitive. Blank lines and lines starting with # are ignored. Names and declaration filenames are whitespace separated tokens; quoting does not allow spaces in those fields. Directive text such as aliases, commands, and guidance can contain spaces.

GROUP NULL Facility
GROUP Facility Vacuum
CHANNEL Vacuum example:pressure -----
$ALIAS Vacuum pressure
$BEEPSEVR MAJOR
$GUIDANCE
Check the vacuum controller before acknowledging this alarm.
$END

Exactly one root group is required. A parent must be the current group or one of its ancestors (for a channel, lookup starts at its parent), so arrange the file in tree order. A group cannot be named NULL or repeat an ancestor's name; repeated group names in separate branches are allowed. Group nesting is limited to 50 levels.

CHANNEL parent pv [mask] defaults to -----. Masks are sets of uppercase letters and save in canonical CDATL positions; short/reordered forms such as D and DA are accepted.

Letter	Setting
C	Cancel: stop the channel's alarm subscription.
D	Disable: exclude the alarm from active group severity, history, commands, and audible indication; monitoring continues unless also cancelled.
A	NoAck: exclude the channel from acknowledgement requirements.
T	NoAckT: do not retain cleared transient alarms for acknowledgement. In global mode this corresponds to IOC ACKT being zero.
L	NoLog: suppress this channel's alarm records.

Disable alone does not suppress alarm-file records; use NoLog for that. Timed NoAck is an operator setting and displays H in the mask summary.

INCLUDE parent filename attaches another file beneath the named parent. Every relative include, including nested includes, resolves against -f or ALARMHANDLER (default .), not the containing include's directory. For example, use qtalh -f /path/to/configs main.alhConfig. Absolute paths are accepted. Within an included file, each GROUP NULL attaches beneath the current group, matching ALH; after a channel, that means its parent group. Include cycles and excessive nesting are errors. The C++ loadConfig API uses the top-level file's directory when no configuration directory is supplied.

Directives normally apply to the preceding group/channel:

Directive	Arguments and behavior
$ALIAS	Display label text; the underlying PV/group name is unchanged.
$GUIDANCE	URL or filename, opened externally. Relative guidance files resolve from the document directory. With no inline value, read text through $END into a guidance dialog. Multiple inline blocks on a node are combined in order.
$COMMAND	Related command, or label ! command ! label ! command menu pairs. Commands starting with medm (including a quoted or absolute executable path) silently launch qtedm from PATH instead, preserving arguments. Configuration text is unchanged. This substitution also applies to severity/status commands.
$BEEPSEVERITY	Facility beep threshold (default MINOR); may occur before the root.
$BEEPSEVR	Threshold for the current node; ancestor thresholds also apply. The last directive on a node wins.
$HEARTBEATPV	pv [interval_seconds [short_integer_value]]; defaults 1 second and value 1. The first heartbeat in the facility, including includes, wins. Writes require global active mode.
$ACKPV	pv short_integer_value; channel only. Written on global active acknowledgement.
$SEVRPV	Output PV for the node's severity (0–4); disabled channels publish -1. Writes require global active mode. - leaves the output unset; the first real PV replaces earlier - placeholders and takes precedence over later directives.
$FORCEPV	pv mask [force_value [reset_value]]; default force 1, reset 0. At force, apply the mask; at reset, restore configured channel masks. NE or a reset equal to force resets on leaving the force value. Applies to descendant channels for a group.
$FORCEPV_CALC	EPICS CALC expression required when the FORCEPV name is CALC.
$FORCEPV_CALC_A through $FORCEPV_CALC_F	Numeric constants or PV inputs for CALC. Unspecified inputs default to zero; all named PV inputs must become available before evaluation.
$SEVRCOMMAND	UP_severity command or DOWN_severity command, matching direction and destination severity; ANY matches any change in that direction, UP_ALARM matches leaving NO_ALARM. Channel startup is evaluated from ERROR, matching ALH. Repeat to add commands.
$STATCOMMAND	status command; channel only, runs when entering that status. Repeat to add commands. Status names follow EPICS alarm names and the additional connection/access states in qtalh/core/model.cc.
$ALARMCOUNTFILTER	count seconds; channel only. Omitted count and seconds each default to 1. Legacy alarm count/time filtering: count -1 delays alarm onset, 0 also holds clearing transitions, positive counts track repeated alarm edges within the interval. Zero seconds disables filtering. Accepted count range: -1 through 1,000,000; seconds must be a nonnegative integer.

Fixed-argument directives accept trailing comments beginning with a whitespace-separated #, for example $SEVRPV output # severity mirror. Hashes within PV names remain part of the name. Commands, aliases, and guidance retain their complete text. $FORCEPV_CALC A > 0 # beam inhibit also accepts a trailing comment. A valid complete CALC expression takes precedence, preserving the # not-equal operator in expressions such as A # B.

Scalar Force PV values compare at double precision; CALC force/reset values compare at float precision. For NE (or reset equal to force), Qt consistently uses float precision to recognize the previous forced CALC value before resetting. This intentionally fixes an ALH inconsistency that could leave a force mask applied after a rounded match. For example, force 16777216 with CALC results 16777217 then 16777220 applies and then resets the mask.

With -global -caputackt, if a PV occurs more than once with different configured T bits, ALH's startup order decides the final setting: subgroups first, then direct channels within each group; the last occurrence in that traversal wins. Cancelled channels participate. Qt sends the final setting once per PV when writable.

Severities are NO_ALARM, MINOR, MAJOR, INVALID, and ERROR (0–4). Severity values also accept numbers and case-insensitive names; command direction prefixes UP_ and DOWN_ are uppercase. Heartbeat intervals must be finite, positive, and no greater than 2147483.647 seconds; scheduling rounds to milliseconds with a 1 ms minimum. Event-loop delays can delay a beat; missed beats are skipped. Heartbeat writes and the precise timer pause while the PV is disconnected or unwritable. One diagnostic is reported per outage. The ordinary refresh checks availability and resumes the timer within about 200 ms after CA reports recovery. In global mode, communication failures have a separate local ERROR acknowledgement. They remain audible and visible in the unacknowledged filter. Acknowledging that error does not write to the IOC or ACKPV; any outstanding IOC alarm remains pending. The error latch survives recovery when transient acknowledgement is enabled, or clears on recovery with NoAckT. Failed IOC acknowledgement submissions are logged as failures and do not trigger ACKPV or acknowledgement-success records.

Severity and heartbeat outputs use the legacy short-integer CA type; ACKPV uses the legacy unsigned-enum type. This also preserves integer text on string PVs.

Commands use /bin/sh -c on Linux/macOS and cmd.exe /d /s /c on Windows. Use commands appropriate to the host. A leading MASTER_ONLY restricts a command to the logging master. Stop-logging broadcasts also temporarily suppress commands. The editor does not execute runtime alarm commands.

Open/insert failures leave the current document intact. Save uses an atomic file replacement, expands includes, normalizes masks, orders channels before child groups, and discards comments and original formatting. Runtime Save As exports masks without changing the original configuration's reload, lock, or broadcast identity; editor Save As changes the document filename.