Hot start file management — transparent C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_hotstart.h:

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

Macros
#define	OPENSWMM_HOTSTART_MAGIC "OPENSWMM_HS_V1\0"
	Magic string written at the start of every OPENSWMM_HS_V1 file.

#define	OPENSWMM_HOTSTART_VERSION 1
	Base format version. Writers select compatible extensions for the configured model state, including Richards cell water/material identity, full-engine checkpoints, snow and groundwater transport state. The macro identifies the base format, not the highest extension version.

#define	SWMM_HOTSTART_FORMAT_AUTO 0
	File formats a `SAVE HOTSTART` entry can write.

#define	SWMM_HOTSTART_FORMAT_LEGACY 1

#define	SWMM_HOTSTART_FORMAT_NATIVE 2

#define	SWMM_HOTSTART_OMITS_WATER_AGE 0x1
	Bits of swmm_hotstart_legacy_omits().

#define	SWMM_HOTSTART_OMITS_REACTION_SPECIES 0x2

#define	SWMM_HOTSTART_OMITS_AQUIFER 0x4

#define	SWMM_HOTSTART_OMITS_NODE_LIDS 0x8

Typedefs
typedef void *	SWMM_HotStart
	Opaque handle to an open hot start file.

Functions
SWMM_ENGINE_API int	swmm_hotstart_saves_count (SWMM_Engine engine, int *count)
	Count scheduled SAVE HOTSTART authoring entries.

SWMM_ENGINE_API int	swmm_hotstart_saves_get_path (SWMM_Engine engine, int idx, char *buf, int buflen)
	Copy the authored path of one scheduled save entry.

SWMM_ENGINE_API int	swmm_hotstart_saves_get_datetime (SWMM_Engine engine, int idx, double *datetime)
	Read the scheduled calendar date of one save entry.

SWMM_ENGINE_API int	swmm_hotstart_saves_set_path (SWMM_Engine engine, int idx, const char *path)
	Replace a scheduled save path without removing its row.

SWMM_ENGINE_API int	swmm_hotstart_saves_set_datetime (SWMM_Engine engine, int idx, double datetime)
	Assign a scheduled save calendar date directly.

SWMM_ENGINE_API int	swmm_hotstart_saves_get_format (SWMM_Engine engine, int idx, int *format)
	Read the authored format selector of one scheduled save.

SWMM_ENGINE_API int	swmm_hotstart_saves_set_format (SWMM_Engine engine, int idx, int format)
	Select the authored format of an existing scheduled save.

SWMM_ENGINE_API int	swmm_hotstart_legacy_omits (SWMM_Engine engine, int *flags)
	Report selected model features that legacy routing hotstarts cannot retain.

SWMM_ENGINE_API int	swmm_hotstart_saves_add (SWMM_Engine engine, const char *path, double datetime)
	Append an AUTO-format scheduled save authoring entry.

SWMM_ENGINE_API int	swmm_hotstart_saves_remove (SWMM_Engine engine, int idx)
	Remove a scheduled save entry and shift later indices down.

SWMM_ENGINE_API int	swmm_hotstart_saves_clear (SWMM_Engine engine)
	Remove all scheduled save authoring entries.

SWMM_ENGINE_API int	swmm_hotstart_save (SWMM_Engine engine, const char *path)
	Write current simulation state through the native checkpoint or state-IO path.

SWMM_ENGINE_API const char *	swmm_hotstart_last_io_error (void)
	Borrow the built-in hot-start reader/writer diagnostic for this thread.

SWMM_ENGINE_API int	swmm_hotstart_open (const char path, SWMM_HotStart hs)
	Load a native OPENSWMM hot-start file into an independent handle.

SWMM_ENGINE_API int	swmm_hotstart_apply (SWMM_Engine engine, SWMM_HotStart hs)
	Apply record state or queue a complete restart on an initialized engine.

SWMM_ENGINE_API int	swmm_hotstart_set_node_depth (SWMM_HotStart hs, const char *node_id, double depth)
	Edit one stored node depth record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_set_node_head (SWMM_HotStart hs, const char *node_id, double head)
	Edit one stored node head record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_set_link_flow (SWMM_HotStart hs, const char *link_id, double flow)
	Edit one stored link flow record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_set_link_depth (SWMM_HotStart hs, const char *link_id, double depth)
	Edit one stored link depth record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_set_subcatch_runoff (SWMM_HotStart hs, const char *subcatch_id, double runoff)
	Edit one stored subcatchment runoff record before application/write-back.

SWMM_ENGINE_API int	swmm_hotstart_get_sim_time (SWMM_HotStart hs, double *sim_time)
	Read the saved elapsed simulation time.

SWMM_ENGINE_API int	swmm_hotstart_get_start_date (SWMM_HotStart hs, double *start_date)
	Read the saving run start calendar date.

SWMM_ENGINE_API int	swmm_hotstart_get_crs (SWMM_HotStart hs, char *buf, int buflen)
	Copy the hot-start header CRS string.

SWMM_ENGINE_API int	swmm_hotstart_node_count (SWMM_HotStart hs)
	Count stored node records in a hot-start handle.

SWMM_ENGINE_API int	swmm_hotstart_link_count (SWMM_HotStart hs)
	Count stored link records in a hot-start handle.

SWMM_ENGINE_API int	swmm_hotstart_warning_count (SWMM_HotStart hs)
	Count warnings retained by the hot-start handle.

SWMM_ENGINE_API const char *	swmm_hotstart_warning (SWMM_HotStart hs, int index)
	Borrow one retained hot-start warning.

SWMM_ENGINE_API int	swmm_hotstart_close (SWMM_HotStart hs)
	Flush dirty record edits and destroy a hot-start handle.

Detailed Description

Hot start file management — transparent C API.

Hot start files capture the hydraulic and water quality state of a SWMM simulation so it can be resumed later without running a warm-up period from dry-weather initial conditions.

The new hot start format (OPENSWMM_HS_V1) extends the legacy SWMM binary hot start format with:

An object UUID map for robust missing-object detection
CRS string for spatial consistency checking
User flag values
A CRC32 integrity checksum

Workflow

// ---- Save a hot start ----
SWMM_Engine e = swmm_engine_create();
swmm_engine_open(e, "warmup.inp", "warmup.rpt", "warmup.out", NULL);
swmm_engine_initialize(e);
swmm_engine_start(e, 0);
double t = 0.0;
while (swmm_engine_step(e, &t) == SWMM_OK && t > 0.0) {}
swmm_hotstart_save(e, "warmup.hs");
swmm_engine_end(e);
swmm_engine_close(e);
swmm_engine_destroy(e);
 
// ---- Apply a hot start ----
SWMM_HotStart hs = NULL;
swmm_hotstart_open("warmup.hs", &hs);
 
SWMM_Engine e2 = swmm_engine_create();
swmm_engine_open(e2, "storm.inp", "storm.rpt", "storm.out", NULL);
swmm_engine_initialize(e2);
swmm_hotstart_apply(e2, hs);   // warnings issued for missing objects
 
int nwarn = swmm_hotstart_warning_count(hs);
for (int i = 0; i < nwarn; i++) {
    printf("Warning: %s\n", swmm_hotstart_warning(hs, i));
}
 
swmm_hotstart_close(hs);

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

◆ OPENSWMM_HOTSTART_MAGIC

#define OPENSWMM_HOTSTART_MAGIC "OPENSWMM_HS_V1\0"

Magic string written at the start of every OPENSWMM_HS_V1 file.

◆ OPENSWMM_HOTSTART_VERSION

#define OPENSWMM_HOTSTART_VERSION 1

Base format version. Writers select compatible extensions for the configured model state, including Richards cell water/material identity, full-engine checkpoints, snow and groundwater transport state. The macro identifies the base format, not the highest extension version.

◆ SWMM_HOTSTART_FORMAT_AUTO

#define SWMM_HOTSTART_FORMAT_AUTO 0

File formats a SAVE HOTSTART entry can write.

In the .inp the format is an optional keyword after the path and optional datetime: SAVE HOTSTART "f.hsf" [date time] LEGACY|NATIVE. A row without one is AUTO, the behaviour of every earlier file: the legacy SWMM5 .hsf routing format, or the native format when the model has node LIDs. USE HOTSTART reads either; it goes by the file's own stamp. NATIVE also carries what the legacy format has no room for (see swmm_hotstart_legacy_omits()); legacy SWMM 5 cannot read it. Legacy, or native with node LIDs

◆ SWMM_HOTSTART_FORMAT_LEGACY

#define SWMM_HOTSTART_FORMAT_LEGACY 1

EPA SWMM5 .hsf

◆ SWMM_HOTSTART_FORMAT_NATIVE

