OWA-EPANET Toolkit  2.2
Reporting Functions

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 *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 *value)
 Retrieves a particular simulation statistic. More...
 
int EN_getresultindex (EN_Project ph, int type, int index, int *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
phan 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
phan EPANET project handle.
filenamethe 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
errcodean error code.
[out]out_errmsgthe error message generated by the error code
maxLenmaximum 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 *  value 
)

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

Parameters
phan EPANET project handle.
typea type of element (either EN_NODE or EN_LINK).
indexthe element's current index (starting from 1).
[out]valuethe 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 *  value 
)

Retrieves a particular simulation statistic.

Parameters
phan EPANET project handle.
typethe type of statistic to retrieve (see EN_AnalysisStatistic).
[out]valuethe value of the statistic.
Returns
an error code

◆ EN_getversion()

int EN_getversion ( int *  version)

Retrieves the toolkit API version number.

Parameters
[out]versionthe 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
phan 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
phan 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
phan EPANET project handle.
formata 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
phan EPANET project handle.
levela 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
phan EPANET project handle.
linea text string to write.
Returns
an error code.