C FFI wrapper for the OutputReader class. More...

#include "../../../include/openswmm/engine/openswmm_output.h"
#include "OutputReader.hpp"

Include dependency graph for openswmm_output_impl.cpp:

Macros
#define	CHECK_READER(h)

Functions
SWMM_ENGINE_API int	swmm_output_get_pollut_units (SWMM_Output handle, int index)
	Read a species column stored concentration-unit code.

SWMM_ENGINE_API int	swmm_output_has_subcatch_variable (SWMM_Output handle, int code)
	Node result variable indices.

SWMM_ENGINE_API SWMM_Output	swmm_output_open (const char *path)
	Allocate a reader for a binary output with a valid closing footer.

SWMM_ENGINE_API SWMM_Output	swmm_output_open_live (const char *path)
	Allocate a reader for the complete records of an output still being written.

SWMM_ENGINE_API int	swmm_output_refresh (SWMM_Output handle, int *periods)
	Update whole-period count and adopt a final footer on a live reader.

SWMM_ENGINE_API int	swmm_output_is_live (SWMM_Output handle)
	Read whether the output reader is still using live record counting.

SWMM_ENGINE_API void	swmm_output_close (SWMM_Output handle)
	Close the file and delete its independent output-reader handle.

SWMM_ENGINE_API int	swmm_output_get_version (SWMM_Output handle)
	Read the output writer version.

SWMM_ENGINE_API int	swmm_output_get_flow_units (SWMM_Output handle)
	Read the output file flow-unit selector.

SWMM_ENGINE_API int	swmm_output_get_subcatch_count (SWMM_Output handle)
	Read the output subcatchment count.

SWMM_ENGINE_API int	swmm_output_get_node_count (SWMM_Output handle)
	Read the output node count.

SWMM_ENGINE_API int	swmm_output_get_link_count (SWMM_Output handle)
	Read the output link count.

SWMM_ENGINE_API int	swmm_output_get_pollut_count (SWMM_Output handle)
	Read the output species-column count.

SWMM_ENGINE_API int	swmm_output_get_period_count (SWMM_Output handle)
	Read the output currently known whole-report count.

SWMM_ENGINE_API int	swmm_output_get_start_date (SWMM_Output handle, double *start_date)
	Read the calendar baseline stored in output report metadata.

SWMM_ENGINE_API int	swmm_output_get_report_step (SWMM_Output handle)
	Read the output configured reporting interval.

SWMM_ENGINE_API const char *	swmm_output_get_subcatch_id (SWMM_Output handle, int index)
	Borrow a subcatchment identifier from the output header.

SWMM_ENGINE_API const char *	swmm_output_get_node_id (SWMM_Output handle, int index)
	Borrow a node identifier from the output header.

SWMM_ENGINE_API const char *	swmm_output_get_link_id (SWMM_Output handle, int index)
	Borrow a link identifier from the output header.

SWMM_ENGINE_API const char *	swmm_output_get_pollut_id (SWMM_Output handle, int index)
	Borrow a species identifier from the output header.

SWMM_ENGINE_API int	swmm_output_get_subcatch_result (SWMM_Output handle, int period, int var, float *values)
	Read one subcatchment variable for all subcatchment rows at one period.

SWMM_ENGINE_API int	swmm_output_get_node_result (SWMM_Output handle, int period, int var, float *values)
	Read one node variable for all node rows at one period.

SWMM_ENGINE_API int	swmm_output_get_link_result (SWMM_Output handle, int period, int var, float *values)
	Read one link variable for all link rows at one period.

SWMM_ENGINE_API int	swmm_output_get_system_result (SWMM_Output handle, int period, int var, float *value)
	Read one system variable for the system at one period.

SWMM_ENGINE_API int	swmm_output_get_subcatch_series (SWMM_Output handle, int subcatch_idx, int var, int start_period, int end_period, float *values)
	Read a closed range of subcatchment report samples.