#define SWMM_HOTSTART_FORMAT_NATIVE 2

OPENSWMM_HS_V1

◆ SWMM_HOTSTART_OMITS_AQUIFER

#define SWMM_HOTSTART_OMITS_AQUIFER 0x4

2D aquifer rows

◆ SWMM_HOTSTART_OMITS_NODE_LIDS

#define SWMM_HOTSTART_OMITS_NODE_LIDS 0x8

LID units at storage nodes

◆ SWMM_HOTSTART_OMITS_REACTION_SPECIES

#define SWMM_HOTSTART_OMITS_REACTION_SPECIES 0x2

reactions-component species

◆ SWMM_HOTSTART_OMITS_WATER_AGE

#define SWMM_HOTSTART_OMITS_WATER_AGE 0x1

Bits of swmm_hotstart_legacy_omits().

[OPTIONS] WATER_AGE YES

Typedef Documentation

◆ SWMM_HotStart

typedef void* SWMM_HotStart

Opaque handle to an open hot start file.

Function Documentation

◆ swmm_hotstart_apply()

SWMM_ENGINE_API int swmm_hotstart_apply	(	SWMM_Engine	engine,
		SWMM_HotStart	hs )

Apply record state or queue a complete restart on an initialized engine.

Record-based application matches string IDs, keeps missing target objects unchanged, records missing source objects as warnings and reopens mass-balance initial storage on success. This wrapper passes a no-op warning sink; use swmm_hotstart_warning_count()/warning() rather than assuming a registered engine warning callback fires. Full-engine checkpoint payloads are queued here and restored during subsequent engine start, after owners initialize; queue acceptance is not completed restoration. Record application is not promised atomic on every extension failure.

Parameters

[in]	engine	Non-null INITIALIZED engine whose model and restart owners support the file profile.
[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.

Returns: SWMM_OK when records apply or a full-engine restart is queued; SWMM_ERR_BADHANDLE for a null handle, SWMM_ERR_LIFECYCLE outside INITIALIZED, or SWMM_ERR_HOTSTART for a refused/incompatible restart.

Here is the call graph for this function:

◆ swmm_hotstart_close()

SWMM_ENGINE_API int swmm_hotstart_close ( SWMM_HotStart hs )

Flush dirty record edits and destroy a hot-start handle.

Unmodified handles do not rewrite the file. Setters mark their records dirty; close attempts to persist those changes to the original path before freeing all storage.

Parameters

[in] hs Caller-owned live hot-start handle, or NULL for a successful no-op. The handle is destroyed even if flush fails; do not retry close or use it afterward.

Returns: SWMM_OK after close/no-op; SWMM_ERR_IO when dirty write-back fails.

Here is the call graph for this function:

◆ swmm_hotstart_get_crs()

SWMM_ENGINE_API int swmm_hotstart_get_crs	(	SWMM_HotStart	hs,
		char *	buf,
		int	buflen )

Copy the hot-start header CRS string.

Returns stored metadata without validating coordinates or compatibility with another model.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[out]	buf	Non-null caller-owned destination; success NUL-terminates and silently truncates to buflen-1 bytes. An absent CRS is an empty string.
[in]	buflen	Positive byte capacity including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

◆ swmm_hotstart_get_sim_time()

SWMM_ENGINE_API int swmm_hotstart_get_sim_time	(	SWMM_HotStart	hs,
		double *	sim_time )

Read the saved elapsed simulation time.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[out]	sim_time	Non-null destination for elapsed seconds since the saving run start calendar date.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

◆ swmm_hotstart_get_start_date()

SWMM_ENGINE_API int swmm_hotstart_get_start_date	(	SWMM_HotStart	hs,
		double *	start_date )

Read the saving run start calendar date.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[out]	start_date	Non-null destination for OADate/SWMM DateTime decimal days since 1899-12-30; no timezone conversion.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

◆ swmm_hotstart_last_io_error()

SWMM_ENGINE_API const char * swmm_hotstart_last_io_error ( void )

Borrow the built-in hot-start reader/writer diagnostic for this thread.

This diagnostic belongs to HotStartManager, not the independent checkpoint diagnostic or every possible state-IO plugin.

Returns: NUL-terminated thread-local string, empty when no detailed IO diagnostic is available. Do not free it; copy before another hot-start IO call on this thread.

Here is the call graph for this function:

◆ swmm_hotstart_legacy_omits()

SWMM_ENGINE_API int swmm_hotstart_legacy_omits	(	SWMM_Engine	engine,
		int *	flags )

Report selected model features that legacy routing hotstarts cannot retain.

Reads parsed authoring before initialization and does not write or validate a complete restart. The mask is not an exhaustive restart-completeness certificate: legacy/native formats and qualified full-engine checkpoints retain different state.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[out]	flags	Non-null OR-mask of SWMM_HOTSTART_OMITS_WATER_AGE, REACTION_SPECIES, AQUIFER and NODE_LIDS; zero when none of these features are configured.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

Here is the call graph for this function:

◆ swmm_hotstart_link_count()

SWMM_ENGINE_API int swmm_hotstart_link_count ( SWMM_HotStart hs )

Count stored link records in a hot-start handle.

Parameters

[in] hs Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.

Returns: Stored link-record count, or -1 for null hs.

◆ swmm_hotstart_node_count()

SWMM_ENGINE_API int swmm_hotstart_node_count ( SWMM_HotStart hs )

Count stored node records in a hot-start handle.

A full-engine checkpoint payload need not expose its embedded state as editable record rows.

Parameters

[in] hs Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.

Returns: Stored node-record count, or -1 for null hs.

◆ swmm_hotstart_open()

SWMM_ENGINE_API int swmm_hotstart_open	(	const char *	path,
		SWMM_HotStart *	hs )

Load a native OPENSWMM hot-start file into an independent handle.

Reads the file into owned in-memory records and restart extensions; no engine handle is retained. Release with swmm_hotstart_close(). This reader is distinct from the model-bound legacy USE HOTSTART loader.

Parameters

[in]	path	Non-null, nonempty NUL-terminated native hot-start path; borrowed for the call.
[out]	hs	Non-null output slot. Set to NULL before path/read validation, then to a newly allocated caller-owned handle on success. A previous handle in this variable is not freed.

Returns: SWMM_OK; SWMM_ERR_BADPARAM for null output or null/empty path; SWMM_ERR_HOTSTART when native magic/version/checksum/content validation fails.

Here is the call graph for this function:

◆ swmm_hotstart_save()

SWMM_ENGINE_API int swmm_hotstart_save	(	SWMM_Engine	engine,
		const char *	path )

Write current simulation state through the native checkpoint or state-IO path.

A heat model with a qualified attached full-engine checkpoint uses its accepted native restart. Otherwise state-IO plugins are tried in order until one succeeds, with a built-in record-format fallback when no state plugin is registered. Record files match objects by ID; full-engine checkpoints require matching model/provider/runtime state and are restored at a subsequent start. This is not the exclusive new-path checkpoint API and does not promise no-replace publication.

Parameters

[in]	engine	Non-null engine in RUNNING or ENDED; exclusive access is required.
[in]	path	Non-null, nonempty NUL-terminated destination path, borrowed for the synchronous call.

Returns: SWMM_OK on successful write; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for null/empty path, SWMM_ERR_LIFECYCLE outside RUNNING/ENDED, or SWMM_ERR_HOTSTART on checkpoint/state-writer failure.

Here is the call graph for this function:

◆ swmm_hotstart_saves_add()

SWMM_ENGINE_API int swmm_hotstart_saves_add	(	SWMM_Engine	engine,
		const char *	path,
		double	datetime )

Append an AUTO-format scheduled save authoring entry.

Appending does not validate collisions or file writability and does not emit the file immediately.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[in]	path	Non-null NUL-terminated path to copy; empty creates a placeholder row.
[in]	datetime	SWMM DateTime decimal days since 1899-12-30; 0 means run end. Stored without finite/date validation.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

◆ swmm_hotstart_saves_clear()

SWMM_ENGINE_API int swmm_hotstart_saves_clear ( SWMM_Engine engine )

Remove all scheduled save authoring entries.

Does not delete any existing files already written by earlier entries.

Parameters

[in] engine Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_hotstart_saves_count()

SWMM_ENGINE_API int swmm_hotstart_saves_count	(	SWMM_Engine	engine,
		int *	count )

Count scheduled SAVE HOTSTART authoring entries.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[out]	count	Non-null destination for the stored entry count.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADPARAM for an invalid required argument or slot.

◆ swmm_hotstart_saves_get_datetime()

SWMM_ENGINE_API int swmm_hotstart_saves_get_datetime	(	SWMM_Engine	engine,
		int	idx,
		double *	datetime )

Read the scheduled calendar date of one save entry.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[in]	idx	Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX.
[out]	datetime	Non-null destination for SWMM DateTime decimal days since 1899-12-30; 0 denotes end of run.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle, SWMM_ERR_BADINDEX for an invalid slot or SWMM_ERR_BADPARAM for an invalid required argument.

◆ swmm_hotstart_saves_get_format()

SWMM_ENGINE_API int swmm_hotstart_saves_get_format	(	SWMM_Engine	engine,
		int	idx,
		int *	format )

Read the authored format selector of one scheduled save.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[in]	idx	Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX.
[out]	format	Non-null destination for SWMM_HOTSTART_FORMAT_AUTO, LEGACY or NATIVE.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle, SWMM_ERR_BADINDEX for an invalid slot or SWMM_ERR_BADPARAM for an invalid required argument.

◆ swmm_hotstart_saves_get_path()

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

Copy the authored path of one scheduled save entry.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[in]	idx	Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX.
[out]	buf	Non-null caller-owned destination, NUL-terminated and silently truncated to buflen-1 bytes.
[in]	buflen	Positive buffer capacity in bytes, including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle, SWMM_ERR_BADINDEX for an invalid slot or SWMM_ERR_BADPARAM for an invalid required argument.

◆ swmm_hotstart_saves_remove()

SWMM_ENGINE_API int swmm_hotstart_saves_remove	(	SWMM_Engine	engine,
		int	idx )

Remove a scheduled save entry and shift later indices down.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[in]	idx	Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADINDEX for an invalid slot.

◆ swmm_hotstart_saves_set_datetime()

SWMM_ENGINE_API int swmm_hotstart_saves_set_datetime	(	SWMM_Engine	engine,
		int	idx,
		double	datetime )

Assign a scheduled save calendar date directly.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[in]	idx	Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX.
[in]	datetime	SWMM DateTime decimal days since 1899-12-30; 0 saves at run end. No finite/range/order validation is performed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle or SWMM_ERR_BADINDEX for an invalid slot.

◆ swmm_hotstart_saves_set_format()

SWMM_ENGINE_API int swmm_hotstart_saves_set_format	(	SWMM_Engine	engine,
		int	idx,
		int	format )

Select the authored format of an existing scheduled save.

This setter stores a preference; actual restart-profile support is evaluated when saving.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[in]	idx	Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX.
[in]	format	SWMM_HOTSTART_FORMAT_AUTO (0), LEGACY (1) or NATIVE (2). Other values are refused.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle, SWMM_ERR_BADINDEX for an invalid slot or SWMM_ERR_BADPARAM for an invalid required argument.

◆ swmm_hotstart_saves_set_path()

SWMM_ENGINE_API int swmm_hotstart_saves_set_path	(	SWMM_Engine	engine,
		int	idx,
		const char *	path )

Replace a scheduled save path without removing its row.

Unlike the legacy slot-0 swmm_files_set() sugar, an empty path with zero datetime does not auto-remove this entry. Use remove/clear explicitly.

Parameters

[in]	engine	Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately.
[in]	idx	Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX.
[in]	path	Non-null NUL-terminated path to copy; empty is permitted and clears the token/cached absolute path.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null handle, SWMM_ERR_BADINDEX for an invalid slot or SWMM_ERR_BADPARAM for an invalid required argument.

◆ swmm_hotstart_set_link_depth()

SWMM_ENGINE_API int swmm_hotstart_set_link_depth	(	SWMM_HotStart	hs,
		const char *	link_id,
		double	depth )

Edit one stored link depth record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	link_id	Non-null NUL-terminated link ID, matched exactly/case-sensitively against stored records.
[in]	depth	New depth in internal feet (ft); assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_set_link_flow()

SWMM_ENGINE_API int swmm_hotstart_set_link_flow	(	SWMM_HotStart	hs,
		const char *	link_id,
		double	flow )

Edit one stored link flow record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	link_id	Non-null NUL-terminated link ID, matched exactly/case-sensitively against stored records.
[in]	flow	New flow in internal cubic feet per second (ft3/s), signed in stored link orientation; assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_set_node_depth()

SWMM_ENGINE_API int swmm_hotstart_set_node_depth	(	SWMM_HotStart	hs,
		const char *	node_id,
		double	depth )

Edit one stored node depth record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	node_id	Non-null NUL-terminated node ID, matched exactly/case-sensitively against stored records.
[in]	depth	New depth in internal feet (ft), regardless of project display units; assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_set_node_head()

SWMM_ENGINE_API int swmm_hotstart_set_node_head	(	SWMM_HotStart	hs,
		const char *	node_id,
		double	head )

Edit one stored node head record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	node_id	Non-null NUL-terminated node ID, matched exactly/case-sensitively against stored records.
[in]	head	New head in internal datum feet (ft); assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_set_subcatch_runoff()

SWMM_ENGINE_API int swmm_hotstart_set_subcatch_runoff	(	SWMM_HotStart	hs,
		const char *	subcatch_id,
		double	runoff )

Edit one stored subcatchment runoff record before application/write-back.

Marks the record file dirty for swmm_hotstart_close() write-back. Does not modify an already running engine or recalculate related fields; a full-engine payload without this record returns BADPARAM.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	subcatch_id	Non-null NUL-terminated subcatchment ID, matched exactly/case-sensitively against stored records.
[in]	runoff	New runoff in internal cubic feet per second (ft3/s); assigned without finite/range validation.

Returns: SWMM_OK when a matching record is modified; SWMM_ERR_BADHANDLE for null hs or SWMM_ERR_BADPARAM for null/unmatched ID.

◆ swmm_hotstart_warning()

SWMM_ENGINE_API const char * swmm_hotstart_warning	(	SWMM_HotStart	hs,
		int	index )

Borrow one retained hot-start warning.

Parameters

[in]	hs	Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.
[in]	index	Zero-based index in [0,swmm_hotstart_warning_count(hs)).

Returns: Handle-owned NUL-terminated warning string, or NULL for null hs/out-of-range index. Never free it; copy before applying again or closing hs.

◆ swmm_hotstart_warning_count()

SWMM_ENGINE_API int swmm_hotstart_warning_count ( SWMM_HotStart hs )

Count warnings retained by the hot-start handle.

Record-based apply clears/repopulates this list; it can contain missing-object and restart-profile diagnostics. The full-checkpoint queue path does not promise to refresh this list.

Parameters

[in] hs Non-null live hot-start handle returned by swmm_hotstart_open(); caller retains ownership until close.

Returns: Warning count, or 0 for null hs.

Macros

Typedefs

Functions

Detailed Description

Workflow

Macro Definition Documentation

◆ OPENSWMM_HOTSTART_MAGIC

◆ OPENSWMM_HOTSTART_VERSION

◆ SWMM_HOTSTART_FORMAT_AUTO

◆ SWMM_HOTSTART_FORMAT_LEGACY

◆ SWMM_HOTSTART_FORMAT_NATIVE

◆ SWMM_HOTSTART_OMITS_AQUIFER

◆ SWMM_HOTSTART_OMITS_NODE_LIDS

◆ SWMM_HOTSTART_OMITS_REACTION_SPECIES

◆ SWMM_HOTSTART_OMITS_WATER_AGE

Typedef Documentation

◆ SWMM_HotStart

Function Documentation

◆ swmm_hotstart_apply()

◆ swmm_hotstart_close()

◆ swmm_hotstart_get_crs()

◆ swmm_hotstart_get_sim_time()

◆ swmm_hotstart_get_start_date()

◆ swmm_hotstart_last_io_error()

◆ swmm_hotstart_legacy_omits()

◆ swmm_hotstart_link_count()

◆ swmm_hotstart_node_count()

◆ swmm_hotstart_open()

◆ swmm_hotstart_save()

◆ swmm_hotstart_saves_add()

◆ swmm_hotstart_saves_clear()

◆ swmm_hotstart_saves_count()

◆ swmm_hotstart_saves_get_datetime()

◆ swmm_hotstart_saves_get_format()

◆ swmm_hotstart_saves_get_path()

◆ swmm_hotstart_saves_remove()

◆ swmm_hotstart_saves_set_datetime()

◆ swmm_hotstart_saves_set_format()

◆ swmm_hotstart_saves_set_path()

◆ swmm_hotstart_set_link_depth()

◆ swmm_hotstart_set_link_flow()

◆ swmm_hotstart_set_node_depth()

◆ swmm_hotstart_set_node_head()

◆ swmm_hotstart_set_subcatch_runoff()

◆ swmm_hotstart_warning()

◆ swmm_hotstart_warning_count()