Project Functions

Functions
int DLLEXPORT	EN_createproject (EN_Project *ph)
	Creates an EPANET project.
int DLLEXPORT	EN_deleteproject (EN_Project ph)
	Deletes a currently opened EPANET project.
int DLLEXPORT	EN_runproject (EN_Project ph, const char *inpFile, const char *rptFile, const char *outFile, void(*pviewprog)(char *))
	Runs a complete EPANET simulation.
int DLLEXPORT	EN_init (EN_Project ph, const char *rptFile, const char *outFile, int unitsType, int headLossType)
	Initializes an EPANET project.
int DLLEXPORT	EN_open (EN_Project ph, const char *inpFile, const char *rptFile, const char *outFile)
	Reads an EPANET input file with no errors allowed.
int DLLEXPORT	EN_openX (EN_Project ph, const char *inpFile, const char *rptFile, const char *outFile)
	Reads an EPANET input file with errors allowed.
int DLLEXPORT	EN_getcount (EN_Project ph, int object, int *out_count)
	Retrieves the number of objects of a given type in a project.
int DLLEXPORT	EN_gettitle (EN_Project ph, char *out_line1, char *out_line2, char *out_line3)
	Retrieves the title lines of the project.
int DLLEXPORT	EN_settitle (EN_Project ph, const char *line1, const char *line2, const char *line3)
	Sets the title lines of the project.
int DLLEXPORT	EN_getcomment (EN_Project ph, int object, int index, char *out_comment)
	Retrieves a descriptive comment assigned to a Node, Link, Pattern or Curve.
int DLLEXPORT	EN_setcomment (EN_Project ph, int object, int index, const char *comment)
	Assigns a descriptive comment to a Node, Link, Pattern or Curve.
int DLLEXPORT	EN_gettag (EN_Project ph, int object, int index, char *out_tag)
	Retrieves a tag string assigned to a Node or Link.
int DLLEXPORT	EN_settag (EN_Project ph, int object, int index, const char *tag)
	Assigns a tag string to a Node or Link.
int DLLEXPORT	EN_saveinpfile (EN_Project ph, const char *filename)
	Saves a project's data to an EPANET-formatted text file.
int DLLEXPORT	EN_close (EN_Project ph)
	Closes a project and frees all of its memory.

Overview

These functions are used to manage a project.

Function Documentation

EN_close()

int DLLEXPORT EN_close

(

EN_Project

ph

)

Closes a project and frees all of its memory.

Parameters

ph	an EPANET project handle.

Returns

an error code

This function clears all existing data from a project but does not delete the project, so it can be re-used with another set of network data. Use EN_deleteproject to actually delete a project from memory.

EN_createproject()

int DLLEXPORT EN_createproject

(

EN_Project *

ph

)

Creates an EPANET project.

Parameters

[out]

ph

an EPANET project handle that is passed into all other API functions.

Returns

an error code.

EN_createproject must be called before any other API functions are used.

EN_deleteproject()

int DLLEXPORT EN_deleteproject

(

EN_Project

ph

)

Deletes a currently opened EPANET project.

Parameters

[in,out]

ph

an EPANET project handle which is returned as NULL.

Returns

an error code.

EN_deleteproject should be called after all network analysis has been completed.

EN_getcomment()

int DLLEXPORT EN_getcomment	(	EN_Project	ph,
		int	object,
		int	index,
		char *	out_comment )

Retrieves a descriptive comment assigned to a Node, Link, Pattern or Curve.

Parameters

	ph	an EPANET project handle.
	object	a type of object (either EN_NODE, EN_LINK, EN_TIMEPAT or EN_CURVE)
	index	the object's index starting from 1
[out]	out_comment	the comment string assigned to the object

Returns

an error code

EN_getcount()

int DLLEXPORT EN_getcount	(	EN_Project	ph,
		int	object,
		int *	out_count )

Retrieves the number of objects of a given type in a project.

Parameters

	ph	an EPANET project handle.
	object	a type of object to count (see EN_CountType)
[out]	out_count	number of objects of the specified type

Returns

an error code

EN_gettag()

int DLLEXPORT EN_gettag	(	EN_Project	ph,
		int	object,
		int	index,
		char *	out_tag )

Retrieves a tag string assigned to a Node or Link.

Parameters

	ph	an EPANET project handle.
	object	a type of object (either EN_NODE or EN_LINK)
	index	the object's index starting from 1
[out]	out_tag	the tag string assigned to the object

Returns

an error code

EN_gettitle()

