openswmm_output.h File Reference

OpenSWMM Engine — Output File Reader C API. More...

#include "openswmm_engine_export.h"

Include dependency graph for openswmm_output.h:

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

Go to the source code of this file.

Typedefs
typedef void *	SWMM_Output
	Opaque handle to an opened output file reader.
typedef enum SWMM_OutSubcatchVar	SWMM_OutSubcatchVar
	Subcatchment result variable indices.
typedef enum SWMM_OutNodeVar	SWMM_OutNodeVar
typedef enum SWMM_OutLinkVar	SWMM_OutLinkVar
	Link result variable indices.
typedef enum SWMM_OutSystemVar	SWMM_OutSystemVar
	System-wide result variable indices.

Enumerations
enum	SWMM_OutSubcatchVar {   SWMM_OUT_SUBCATCH_RAINFALL = 0 ,   SWMM_OUT_SUBCATCH_SNOW_DEPTH = 1 ,   SWMM_OUT_SUBCATCH_EVAP = 2 ,   SWMM_OUT_SUBCATCH_INFIL = 3 ,   SWMM_OUT_SUBCATCH_RUNOFF = 4 ,   SWMM_OUT_SUBCATCH_GW_FLOW = 5 ,   SWMM_OUT_SUBCATCH_GW_ELEV = 6 ,   SWMM_OUT_SUBCATCH_SOIL_MOIST = 7 ,   SWMM_OUT_SUBCATCH_POLLUT_BASE = 8 ,   SWMM_OUT_SUBCATCH_SNOW_SWE = 65536 ,   SWMM_OUT_SUBCATCH_SNOW_ENERGY = 65537 ,   SWMM_OUT_SUBCATCH_SNOW_SURFACE_TEMP = 65538 ,   SWMM_OUT_SUBCATCH_SNOW_BULK_TEMP = 65539 ,   SWMM_OUT_SUBCATCH_SNOW_ALBEDO = 65540 ,   SWMM_OUT_SUBCATCH_SNOW_COVER = 65541 ,   SWMM_OUT_SUBCATCH_SNOW_MELT = 65542 ,   SWMM_OUT_SUBCATCH_SNOW_INPUT = 65543 ,   SWMM_OUT_SUBCATCH_SNOW_SUBLIMATION = 65544 ,   SWMM_OUT_SUBCATCH_SNOW_TIME = 65545 }
	Subcatchment result variable indices. More...
enum	SWMM_OutNodeVar {   SWMM_OUT_NODE_DEPTH = 0 ,   SWMM_OUT_NODE_HEAD = 1 ,   SWMM_OUT_NODE_VOLUME = 2 ,   SWMM_OUT_NODE_LATERAL_INFLOW = 3 ,   SWMM_OUT_NODE_TOTAL_INFLOW = 4 ,   SWMM_OUT_NODE_OVERFLOW = 5 ,   SWMM_OUT_NODE_POLLUT_BASE = 6 }
enum	SWMM_OutLinkVar {   SWMM_OUT_LINK_FLOW = 0 ,   SWMM_OUT_LINK_DEPTH = 1 ,   SWMM_OUT_LINK_VELOCITY = 2 ,   SWMM_OUT_LINK_VOLUME = 3 ,   SWMM_OUT_LINK_CAPACITY = 4 ,   SWMM_OUT_LINK_POLLUT_BASE = 5 }
	Link result variable indices. More...
