Network Link Functions

These functions are used for working with network links.

Function	Versions	Description
addLink	2.2+	Adds a new link to a project.
deleteLink	2.2+	Deletes a link from the project.
getLinkIndex	2.2+	Gets the index of a link given its ID name.
getLinkId	2.2+	Gets the ID name of a link given its index.
setLinkId	2.2+	Changes the ID name of a link.
getLinkType	2.2+	Retrieves a link’s type.
setLinkType	2.2+	Changes a link’s type.
getLinkNodes	2.2+	Gets the indexes of a link’s start- and end-nodes.
setLinkNodes	2.2+	Sets the indexes of a link’s start- and end-nodes.
getLinkValue	2.2+	Retrieves a property value for a link.
setLinkValue	2.2+	Sets a property value for a link.
getLinkValues	2.3+	Retrieves a property value for every link at once.
setLinkValues	2.3+	Sets a property value for every link at once.
setPipeData	2.2+	Sets a group of properties for a pipe link.
getPumpType	2.2+	Retrieves the type of head curve used by a pump.
getHeadCurveIndex	2.2+	Retrieves the curve assigned to a pump’s head curve.
setHeadCurveIndex	2.2+	Assigns a curve to a pump’s head curve.
getVertexCount	2.2+	Retrieves the number of internal vertex points assigned to a link.
getVertex	2.2+	Retrieves the coordinate’s of a vertex point assigned to a link.
setVertex	2.3+	Updates the coordinates of a single vertex point on a link.
setVertices	2.2+	Assigns a set of internal vertex points to a link.

---

addLink 2.2+

Adds a new link to a project.

addLink(id: string, linkType: LinkType, fromNode: string, toNode: string): number;

Parameters

Parameter	Type	Description
id	string	the ID name of the link to be added.
linkType	LinkType	The type of link being added (see LinkType)
fromNode	string	The ID name of the link’s starting node.
toNode	string	The ID name of the link’s ending node.

Returns

Number the index of the newly added link.

A new pipe is assigned a diameter of 10 inches (254 mm) and a length of 330 feet (~ 100 meters). Its roughness coefficient depends on the head loss formula in effect (see HeadLossType) as follows:

• Hazen-Williams formula: 130
• Darcy-Weisbach formula: 0.5 millifeet (0.15 mm) *Chezy-Manning formula: 0.01

All other pipe properties are set to 0.

A new pump has a status of LinkStatusType.Open, a speed setting of 1, and has no pump curve or power rating assigned to it.

A new valve has a diameter of 10 inches (254 mm) and all other properties set to 0.

See LinkProperty.

---

deleteLink 2.2+

Deletes a link from the project.

deleteLink(index: number, actionCode: ActionCodeType): void;

Parameters

Parameter	Type	Description
index	number	the index of the link to be deleted.
actionCode	ActionCodeType	The action taken if any control contains the link.

If actionCode is ActionCodeType.Unconditional then the link and all simple and rule-based controls that contain it are deleted. If set to ActionCodeType.Conditional then the link is not deleted if it appears in any control and error 261 is returned.

---

getLinkIndex 2.2+

Gets the index of a link given its ID name.

getLinkIndex(id: string): number;

Parameters

Parameter	Type	Description
id	string	a link’s ID name.

Returns

Number the link’s index (starting from 1).

---

getLinkId 2.2+

Gets the ID name of a link given its index.

getLinkId(index: number): string;

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).

Returns

string The link’s ID name.

---

setLinkId 2.2+

Changes the ID name of a link.

setLinkId(index: number, newid: string): void;

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).
newid	string	the new ID name for the link.

---

getLinkType 2.2+

Retrieves a link’s type.

getLinkType(index: number): LinkType;

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).

Returns

LinkType the link’s type (see LinkType).

---

setLinkType 2.2+

Changes a link’s type.

setLinkType(index: number, linkType: LinkType, actionCode: ActionCodeType): number;

Parameters

Parameter	Type	Description
index	number	the link’s index
linkType	LinkType	the new type to change the link to (see LinkType).
actionCode	ActionCodeType	the action taken if any controls contain the link.

Returns

Number the link’s new index after the type change.

If actionCode is ActionCodeType.Unconditional then all simple and rule-based controls that contain the link are deleted when the link’s type is changed. If set to ActionCodeType.Conditional then the type change is cancelled if the link appears in any control and error 261 is returned.

---

getLinkNodes 2.2+

Gets the indexes of a link’s start- and end-nodes.

getLinkNodes(index: number): {
  node1: number;
  node2: number;
};

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).

Returns

Object