SWMM_ENGINE_API int	swmm_output_get_node_series (SWMM_Output handle, int node_idx, int var, int start_period, int end_period, float *values)
	Read a closed range of node report samples.

SWMM_ENGINE_API int	swmm_output_get_link_series (SWMM_Output handle, int link_idx, int var, int start_period, int end_period, float *values)
	Read a closed range of link report samples.

SWMM_ENGINE_API int	swmm_output_get_system_series (SWMM_Output handle, int var, int start_period, int end_period, float *values)
	Read a closed range of system report samples.

SWMM_ENGINE_API int	swmm_output_get_subcatch_attribute (SWMM_Output handle, int subcatch_idx, int period, float values, int count)
	Read subcatchment variables at one report record.

SWMM_ENGINE_API int	swmm_output_get_node_attribute (SWMM_Output handle, int node_idx, int period, float values, int count)
	Read node variables at one report record.

SWMM_ENGINE_API int	swmm_output_get_link_attribute (SWMM_Output handle, int link_idx, int period, float values, int count)
	Read link variables at one report record.

SWMM_ENGINE_API int	swmm_output_get_period_time (SWMM_Output handle, int period, double *time)
	Read the exact calendar timestamp of one report record.

SWMM_ENGINE_API int	swmm_output_get_node_stat_max_depth (SWMM_Output handle, int node_idx, double *value)
	Reconstruct node maximum reported depth from report records.

SWMM_ENGINE_API int	swmm_output_get_node_stat_max_overflow (SWMM_Output handle, int node_idx, double *value)
	Reconstruct node maximum reported overflow from report records.

SWMM_ENGINE_API int	swmm_output_get_node_stat_vol_flooded (SWMM_Output handle, int node_idx, double *value)
	Reconstruct node report-sampled flooding integral from report records.

SWMM_ENGINE_API int	swmm_output_get_node_stat_time_flooded (SWMM_Output handle, int node_idx, double *value)
	Reconstruct node report-sampled flooding duration from report records.

SWMM_ENGINE_API int	swmm_output_get_error_code (SWMM_Output handle)
	Read the output simulation footer error.

Detailed Description

C FFI wrapper for the OutputReader class.

Maps the C API declared in openswmm_output.h to the C++ OutputReader implementation. Each function casts the opaque SWMM_Output handle to an OutputReader pointer.

See also: openswmm_output.h — public C API; OutputReader.hpp — internal C++ reader

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: Apache-2.0

Macro Definition Documentation

◆ CHECK_READER

#define CHECK_READER ( h )

Value:

    do {                                                                                           \
        if (!(h))                                                                                  \
            return -1;                                                                             \
    } while (0)

Function Documentation

◆ swmm_output_close()

SWMM_ENGINE_API void swmm_output_close ( SWMM_Output handle )

Close the file and delete its independent output-reader handle.

All borrowed ID strings become invalid. Does not close or alter a separate simulation-engine handle.

Parameters

[in] handle Caller-owned live reader, or NULL for a no-op. Do not use afterward, close twice or close concurrently with another read.

◆ swmm_output_get_error_code()

SWMM_ENGINE_API int swmm_output_get_error_code ( SWMM_Output handle )

Read the output simulation footer error.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: Recorded simulation error (0 for success; live readers use 0 until a footer is adopted); -1 for null handle.

◆ swmm_output_get_flow_units()

SWMM_ENGINE_API int swmm_output_get_flow_units ( SWMM_Output handle )

Read the output file flow-unit selector.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: 0=CFS, 1=GPM, 2=MGD, 3=CMS, 4=LPS or 5=MLD; -1 for null handle.

◆ swmm_output_get_link_attribute()

SWMM_ENGINE_API int swmm_output_get_link_attribute	(	SWMM_Output	handle,
		int	link_idx,
		int	period,
		float *	values,
		int *	count )

Read link variables at one report record.

Values are in stored column order and each field retains its file unit. Provide enough space before calling; optional snow extensions are accessed by code through the subcatchment result/series APIs.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	link_idx	Zero-based link index in this output file.
[in]	period	Zero-based index in [0,swmm_output_get_period_count(handle)). Live readers require refresh to discover new whole records.
[out]	values	Non-null caller-owned destination sized for the full link-variable count floats (normally 5+species count).
[out]	count	Optional number of variables written, set only after the entire record read succeeds; this is not an input capacity or size-query mode.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_link_count()

SWMM_ENGINE_API int swmm_output_get_link_count ( SWMM_Output handle )

Read the output link count.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: Nonnegative number of link result rows; -1 for null handle.

◆ swmm_output_get_link_id()

SWMM_ENGINE_API const char * swmm_output_get_link_id	(	SWMM_Output	handle,
		int	index )

Borrow a link identifier from the output header.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	index	Zero-based link index in this file, independent of a model engine row order.

Returns: Reader-owned NUL-terminated ID, or NULL for null handle/out-of-range index. Never free it; storage remains valid until the reader is closed.

◆ swmm_output_get_link_result()

SWMM_ENGINE_API int swmm_output_get_link_result	(	SWMM_Output	handle,
		int	period,
		int	var,
		float *	values )

Read one link variable for all link rows at one period.

Values retain the file display-unit convention; optional UEB snow variables use their documented SI units. Reserved species use hours/degrees C. This API has no buffer-capacity argument, so allocation size is the caller responsibility.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	period	Zero-based index in [0,swmm_output_get_period_count(handle)). Live readers require refresh to discover new whole records.
[in]	var	SWMM_OutLinkVar variable index, including supported species slots for node/link results.
[out]	values	Non-null caller-owned array of at least this file's link count floats, in file object order.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_link_series()

SWMM_ENGINE_API int swmm_output_get_link_series	(	SWMM_Output	handle,
		int	link_idx,
		int	var,
		int	start_period,
		int	end_period,
		float *	values )

Read a closed range of link report samples.

The range endpoints are both inclusive. Returns stored reporting samples without temporal interpolation or automatic live refresh.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	link_idx	Zero-based link index in this output file.
[in]	var	SWMM_OutLinkVar variable index, including supported species slots for node/link results.
[in]	start_period	Inclusive first period, >=0 and <=end_period.
[in]	end_period	Inclusive last period, less than the currently known period count.
[out]	values	Non-null caller-owned array of end_period-start_period+1 floats, ordered chronologically in file display/extension units.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_node_attribute()

SWMM_ENGINE_API int swmm_output_get_node_attribute	(	SWMM_Output	handle,
		int	node_idx,
		int	period,
		float *	values,
		int *	count )

Read node variables at one report record.

Values are in stored column order and each field retains its file unit. Provide enough space before calling; optional snow extensions are accessed by code through the subcatchment result/series APIs.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	node_idx	Zero-based node index in this output file.
[in]	period	Zero-based index in [0,swmm_output_get_period_count(handle)). Live readers require refresh to discover new whole records.
[out]	values	Non-null caller-owned destination sized for the full node-variable count floats (normally 6+species count).
[out]	count	Optional number of variables written, set only after the entire record read succeeds; this is not an input capacity or size-query mode.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_node_count()

SWMM_ENGINE_API int swmm_output_get_node_count ( SWMM_Output handle )

Read the output node count.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: Nonnegative number of node result rows; -1 for null handle.

◆ swmm_output_get_node_id()

SWMM_ENGINE_API const char * swmm_output_get_node_id	(	SWMM_Output	handle,
		int	index )

Borrow a node identifier from the output header.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	index	Zero-based node index in this file, independent of a model engine row order.

Returns: Reader-owned NUL-terminated ID, or NULL for null handle/out-of-range index. Never free it; storage remains valid until the reader is closed.

◆ swmm_output_get_node_result()

SWMM_ENGINE_API int swmm_output_get_node_result	(	SWMM_Output	handle,
		int	period,
		int	var,
		float *	values )

Read one node variable for all node rows at one period.

Values retain the file display-unit convention; optional UEB snow variables use their documented SI units. Reserved species use hours/degrees C. This API has no buffer-capacity argument, so allocation size is the caller responsibility.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	period	Zero-based index in [0,swmm_output_get_period_count(handle)). Live readers require refresh to discover new whole records.
[in]	var	SWMM_OutNodeVar variable index, including supported species slots for node/link results.
[out]	values	Non-null caller-owned array of at least this file's node count floats, in file object order.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_node_series()

SWMM_ENGINE_API int swmm_output_get_node_series	(	SWMM_Output	handle,
		int	node_idx,
		int	var,
		int	start_period,
		int	end_period,
		float *	values )

Read a closed range of node report samples.

The range endpoints are both inclusive. Returns stored reporting samples without temporal interpolation or automatic live refresh.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	node_idx	Zero-based node index in this output file.
[in]	var	SWMM_OutNodeVar variable index, including supported species slots for node/link results.
[in]	start_period	Inclusive first period, >=0 and <=end_period.
[in]	end_period	Inclusive last period, less than the currently known period count.
[out]	values	Non-null caller-owned array of end_period-start_period+1 floats, ordered chronologically in file display/extension units.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_node_stat_max_depth()

SWMM_ENGINE_API int swmm_output_get_node_stat_max_depth	(	SWMM_Output	handle,
		int	node_idx,
		double *	value )

Reconstruct node maximum reported depth from report records.

Maximum over the currently known report samples. Scans O(period count) samples per call and may miss short events; use engine routing-step statistics when that precision is required.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	node_idx	Zero-based node index in this output file.
[out]	value	Non-null destination in file display length (ft US, m SI); zero when there are no report periods, unchanged on validation/read failure.

Returns: 0 on success or -1 for null arguments, invalid node index or read failure.

◆ swmm_output_get_node_stat_max_overflow()

SWMM_ENGINE_API int swmm_output_get_node_stat_max_overflow	(	SWMM_Output	handle,
		int	node_idx,
		double *	value )

Reconstruct node maximum reported overflow from report records.

Maximum over the currently known report samples. Scans O(period count) samples per call and may miss short events; use engine routing-step statistics when that precision is required.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	node_idx	Zero-based node index in this output file.
[out]	value	Non-null destination in file flow units selected by swmm_output_get_flow_units(); zero when there are no report periods, unchanged on validation/read failure.

Returns: 0 on success or -1 for null arguments, invalid node index or read failure.

◆ swmm_output_get_node_stat_time_flooded()

SWMM_ENGINE_API int swmm_output_get_node_stat_time_flooded	(	SWMM_Output	handle,
		int	node_idx,
		double *	value )

Reconstruct node report-sampled flooding duration from report records.

Counts positive-overflow report records and multiplies by report-step seconds. Counts full report intervals; it does not reconstruct sub-report-step onset/duration. Scans O(period count) samples per call and may miss short events; use engine routing-step statistics when that precision is required.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	node_idx	Zero-based node index in this output file.
[out]	value	Non-null destination in seconds; zero when there are no report periods, unchanged on validation/read failure.

Returns: 0 on success or -1 for null arguments, invalid node index or read failure.

◆ swmm_output_get_node_stat_vol_flooded()

SWMM_ENGINE_API int swmm_output_get_node_stat_vol_flooded	(	SWMM_Output	handle,
		int	node_idx,
		double *	value )

Reconstruct node report-sampled flooding integral from report records.

Sums positive stored overflow*report_step with no flow-to-volume unit conversion. CFS gives ft3 and CMS gives m3; GPM/MGD/LPS/MLD outputs need caller conversion before interpreting this as a physical volume. Scans O(period count) samples per call and may miss short events; use engine routing-step statistics when that precision is required.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	node_idx	Zero-based node index in this output file.
[out]	value	Non-null destination in numeric file flow unit multiplied by seconds; zero when there are no report periods, unchanged on validation/read failure.

Returns: 0 on success or -1 for null arguments, invalid node index or read failure.

◆ swmm_output_get_period_count()

SWMM_ENGINE_API int swmm_output_get_period_count ( SWMM_Output handle )

Read the output currently known whole-report count.

A live period count does not advance automatically; call swmm_output_refresh() to discover growth.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: Nonnegative current complete-period count; -1 for null handle.

◆ swmm_output_get_period_time()

SWMM_ENGINE_API int swmm_output_get_period_time	(	SWMM_Output	handle,
		int	period,
		double *	time )

Read the exact calendar timestamp of one report record.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	period	Zero-based index in [0,swmm_output_get_period_count(handle)). Live readers require refresh to discover new whole records.
[out]	time	Non-null destination for SWMM DateTime decimal days since 1899-12-30; no timezone conversion.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_pollut_count()

SWMM_ENGINE_API int swmm_output_get_pollut_count ( SWMM_Output handle )

Read the output species-column count.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: Nonnegative count including any reserved water-age/temperature species; -1 for null handle.

◆ swmm_output_get_pollut_id()

SWMM_ENGINE_API const char * swmm_output_get_pollut_id	(	SWMM_Output	handle,
		int	index )

Borrow a species identifier from the output header.

Species IDs WATER_AGE and TEMPERATURE denote hours and degrees C regardless of their stored concentration code.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	index	Zero-based species index in this file, independent of a model engine row order.

Returns: Reader-owned NUL-terminated ID, or NULL for null handle/out-of-range index. Never free it; storage remains valid until the reader is closed.

◆ swmm_output_get_pollut_units()

SWMM_ENGINE_API int swmm_output_get_pollut_units	(	SWMM_Output	handle,
		int	index )

Read a species column stored concentration-unit code.

Reserved WATER_AGE and TEMPERATURE columns reuse the concentration-unit field; identify them by species name and interpret as hours and degrees C. The unit code alone cannot identify a reserved species.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	index	Zero-based species-column index in [0,pollutant count).

Returns: Stored code 0=mg/L, 1=ug/L or 2=count/L, or -1 for null handle/invalid index.

◆ swmm_output_get_report_step()

SWMM_ENGINE_API int swmm_output_get_report_step ( SWMM_Output handle )

Read the output configured reporting interval.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: Report interval in seconds; -1 for null handle.

◆ swmm_output_get_start_date()

SWMM_ENGINE_API int swmm_output_get_start_date	(	SWMM_Output	handle,
		double *	start_date )

Read the calendar baseline stored in output report metadata.

Use actual period times for sample timestamps rather than assuming a particular origin/report-start alignment.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[out]	start_date	Non-null destination for SWMM DateTime/OADate decimal days since 1899-12-30; no timezone conversion.

Returns: 0 on success, -1 for null handle/start_date.

◆ swmm_output_get_subcatch_attribute()

SWMM_ENGINE_API int swmm_output_get_subcatch_attribute	(	SWMM_Output	handle,
		int	subcatch_idx,
		int	period,
		float *	values,
		int *	count )

Read subcatchment variables at one report record.

Values are in stored column order and each field retains its file unit. Provide enough space before calling; optional snow extensions are accessed by code through the subcatchment result/series APIs.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	subcatch_idx	Zero-based subcatchment index in this output file.
[in]	period	Zero-based index in [0,swmm_output_get_period_count(handle)). Live readers require refresh to discover new whole records.
[out]	values	Non-null caller-owned destination sized for 8+pollutant count legacy floats (optional UEB process fields are excluded).
[out]	count	Optional number of variables written, set only after the entire record read succeeds; this is not an input capacity or size-query mode.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_subcatch_count()

SWMM_ENGINE_API int swmm_output_get_subcatch_count ( SWMM_Output handle )

Read the output subcatchment count.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: Nonnegative number of subcatchment result rows; -1 for null handle.

◆ swmm_output_get_subcatch_id()