enum	SWMM_OutSystemVar {   SWMM_OUT_SYS_TEMPERATURE = 0 ,   SWMM_OUT_SYS_RAINFALL = 1 ,   SWMM_OUT_SYS_SNOW_DEPTH = 2 ,   SWMM_OUT_SYS_INFIL = 3 ,   SWMM_OUT_SYS_RUNOFF = 4 ,   SWMM_OUT_SYS_DW_INFLOW = 5 ,   SWMM_OUT_SYS_GW_INFLOW = 6 ,   SWMM_OUT_SYS_RDII_INFLOW = 7 ,   SWMM_OUT_SYS_EXT_INFLOW = 8 ,   SWMM_OUT_SYS_TOTAL_INFLOW ,   SWMM_OUT_SYS_FLOODING = 10 ,   SWMM_OUT_SYS_OUTFLOW = 11 ,   SWMM_OUT_SYS_STORAGE = 12 ,   SWMM_OUT_SYS_EVAP = 13 ,   SWMM_OUT_SYS_PET = 14 ,   SWMM_OUT_SYS_LAT_INFLOW = SWMM_OUT_SYS_TOTAL_INFLOW }
	System-wide result variable indices. More...

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

OpenSWMM Engine — Output File Reader C API.

Provides a transparent C89-compatible API for reading binary output files (.out) produced by the DefaultOutputPlugin. The binary format is the standard SWMM 5.x output format containing:

• Header (magic, version, flow units, object counts)
• Object ID names
• Input properties (subcatchment areas, node geometry, link geometry)
• Per-period time series results (subcatch/node/link/system)
• Footer (section offsets, period count, error code)

Usage:

#include <openswmm/engine/openswmm_output.h>
 
SWMM_Output out = swmm_output_open("model.out");
if (!out) return 1; // handle error
 
int n = swmm_output_get_node_count(out);
int periods = swmm_output_get_period_count(out);
 
float* depths = malloc(n * sizeof(float));
swmm_output_get_node_result(out, 5, SWMM_OUT_NODE_DEPTH, depths);
// depths[j] is node j depth at period 5
 
float* ts_buf = malloc(periods * sizeof(float));
swmm_output_get_node_series(out, 0, SWMM_OUT_NODE_DEPTH,
                                  0, periods - 1, ts_buf);
 
free(ts_buf);
free(depths);
swmm_output_close(out);

See also

DefaultOutputPlugin.hpp — the writer that produces these files

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

Typedef Documentation

SWMM_OutLinkVar

typedef enum SWMM_OutLinkVar SWMM_OutLinkVar

Link result variable indices.

Variables stored per link per output period. Pollutant concentrations follow at indices >= SWMM_OUT_LINK_POLLUT_BASE.

SWMM_OutNodeVar

typedef enum SWMM_OutNodeVar SWMM_OutNodeVar

SWMM_Output

typedef void* SWMM_Output

Opaque handle to an opened output file reader.

SWMM_OutSubcatchVar

typedef enum SWMM_OutSubcatchVar SWMM_OutSubcatchVar

Subcatchment result variable indices.

Variables stored per subcatchment per output period. Pollutant concentrations follow at indices >= SWMM_OUT_SUBCATCH_POLLUT_BASE.

SWMM_OutSystemVar

typedef enum SWMM_OutSystemVar SWMM_OutSystemVar

System-wide result variable indices.

15 system-wide summary results stored per output period, in the slot order the .out writer uses (legacy SWMM 5 SysResults order).

Enumeration Type Documentation

SWMM_OutLinkVar

enum SWMM_OutLinkVar

Link result variable indices.

Variables stored per link per output period. Pollutant concentrations follow at indices >= SWMM_OUT_LINK_POLLUT_BASE.

Enumerator
SWMM_OUT_LINK_FLOW	Flow rate.
SWMM_OUT_LINK_DEPTH	Flow depth.
SWMM_OUT_LINK_VELOCITY	Flow velocity.
SWMM_OUT_LINK_VOLUME	Volume.
SWMM_OUT_LINK_CAPACITY	Fraction of conduit capacity.
SWMM_OUT_LINK_POLLUT_BASE	First pollutant concentration slot.

SWMM_OutNodeVar

enum SWMM_OutNodeVar

