openswmm_controls.h File Reference

OpenSWMM Engine — Control Rules C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_controls.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
SWMM_ENGINE_API int	swmm_control_add_rule (SWMM_Engine engine, const char *rule_text)
	Add a control rule from its text representation.
SWMM_ENGINE_API int	swmm_control_count (SWMM_Engine engine)
	Get the total number of control rules defined.
SWMM_ENGINE_API int	swmm_control_get_rule (SWMM_Engine engine, int idx, char *buf, int buflen)
	Get the text of a control rule by index.
SWMM_ENGINE_API int	swmm_control_get_id (SWMM_Engine engine, int idx, char *buf, int buflen)
	Get the canonical name of a control rule by index.
SWMM_ENGINE_API int	swmm_control_clear_rules (SWMM_Engine engine)
	Remove all control rules from the model.
SWMM_ENGINE_API int	swmm_control_validate_rule (SWMM_Engine engine, const char *rule_text, char *errbuf, int buflen, int *line_out)
	Validate a control-rule text block without storing it.
SWMM_ENGINE_API int	swmm_control_set_link_setting (SWMM_Engine engine, int link_idx, double setting)
	Directly set the control setting of a link.
SWMM_ENGINE_API int	swmm_control_set_link_status (SWMM_Engine engine, int link_idx, int status)
	Directly set the open/close status of a link.

Detailed Description

OpenSWMM Engine — Control Rules C API.

Control rule addition, retrieval, clearing, and direct link setting/status overrides.

See also

openswmm_engine.h

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n MIT License

Function Documentation

swmm_control_add_rule()

SWMM_ENGINE_API int swmm_control_add_rule	(	SWMM_Engine	engine,
		const char *	rule_text
	)

Add a control rule from its text representation.

The rule text follows the standard SWMM control rule syntax (e.g., "RULE R1\\nIF NODE J1 DEPTH > 5\\nTHEN PUMP P1 STATUS = ON"). Lines are separated by newline characters within the string.

Parameters

engine	Engine handle.
rule_text	Null-terminated string containing the full rule text.

Returns

SWMM_OK on success, or an error code.

swmm_control_clear_rules()

SWMM_ENGINE_API int swmm_control_clear_rules

(

SWMM_Engine

engine

)

Remove all control rules from the model.

Parameters

engine

Engine handle.

Returns

SWMM_OK on success, or an error code.

swmm_control_count()

SWMM_ENGINE_API int swmm_control_count

(

SWMM_Engine

engine

)

Get the total number of control rules defined.

Parameters

engine

Engine handle.

Returns

Number of control rules, or -1 on error.

swmm_control_get_id()

SWMM_ENGINE_API int swmm_control_get_id	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen
	)

Get the canonical name of a control rule by index.

Parses the stored rule text and returns the first whitespace-delimited token that follows the RULE keyword (case-insensitive match, leading whitespace tolerated). On parse failure — when the rule text does not begin with a RULE keyword token — returns SWMM_ERR_BADPARAM so callers can surface a sentinel display name for malformed rules.

Parameters

engine	Engine handle.
idx	Zero-based rule index.
buf	[out] Caller-allocated buffer to receive the rule name.
buflen	Size of buf in bytes.

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if the rule text has no parseable RULE token, or another error code.

swmm_control_get_rule()

SWMM_ENGINE_API int swmm_control_get_rule	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen
	)

Get the text of a control rule by index.

Parameters

engine	Engine handle.
idx	Zero-based rule index.
buf	Caller-allocated buffer to receive the rule text.
buflen	Size of buf in bytes.

Returns

SWMM_OK on success, or an error code.

swmm_control_set_link_setting()

SWMM_ENGINE_API int swmm_control_set_link_setting	(	SWMM_Engine	engine,
		int	link_idx,
		double	setting
	)

Directly set the control setting of a link.

Bypasses the control rule engine. For pumps: 0.0=off, 1.0=full. For orifices/weirs: fractional opening [0, 1].

Parameters

engine	Engine handle (RUNNING state).
link_idx	Zero-based link index.
setting	Setting value.

Returns

SWMM_OK on success, or an error code.

swmm_control_set_link_status()

SWMM_ENGINE_API int swmm_control_set_link_status	(	SWMM_Engine	engine,
		int	link_idx,
		int	status
	)

Directly set the open/close status of a link.

Bypasses the control rule engine. Status: 0=closed, 1=open.

Parameters

engine	Engine handle (RUNNING state).
link_idx	Zero-based link index.
status	0 for closed, non-zero for open.

Returns

SWMM_OK on success, or an error code.

swmm_control_validate_rule()

SWMM_ENGINE_API int swmm_control_validate_rule	(	SWMM_Engine	engine,
		const char *	rule_text,
		char *	errbuf,
		int	buflen,
		int *	line_out
	)

Validate a control-rule text block without storing it.

Runs the engine's control-rule parser against the engine's live SimulationContext for name resolution (NODE / LINK / CURVE / TIMESERIES references), but does not mutate the engine's rule list or PID state. Designed for GUI-side live validation where the editor needs the production parser's accept/reject verdict on each keystroke without side effects.

The validation contract matches swmm_control_add_rule followed by a simulation-initialisation parse: identical input text yields identical accept/reject. Engine state across the call is invariant — swmm_control_count, swmm_control_get_rule, and the engine's internal ControlEngine::rules() vector are unchanged.

On reject the function returns SWMM_ERR_BADPARAM and writes a short human-readable message to errbuf (truncated to fit). Line-precise error reporting is not yet wired through the parser; line_out is set to -1 on reject. Future work may carry a 1-based line index through the parser.

Parameters

engine	Engine handle.
rule_text	Null-terminated rule text. Same grammar as the [CONTROLS] section.
errbuf	[out, optional] Buffer for the rejection message. May be NULL or zero-length to suppress message capture.
buflen	Size of errbuf in bytes.
line_out	[out, optional] 1-based line number of the rejection, or -1 if not available. May be NULL.

Returns

SWMM_OK if the parser accepts the text, SWMM_ERR_BADPARAM if it rejects, or another error code on infrastructure failure.

Here is the call graph for this function: