errormanager.h File Reference

Header file for SWMM output API error handling. More...

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

Go to the source code of this file.

Classes
struct	error_s
	Structure for managing errors. More...

Macros
#define	ERR_MAXMSG   256
	Maximum length of error message.

Typedefs
typedef void(*	p_msg_lookup) (int errorcode, char *message, int length)
	Describe a borrowed lookup callback used to format one error code.
typedef struct error_s	error_handle_t

Enumerations
enum	OutputErrorTypes {   ERR411 = 411 ,   ERR421 = 421 ,   ERR422 = 422 ,   ERR423 = 423 ,   ERR424 = 424 ,   ERR434 = 434 ,   ERR435 = 435 ,   ERR436 = 436 ,   ERR440 = 440 }
	Error codes. More...
enum	OutputWarningTypes { WARN10 = 10 }
	Warning codes. More...

Functions
error_handle_t *	new_error_manager (p_msg_lookup message_lookup)
	Allocate a zero-status error manager and retain its lookup callback.
void	dst_error_manager (error_handle_t *error_handle)
	Release an error manager allocation.
int	set_error (error_handle_t *error_handle, int errorcode)
	Record a nonzero error without clearing a previous status on success.
char *	check_error (error_handle_t *error_handle)
	Allocate a copy of the current stored error message.
void	clear_error (error_handle_t *error_handle)
	Explicitly clear the sticky error status.

Detailed Description

Header file for SWMM output API error handling.

Author

Michael E. Tryby (US EPA - ORD/NRMRL)

Date

Created: 2017-08-25

Last edited: 2024-10-17

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com (OpenSWMM maintenance and extensions)

Copyright

Copyright (c) 2026 Caleb Buahin. OpenSWMM contributions only; original EPA SWMM credits are retained.

License

Apache-2.0 for OpenSWMM contributions; original EPA SWMM provenance is retained.

Macro Definition Documentation

ERR_MAXMSG

#define ERR_MAXMSG   256

Maximum length of error message.

Typedef Documentation

error_handle_t

typedef struct error_s error_handle_t

p_msg_lookup

typedef void(* p_msg_lookup) (int errorcode, char *message, int length)

Describe a borrowed lookup callback used to format one error code.

Invoked synchronously by check_error. The manager retains the callback pointer until destruction, so its code must remain loaded for that lifetime.

Parameters

[in]	errorcode	Stored nonzero warning/error code to translate.
[out]	message	Writable caller-owned buffer of length bytes; write a bounded null-terminated message.
[in]	length	Positive writable buffer capacity in bytes, including its terminator.

Enumeration Type Documentation

OutputErrorTypes

enum OutputErrorTypes

Error codes.

Enumerator
ERR411	Error 411: memory allocation failure.
ERR421	Error 421: invalid parameter code.
ERR422	Error 422: reporting period index out of range.
ERR423	Error 423: element index out of range.
ERR424	Error 424: no memory allocated for results.
ERR434	Error 434: unable to open binary output file.
ERR435	Error 435: invalid file - not created by SWMM.
ERR436	Error 436: invalid file - contains no results.
ERR440	rror 440: an unspecified error has occurred

OutputWarningTypes

enum OutputWarningTypes

Warning codes.

Enumerator
WARN10	Model run issued warnings.

Function Documentation

check_error()

char * check_error

(

error_handle_t *

error_handle

)

Allocate a copy of the current stored error message.

Invokes lookup synchronously only when allocation succeeds. Does not clear status or retain the message; each call creates a separate allocation.

Parameters

[in]

error_handle

Live non-null manager with a callable lookup for nonzero status; manager is read only.

Returns

Owned zero-initialized ERR_MAXMSG-byte message allocation, or null for zero status or allocation failure; free the returned allocation.

See also

Declaration contract for check_error().

clear_error()

void clear_error

(

error_handle_t *

error_handle

)

Explicitly clear the sticky error status.

Parameters

[in,out]

error_handle

Live non-null manager; error_status becomes zero, callback remains unchanged.

See also

Declaration contract for clear_error().

dst_error_manager()

void dst_error_manager

(

error_handle_t *

error_handle

)

Release an error manager allocation.

No message allocations are owned by the manager. Caller remains responsible for strings returned by check_error; the argument itself is not cleared.

Parameters

[in]

error_handle

Owned manager to destroy, or null (free accepts null); all aliases become invalid.

See also

Declaration contract for dst_error_manager().

new_error_manager()

error_handle_t * new_error_manager

(

p_msg_lookup

message_lookup

)

Allocate a zero-status error manager and retain its lookup callback.

Parameters

[in]

message_lookup

Callback kept in the manager; must remain callable for its lifetime and be non-null before checking a nonzero error.

Returns

Owned calloc-initialized manager, released with dst_error_manager. Allocation failure is not safely handled: the implementation dereferences the allocation immediately.

See also

Declaration contract for new_error_manager().

set_error()

int set_error	(	error_handle_t *	error_handle,
		int	errorcode )

Record a nonzero error without clearing a previous status on success.

Parameters

[in,out]	error_handle	Live manager; non-null is required only when errorcode is nonzero.
[in]	errorcode	Nonzero status replaces the stored code; zero leaves the previous code intact.

Returns

The supplied errorcode unchanged, including zero.

See also

Declaration contract for set_error().