Functions
int DLLEXPORT	EN_writeline (EN_Project ph, const char *line)
	Writes a line of text to a project's report file.

int DLLEXPORT	EN_report (EN_Project ph)
	Writes simulation results in a tabular format to a project's report file.

int DLLEXPORT	EN_copyreport (EN_Project ph, const char *filename)
	Copies the current contents of a project's report file to another file.

int DLLEXPORT	EN_clearreport (EN_Project ph)
	Clears the contents of a project's report file.

int DLLEXPORT	EN_resetreport (EN_Project ph)
	Resets a project's report options to their default values.

int DLLEXPORT	EN_setreport (EN_Project ph, const char *format)
	Processes a reporting format command.

int DLLEXPORT	EN_setstatusreport (EN_Project ph, int level)
	Sets the level of hydraulic status reporting.

int DLLEXPORT	EN_getversion (int *out_version)
	Retrieves the toolkit API version number.

int DLLEXPORT	EN_geterror (int errcode, char *out_errmsg, int maxLen)
	Returns the text of an error message generated by an error code.

int DLLEXPORT	EN_getstatistic (EN_Project ph, int type, double *out_value)
	Retrieves a particular simulation statistic.

int DLLEXPORT	EN_getresultindex (EN_Project ph, int type, int index, int *out_value)
	Retrieves the order in which a node or link appears in an output file.

int DLLEXPORT	EN_timetonextevent (EN_Project ph, int eventType, long duration, int *elementIndex)
	Gets information about when the next hydraulic time step occurs.

int DLLEXPORT	EN_setreportcallback (EN_Project ph, void(callback)(void userData, void EN_projectHandle, const char ))
	Sets a user-supplied callback function for reporting.

int DLLEXPORT	EN_setreportcallbackuserdata (EN_Project ph, void *userData)
	Sets a pointer to a client-side data object.

Overview

These functions are used to report simulation results.

Function Documentation

◆ EN_clearreport()

int DLLEXPORT EN_clearreport ( EN_Project ph )

Clears the contents of a project's report file.

Parameters

ph	an EPANET project handle.

Returns: an error code.

◆ EN_copyreport()

int DLLEXPORT EN_copyreport	(	EN_Project	ph,
		const char *	filename )

Copies the current contents of a project's report file to another file.

Parameters

ph	an EPANET project handle.
filename	the full path name of the destination file.

Returns: an error code.

This function allows toolkit clients to retrieve the contents of a project's report file while the project is still open.

◆ EN_geterror()

int DLLEXPORT EN_geterror	(	int	errcode,
		char *	out_errmsg,
		int	maxLen )

Returns the text of an error message generated by an error code.

Parameters

	errcode	an error code.
[out]	out_errmsg	the error message generated by the error code
	maxLen	maximum number of characters that errmsg can hold

Returns: an error code

Error message strings should be greater than EN_MAXMSG characters in length.

◆ EN_getresultindex()

int DLLEXPORT EN_getresultindex	(	EN_Project	ph,
		int	type,
		int	index,
		int *	out_value )

Retrieves the order in which a node or link appears in an output file.

Parameters

	ph	an EPANET project handle.
	type	a type of element (either EN_NODE or EN_LINK).
	index	the element's current index (starting from 1).
[out]	out_value	the order in which the element's results were written to file.

Returns: an error code.

If the element does not appear in the file then its result index is 0.

This function can be used to correctly retrieve results from an EPANET binary output file after the order of nodes or links in a network's database has been changed due to editing operations.

◆ EN_getstatistic()

int DLLEXPORT EN_getstatistic	(	EN_Project	ph,
		int	type,
		double *	out_value )

Retrieves a particular simulation statistic.

Parameters

	ph	an EPANET project handle.
	type	the type of statistic to retrieve (see EN_AnalysisStatistic).
[out]	out_value	the value of the statistic.

Returns: an error code

◆ EN_getversion()

int DLLEXPORT EN_getversion ( int * out_version )

Retrieves the toolkit API version number.

Parameters

[out] out_version the version of the OWA-EPANET toolkit.

Returns: an error code.

The version number is to be interpreted with implied decimals, i.e., "20100" == "2(.)01(.)00"

◆ EN_report()

int DLLEXPORT EN_report ( EN_Project ph )

Writes simulation results in a tabular format to a project's report file.

Parameters

ph	an EPANET project handle.

Returns: an error code

Either a full hydraulic analysis or full hydraulic and water quality analysis must have been run, with results saved to file, before EN_report is called. In the former case, EN_saveH must also be called first to transfer results from the project's intermediate hydraulics file to its output file.

The format of the report is controlled by commands issued with EN_setreport.

◆ EN_resetreport()

int DLLEXPORT EN_resetreport ( EN_Project ph )

Resets a project's report options to their default values.

Parameters

ph	an EPANET project handle.

Returns: an error code

After calling this function the default reporting options are in effect. These are:

no status report
no energy report
no nodes reported on
no links reported on
node variables reported to 2 decimal places
link variables reported to 2 decimal places (3 for friction factor)
node variables reported are elevation, head, pressure, and quality
link variables reported are flow, velocity, and head loss.

◆ EN_setreport()

int DLLEXPORT EN_setreport	(	EN_Project	ph,
		const char *	format )

Processes a reporting format command.

Parameters

ph	an EPANET project handle.
format	a report formatting command.

Returns: an error code

Acceptable report formatting commands are described in the [REPORT] section of the Input File topic.

Formatted results of a simulation can be written to a project's report file using the EN_report function.

◆ EN_setreportcallback()

int DLLEXPORT EN_setreportcallback	(	EN_Project	ph,
		void(*	callback )(void userData, void EN_projectHandle, const char *) )

Sets a user-supplied callback function for reporting.

Parameters

ph	an EPANET project handle.
callback	a function pointer used for reporting.

Returns: an error code.

The callback function replaces the project's report file as the destination for all output written by EN_writeline. It must have the following signature:

void(void *userData, void *EN_projectHandle p, const char* s)

The userData parameter is a pointer to a client-side data object. It can be changed using the EN_setreportcallbackuserdata function. The parameter s is a placeholder for the EPANET-generated string that was passed into EN_writeline. Setting the callback function to NULL reverts to having EN_writeline use the project's report file.

◆ EN_setreportcallbackuserdata()

int DLLEXPORT EN_setreportcallbackuserdata	(	EN_Project	ph,
		void *	userData )

Sets a pointer to a client-side data object.

Parameters

ph	an EPANET project handle.
userData	a pointer to a client-side data object.

Returns: an error code.

The data pointer supplied by this function is passed into the callback function declared in EN_setreportcallback that replaces a project's report file as the destination for output written with EN_writeline.

◆ EN_setstatusreport()

int DLLEXPORT EN_setstatusreport	(	EN_Project	ph,
		int	level )

Sets the level of hydraulic status reporting.

Parameters

ph	an EPANET project handle.
level	a status reporting level code (see EN_StatusReport).

Returns: an error code.

Status reporting writes changes in the hydraulics status of network elements to a project's report file as a hydraulic simulation unfolds. There are three levels of reporting: EN_NO_REPORT (no status reporting), EN_NORMAL_REPORT (normal reporting) EN_FULL_REPORT (full status reporting).

The full status report contains information at each trial of the solution to the system hydraulic equations at each time step of a simulation. It is useful mainly for debugging purposes.

If many hydraulic analyses will be run in the application it is recommended that status reporting be turned off (level = EN_NO_REPORT).

◆ EN_timetonextevent()

int DLLEXPORT EN_timetonextevent	(	EN_Project	ph,
		int *	eventType,
		long *	duration,
		int *	elementIndex )

Gets information about when the next hydraulic time step occurs.

Parameters

	ph	an EPANET project handle.
[out]	eventType	the type of event that will occur (see EN_TimestepEvent).
[out]	duration	the amount of time in the future this event will occur
[out]	elementIndex	the index of the element causing the event.

◆ EN_writeline()

int DLLEXPORT EN_writeline	(	EN_Project	ph,
		const char *	line )

Writes a line of text to a project's report file.

Parameters

ph	an EPANET project handle.
line	a text string to write.

Returns: an error code.

EN_setreportcallback can be used to assign an alternative destination to write line to in place of the project's report file.

Functions

Overview

Function Documentation

◆ EN_clearreport()

◆ EN_copyreport()

◆ EN_geterror()

◆ EN_getresultindex()

◆ EN_getstatistic()

◆ EN_getversion()

◆ EN_report()

◆ EN_resetreport()

◆ EN_setreport()

◆ EN_setreportcallback()

◆ EN_setreportcallbackuserdata()

◆ EN_setstatusreport()

◆ EN_timetonextevent()

◆ EN_writeline()