openswmm_controls_impl.cpp File Reference

C API implementation — control rules and direct link control actions. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_controls.h"
#include "../controls/Controls.hpp"
#include "../edit/ObjectDeleter.hpp"
#include <algorithm>
#include <cctype>
#include <cstring>
#include <string>

Include dependency graph for openswmm_controls_impl.cpp:

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_remove_rule (SWMM_Engine engine, int idx)
	Remove one control rule by index.
SWMM_ENGINE_API int	swmm_control_find_references (SWMM_Engine engine, const char *object_name, int *rule_indices_out, int *n_inout)
	Find control rules whose text references an object by name.
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

C API implementation — control rules and direct link control actions.

See also

include/openswmm/engine/openswmm_controls.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 Apache-2.0

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.

Behaviour depends on the engine's lifecycle state:

• CREATED / BUILDING / OPENED — the text is stored verbatim and compiled later by swmm_engine_initialize(). It is not validated here, because the objects a rule references may legitimately not exist yet while a model is being built.
• INITIALIZED and beyond — rules have already been compiled, so the text is parsed and compiled into the live control engine and takes effect immediately. Text the parser rejects is not stored; swmm_get_last_error_msg then carries a "line N: reason" diagnostic. Use swmm_control_validate_rule to pre-flight.

Parameters

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

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if the engine is initialized and the parser rejects the text or finds no rule in it, or another error code.

Here is the call graph for this function:

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_find_references()

SWMM_ENGINE_API int swmm_control_find_references	(	SWMM_Engine	engine,
		const char *	object_name,
		int *	rule_indices_out,
		int *	n_inout )

Find control rules whose text references an object by name.

Scans each rule's clauses for an object-type keyword (NODE, LINK, CONDUIT, PUMP, ORIFICE, WEIR, OUTLET) immediately followed by object_name (case-insensitive, matching legacy rule parsing). Read-only — no delete ever edits rule text; callers decide what to do with affected rules.

Parameters

engine	Engine handle.
object_name	Object name to search for.
rule_indices_out	Receives matching rule indices, ascending (may be NULL to query the count only).
n_inout	In: capacity of rule_indices_out (ignored when it is NULL). Out: total number of matching rules.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADPARAM if object_name or n_inout is NULL.

Here is the call graph for this function:

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_remove_rule()

SWMM_ENGINE_API int swmm_control_remove_rule	(	SWMM_Engine	engine,
		int	idx )

Remove one control rule by index.

Later rule indices shift down by one. BUILDING/OPENED state only.

Parameters

engine	Engine handle.
idx	Zero-based rule index (0..swmm_control_count()-1).

Returns

SWMM_OK, SWMM_ERR_LIFECYCLE, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

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 human-readable "line N: reason" message to errbuf (truncated to fit), with the same 1-based line number in line_out. The line number counts blank lines, so it indexes rule_text exactly as submitted. When the text parses but contains no rule at all, line_out is -1 — there is no single offending line.

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: