These functions are used to report simulation results. More...

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

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

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

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

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

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

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

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

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

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

int	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. More...

Overview

These functions are used to report simulation results.

Function Documentation

◆ EN_clearreport()

int 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 EN_copyreport	(	EN_Project	ph,
		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 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 at least EN_MAXMSG characters in length.

◆ EN_getresultindex()

int 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]	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 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]	value	the value of the statistic.

Returns: an error code

◆ EN_getversion()

int EN_getversion ( int * out_version )

Retrieves the toolkit API version number.

Parameters

[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 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 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 EN_setreport	(	EN_Project	ph,
		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_setstatusreport()

int 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_writeline()

int EN_writeline	(	EN_Project	ph,
		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.

Functions

Overview

Function Documentation

◆ EN_clearreport()

◆ EN_copyreport()

◆ EN_geterror()

◆ EN_getresultindex()

◆ EN_getstatistic()

◆ EN_getversion()

◆ EN_report()

◆ EN_resetreport()

◆ EN_setreport()

◆ EN_setstatusreport()

◆ EN_writeline()