Enumerator
SWMM_OUT_NODE_DEPTH	Water depth above invert.
SWMM_OUT_NODE_HEAD	Hydraulic head.
SWMM_OUT_NODE_VOLUME	Stored water volume.
SWMM_OUT_NODE_LATERAL_INFLOW	Lateral inflow rate.
SWMM_OUT_NODE_TOTAL_INFLOW	Total inflow rate.
SWMM_OUT_NODE_OVERFLOW	Overflow rate.
SWMM_OUT_NODE_POLLUT_BASE	First pollutant concentration slot.

SWMM_OutSubcatchVar

enum SWMM_OutSubcatchVar

Subcatchment result variable indices.

Variables stored per subcatchment per output period. Pollutant concentrations follow at indices >= SWMM_OUT_SUBCATCH_POLLUT_BASE.

Enumerator
SWMM_OUT_SUBCATCH_RAINFALL	Rainfall rate.
SWMM_OUT_SUBCATCH_SNOW_DEPTH	Snow depth.
SWMM_OUT_SUBCATCH_EVAP	Evaporation loss.
SWMM_OUT_SUBCATCH_INFIL	Infiltration loss.
SWMM_OUT_SUBCATCH_RUNOFF	Runoff flow rate.
SWMM_OUT_SUBCATCH_GW_FLOW	Groundwater flow.
SWMM_OUT_SUBCATCH_GW_ELEV	Groundwater table elevation.
SWMM_OUT_SUBCATCH_SOIL_MOIST	Soil moisture content.
SWMM_OUT_SUBCATCH_POLLUT_BASE	First pollutant concentration slot.
SWMM_OUT_SUBCATCH_SNOW_SWE	m, including retained liquid.
SWMM_OUT_SUBCATCH_SNOW_ENERGY	kJ/m2, including bare-ground energy.
SWMM_OUT_SUBCATCH_SNOW_SURFACE_TEMP	degC, snow/ground surface.
SWMM_OUT_SUBCATCH_SNOW_BULK_TEMP	degC.
SWMM_OUT_SUBCATCH_SNOW_ALBEDO	fraction.
SWMM_OUT_SUBCATCH_SNOW_COVER	fraction.
SWMM_OUT_SUBCATCH_SNOW_MELT	m/s.
SWMM_OUT_SUBCATCH_SNOW_INPUT	m/s, liquid reaching surface.
SWMM_OUT_SUBCATCH_SNOW_SUBLIMATION	m/s, negative is condensation.
SWMM_OUT_SUBCATCH_SNOW_TIME	accepted seconds since run start.

SWMM_OutSystemVar

enum SWMM_OutSystemVar

System-wide result variable indices.

15 system-wide summary results stored per output period, in the slot order the .out writer uses (legacy SWMM 5 SysResults order).

Enumerator
SWMM_OUT_SYS_TEMPERATURE	Air temperature.
SWMM_OUT_SYS_RAINFALL	Average rainfall.
SWMM_OUT_SYS_SNOW_DEPTH	Average snow depth.
SWMM_OUT_SYS_INFIL	Average infiltration.
SWMM_OUT_SYS_RUNOFF	Total runoff flow.
SWMM_OUT_SYS_DW_INFLOW	Dry weather inflow.
SWMM_OUT_SYS_GW_INFLOW	Groundwater inflow.
SWMM_OUT_SYS_RDII_INFLOW	RDII inflow.
SWMM_OUT_SYS_EXT_INFLOW	External (direct) inflow.
SWMM_OUT_SYS_TOTAL_INFLOW	Total lateral inflow (runoff + DWF + GW + RDII + external).
SWMM_OUT_SYS_FLOODING	Total flooding.
SWMM_OUT_SYS_OUTFLOW	Total outfall outflow.
SWMM_OUT_SYS_STORAGE	Total storage volume.
SWMM_OUT_SYS_EVAP	Evaporation rate.
SWMM_OUT_SYS_PET	Potential evapotranspiration.
SWMM_OUT_SYS_LAT_INFLOW	Deprecated alias of TOTAL_INFLOW.

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.