SWMM_ENGINE_API const char * swmm_output_get_subcatch_id	(	SWMM_Output	handle,
		int	index )

Borrow a subcatchment identifier from the output header.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	index	Zero-based subcatchment index in this file, independent of a model engine row order.

Returns: Reader-owned NUL-terminated ID, or NULL for null handle/out-of-range index. Never free it; storage remains valid until the reader is closed.

◆ swmm_output_get_subcatch_result()

SWMM_ENGINE_API int swmm_output_get_subcatch_result	(	SWMM_Output	handle,
		int	period,
		int	var,
		float *	values )

Read one subcatchment variable for all subcatchment rows at one period.

Values retain the file display-unit convention; optional UEB snow variables use their documented SI units. Reserved species use hours/degrees C. This API has no buffer-capacity argument, so allocation size is the caller responsibility.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	period	Zero-based index in [0,swmm_output_get_period_count(handle)). Live readers require refresh to discover new whole records.
[in]	var	SWMM_OutSubcatchVar variable CODE, including optional snow extension codes; not a physical column index.
[out]	values	Non-null caller-owned array of at least this file's subcatchment count floats, in file object order.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_subcatch_series()

SWMM_ENGINE_API int swmm_output_get_subcatch_series	(	SWMM_Output	handle,
		int	subcatch_idx,
		int	var,
		int	start_period,
		int	end_period,
		float *	values )

Read a closed range of subcatchment report samples.

The range endpoints are both inclusive. Returns stored reporting samples without temporal interpolation or automatic live refresh.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	subcatch_idx	Zero-based subcatchment index in this output file.
[in]	var	SWMM_OutSubcatchVar variable CODE, including optional snow extension codes; not a physical column index.
[in]	start_period	Inclusive first period, >=0 and <=end_period.
[in]	end_period	Inclusive last period, less than the currently known period count.
[out]	values	Non-null caller-owned array of end_period-start_period+1 floats, ordered chronologically in file display/extension units.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_system_result()

SWMM_ENGINE_API int swmm_output_get_system_result	(	SWMM_Output	handle,
		int	period,
		int	var,
		float *	value )

Read one system variable for the system at one period.

Values retain the file display-unit convention; optional UEB snow variables use their documented SI units. Reserved species use hours/degrees C. This API has no buffer-capacity argument, so allocation size is the caller responsibility.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	period	Zero-based index in [0,swmm_output_get_period_count(handle)). Live readers require refresh to discover new whole records.
[in]	var	SWMM_OutSystemVar variable index, including supported species slots for node/link results.
[out]	value	Non-null caller-owned single float destination.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_system_series()

SWMM_ENGINE_API int swmm_output_get_system_series	(	SWMM_Output	handle,
		int	var,
		int	start_period,
		int	end_period,
		float *	values )

Read a closed range of system report samples.

The range endpoints are both inclusive. Returns stored reporting samples without temporal interpolation or automatic live refresh.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	var	SWMM_OutSystemVar variable index, including supported species slots for node/link results.
[in]	start_period	Inclusive first period, >=0 and <=end_period.
[in]	end_period	Inclusive last period, less than the currently known period count.
[out]	values	Non-null caller-owned array of end_period-start_period+1 floats, ordered chronologically in file display/extension units.

Returns: 0 on success, -1 for null handle/output, invalid indices/variable/range, or a seek/read failure. A partial output prefix may have been written before an IO failure.

◆ swmm_output_get_version()

SWMM_ENGINE_API int swmm_output_get_version ( SWMM_Output handle )

Read the output writer version.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: Integer writer version (for example 52001); -1 for null handle.

◆ swmm_output_has_subcatch_variable()

SWMM_ENGINE_API int swmm_output_has_subcatch_variable	(	SWMM_Output	handle,
		int	code )

Node result variable indices.

Variables stored per node per output period. Pollutant concentrations follow at indices >= SWMM_OUT_NODE_POLLUT_BASE.

Check whether a subcatchment result variable CODE is present.