{
  node1: number;
  node2: number;
}

Property	Type	Description
node1	number	the index of the link’s start node (starting from 1).
node2	number	the index of the link’s end node (starting from 1).

---

setLinkNodes 2.2+

Sets the indexes of a link’s start- and end-nodes.

setLinkNodes(index: number, node1: number, node2: number): void;

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).
node1	number	The index of the link’s start node (starting from 1).
node2	number	The index of the link’s end node (starting from 1).

---

getLinkValue 2.2+

Retrieves a property value for a link.

getLinkValue(index: number, property: LinkProperty): number;

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).
property	LinkProperty	the property to retrieve (see LinkProperty).

Returns

Number the current value of the property.

Values are returned in units that depend on the units used for flow rate (see Measurement Units).

---

setLinkValue 2.2+

Sets a property value for a link.

setLinkValue(index: number, property: number, value: number): void;

Parameters

Parameter	Type	Description
index	number	a link’s index.
property	number	the property to set (see LinkProperty).
value	number	the new value for the property.

Values are in units that depend on the units used for flow rate (see Measurement Units).

---

getLinkValues 2.3+

Retrieves the values of a single property for every link in the network in a single call. Avoids the per-call overhead of looping getLinkValue.

getLinkValues(property: LinkProperty): number[];

Parameters

Parameter	Type	Description
property	LinkProperty	the property to retrieve (see LinkProperty).

Returns

Number[] an array indexed by link (starting from 1) holding the property’s current value for each link.

---

setLinkValues 2.3+

Sets the value of a single property for every link at once.

setLinkValues(property: LinkProperty, values: number[]): void;

Parameters

Parameter	Type	Description
property	LinkProperty	the property to set (see LinkProperty).
values	number[]	an array of new values, one per link (starting from index 1).

---

setPipeData 2.2+

Sets a group of properties for a pipe link.

setPipeData(index: number, length: number, diam: number, rough: number, mloss: number): void;

Parameters

Parameter	Type	Description
index	number	the index of a pipe link (starting from 1).
length	number	the pipe’s length.
diam	number	the pipe’s diameter.
rough	number	the pipe’s roughness coefficient.
mloss	number	the pipe’s minor loss coefficient.

These properties have units that depend on the units used for flow rate (see Measurement Units).

---

getPumpType 2.2+

Retrieves the type of head curve used by a pump.

getPumpType(index: number): PumpType;

Parameters

Parameter	Type	Description
index	number	the index of a pump link (starting from 1).

Returns

PumpType the type of head curve used by the pump (see PumpType).

---

getHeadCurveIndex 2.2+

Retrieves the curve assigned to a pump’s head curve.

getHeadCurveIndex(linkIndex: number): number;

Parameters

Parameter	Type	Description
linkIndex	number	the index of a pump link (starting from 1).

Returns

Number the index of the curve assigned to the pump’s head curve.

---

setHeadCurveIndex 2.2+

Assigns a curve to a pump’s head curve.

setHeadCurveIndex(linkIndex: number, curveIndex: number): void;

Parameters

Parameter	Type	Description
linkIndex	number	the index of a pump link (starting from 1).
curveIndex	number	the index of a curve to be assigned as the pump’s head curve.

---

getVertexCount 2.2+

Retrieves the number of internal vertex points assigned to a link.

getVertexCount(index: number): number;

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).

Returns

Number the number of vertex points that describe the link’s shape.

---

getVertex 2.2+

Retrieves the coordinate’s of a vertex point assigned to a link.

getVertex(index: number, vertex: number): {
  x: number;
  y: number;
};

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).
vertex	number	a vertex point index (starting from 1).

Returns

Object

{
  x: number;
  y: number;
}

Property	Type	Description
x	number	the vertex’s X-coordinate value.
y	number	the vertex’s Y-coordinate value.

---

setVertex 2.3+

Updates the coordinates of a single vertex point on a link without rewriting the whole vertex list. Pair with getVertexCount to know the valid range of vertex.

setVertex(index: number, vertex: number, x: number, y: number): void;

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).
vertex	number	the vertex point’s position on the link (1-indexed).
x	number	the vertex’s new X-coordinate value.
y	number	the vertex’s new Y-coordinate value.

---

setVertices 2.2+

Assigns a set of internal vertex points to a link.

setVertices(index: number, x: number[], y: number[]): void;

Parameters

Parameter	Type	Description
index	number	a link’s index (starting from 1).
x	Number[]	an array of X-coordinates for the vertex points.
y	Number[]	an array of Y-coordinates for the vertex points.

Replaces any existing vertices previously assigned to the link.