int DLLEXPORT EN_gettitle	(	EN_Project	ph,
		char *	out_line1,
		char *	out_line2,
		char *	out_line3 )

Retrieves the title lines of the project.

Parameters

	ph	an EPANET project handle.
[out]	out_line1	first title line
[out]	out_line2	second title line
[out]	out_line3	third title line

Returns

an error code

EN_init()

int DLLEXPORT EN_init	(	EN_Project	ph,
		const char *	rptFile,
		const char *	outFile,
		int	unitsType,
		int	headLossType )

Initializes an EPANET project.

Parameters

ph	an EPANET project handle.
rptFile	the name of a report file to be created (or "" if not needed).
outFile	the name of a binary output file to be created (or "" if not needed).
unitsType	the choice of flow units (see EN_FlowUnits).
headLossType	the choice of head loss formula (see EN_HeadLossType).

Returns

an error code.

This function should be called immediately after EN_createproject if an EPANET-formatted input file will not be used to supply network data. If the project receives it's network data from an input file then there is no need to call this function.

EN_open()

int DLLEXPORT EN_open	(	EN_Project	ph,
		const char *	inpFile,
		const char *	rptFile,
		const char *	outFile )

Reads an EPANET input file with no errors allowed.

Parameters

ph	an EPANET project handle.
inpFile	the name of an existing EPANET-formatted input file.
rptFile	the name of a report file to be created (or "" if not needed).
outFile	the name of a binary output file to be created (or "" if not needed).

Returns

an error code.

This function should be called immediately after EN_createproject if an EPANET-formatted input file will be used to supply network data. If errors are detected then the project is not opened and will not accept toolkit function calls.

EN_openX()

int DLLEXPORT EN_openX	(	EN_Project	ph,
		const char *	inpFile,
		const char *	rptFile,
		const char *	outFile )

Reads an EPANET input file with errors allowed.

Parameters

ph	an EPANET project handle.
inpFile	the name of an existing EPANET-formatted input file.
rptFile	the name of a report file to be created (or "" if not needed).
outFile	the name of a binary output file to be created (or "" if not needed).

Returns

an error code.

This function should be called immediately after EN_createproject if an EPANET-formatted input file will be used to supply network data. If formatting errors are detected (error code = 200) then the project remains open and will accept toolkit function calls.

EN_runproject()

int DLLEXPORT EN_runproject	(	EN_Project	ph,
		const char *	inpFile,
		const char *	rptFile,
		const char *	outFile,
		void(*	pviewprog )(char *) )

Runs a complete EPANET simulation.

Parameters

ph	an EPANET project handle.
inpFile	the name of an existing EPANET-formatted input file.
rptFile	the name of a report file to be created (or "" if not needed)
outFile	the name of a binary output file to be created (or "" if not needed)
pviewprog	a callback function that takes a character string (char *) as its only parameter.

Returns

an error code

The callback function should reside in and be used by the calling code to display the progress messages that EPANET generates as it carries out its computations. Here is an example of a such a function that displays progress messages to stdout:

void  writeConsole(char *s)
{
    fprintf(stdout, "\n%s", s);
}

It would be passed into EN_runproject as &writeConsole. If this feature is not needed then the pviewprog argument should be NULL.

EN_saveinpfile()

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

Saves a project's data to an EPANET-formatted text file.

Parameters

ph	an EPANET project handle.
filename	the name of the file to create.

Returns

an error code

EN_setcomment()

int DLLEXPORT EN_setcomment	(	EN_Project	ph,
		int	object,
		int	index,
		const char *	comment )

Assigns a descriptive comment to a Node, Link, Pattern or Curve.

Parameters

ph	an EPANET project handle.
object	a type of object (either EN_NODE, EN_LINK, EN_TIMEPAT or EN_CURVE)
index	the object's index starting from 1
comment	the comment string assigned to the object

Returns

an error code

EN_settag()

int DLLEXPORT EN_settag	(	EN_Project	ph,
		int	object,
		int	index,
		const char *	tag )

Assigns a tag string to a Node or Link.

Parameters

ph	an EPANET project handle.
object	a type of object (either EN_NODE or EN_LINK)
index	the object's index starting from 1
tag	the tag string assigned to the object

Returns

an error code

EN_settitle()

int DLLEXPORT EN_settitle	(	EN_Project	ph,
		const char *	line1,
		const char *	line2,
		const char *	line3 )

Sets the title lines of the project.

Parameters

ph	an EPANET project handle.
line1	first title line
line2	second title line
line3	third title line

Returns

an error code