Examines header codes without requiring any completed reporting period.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[in]	code	SWMM_OutSubcatchVar code, including optional UEB snow codes; not a physical column index.

Returns: 1 when present, 0 when absent (including invalid codes), or -1 for null handle.

◆ swmm_output_is_live()

SWMM_ENGINE_API int swmm_output_is_live ( SWMM_Output handle )

Read whether the output reader is still using live record counting.

Parameters

[in] handle Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().

Returns: 1 while live, 0 after adopting a final footer or opening normally, -1 for null handle.

◆ swmm_output_open()

SWMM_ENGINE_API SWMM_Output swmm_output_open ( const char * path )

Allocate a reader for a binary output with a valid closing footer.

Opening does not imply the simulation footer error is zero; inspect swmm_output_get_error_code(). Object/species order and display units come from this output file, independently of any live model.

Parameters

[in] path Non-null NUL-terminated UTF-8 output path, borrowed for this call. File is opened read-only.

Returns: Caller-owned independent output handle, or NULL for allocation/open/header/footer failure. Close every successful handle exactly once.

◆ swmm_output_open_live()

SWMM_ENGINE_API SWMM_Output swmm_output_open_live ( const char * path )

Allocate a reader for the complete records of an output still being written.

Forward-parses offsets and counts only whole report records; no closing footer is needed. Can inspect running or interrupted output without modifying it. Refresh later for growth; a valid final footer is adopted when it arrives.

Parameters

[in] path Non-null NUL-terminated UTF-8 output path with a complete parseable header; opened read-only.

Returns: Caller-owned output handle, or NULL for allocation/open/header failure. Release with swmm_output_close().

◆ swmm_output_refresh()

SWMM_ENGINE_API int swmm_output_refresh	(	SWMM_Output	handle,
		int *	periods )

Update whole-period count and adopt a final footer on a live reader.

A non-live handle keeps its footer count. Live refresh sees new complete records and becomes non-live after a matching final footer appears; seek/size-query failure can return the previous count, so success does not guarantee growth. Does not retain partial report records.

Parameters

[in]	handle	Non-null live output-reader handle. Serialize access on one thread because result reads share a file cursor; release with swmm_output_close().
[out]	periods	Optional destination for the current period count, written after a nonnegative refresh result.

Returns: 0 on a nonnegative refresh result, -1 for null/unopened reader.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CHECK_READER

Function Documentation

◆ swmm_output_close()

◆ swmm_output_get_error_code()

◆ swmm_output_get_flow_units()

◆ swmm_output_get_link_attribute()

◆ swmm_output_get_link_count()

◆ swmm_output_get_link_id()

◆ swmm_output_get_link_result()

◆ swmm_output_get_link_series()

◆ swmm_output_get_node_attribute()

◆ swmm_output_get_node_count()

◆ swmm_output_get_node_id()

◆ swmm_output_get_node_result()

◆ swmm_output_get_node_series()

◆ swmm_output_get_node_stat_max_depth()

◆ swmm_output_get_node_stat_max_overflow()

◆ swmm_output_get_node_stat_time_flooded()

◆ swmm_output_get_node_stat_vol_flooded()

◆ swmm_output_get_period_count()

◆ swmm_output_get_period_time()

◆ swmm_output_get_pollut_count()

◆ swmm_output_get_pollut_id()

◆ swmm_output_get_pollut_units()

◆ swmm_output_get_report_step()

◆ swmm_output_get_start_date()

◆ swmm_output_get_subcatch_attribute()

◆ swmm_output_get_subcatch_count()

◆ swmm_output_get_subcatch_id()

◆ swmm_output_get_subcatch_result()

◆ swmm_output_get_subcatch_series()

◆ swmm_output_get_system_result()

◆ swmm_output_get_system_series()

◆ swmm_output_get_version()

◆ swmm_output_has_subcatch_variable()

◆ swmm_output_is_live()

◆ swmm_output_open()

◆ swmm_output_open_live()

◆ swmm_output_refresh()