tpm_elemget

Lists information about an element in a topology.

struct resbuf

*tpm_elemget(

ade_id tpm_id,

ade_id elem_id);

Returns a resbuf list of value pairs or NULL.

tpm_id	The topology ID.
elem_id	An element ID returned by tpm_elemid.

For each value pair in the list that is returned, the first value is an integer code for the information type, and the second value is the information. The list format depends on the element type: node, link, or polygon.

The following examples illustrate possible contents of resbuf data structures returned by tpm_elemget.

If the referenced element is a node, the contents of the resbuf could be as follows.

Restype	Resval
RTLB
RTSHORT	0
RTREAL	10.000000
RTDOTE
RTLB
RTSHORT	-2
RTENAME	2546033006, 3172571566
RTDOTE
RTLB
RTSHORT	-1
RTSHORT	1
RTDOTE
RT3DPOINT	10.000000, 4.000000, 4.000000
RTLB
RTSHORT	40
RTREAL	0.000000
RTDOTE

If the refernced element is a link, the contents of the resbuf could be as follows.

Restype	Resval
RTLB
RTSHORT	0
RTREAL	29.000000
RTDOTE
RTLB
RTSHORT	-2
RTENAME	2546045206, 3172507766
RTDOTE
RTLB
RTSHORT	-1
RTSHORT	2
RTDOTE
RTLB
RTSHORT	1
RTREAL	4.000000
RTDOTE
RTLB
RTSHORT	2
RTREAL	8.000000
RTDOTE
RTLB
RTSHORT	3
RTREAL	19.000000
RTDOTE
RTLB
RTSHORT	4
RTREAL	20.000000
RTDOTE
RTLB
RTSHORT	40
RTREAL	2.320675
RTDOTE
RTLB
RTSHORT	41
RTREAL	2.320675
RTDOTE
RTLB
RTSHORT	70
RTSHORT	0
RTDOTE

If the referenced element is a polygon, the contents of the resbuf could be as follows.

Restype	Resval
RTLB
RTSHORT	0
RTREAL	20.000000
RTDOTE
RTLB
RTSHORT	-2
RTENAME	2546047206, 3172505766
RTDOTE
RTLB
RTSHORT	-1
RTSHORT	3
RTDOTE
RT3DPOINT	10.000000,3.319400,4.589200
RTLB
RTSHORT	50
RTREAL	12.775065
RTDOTE
RTLB
RTSHORT	51
RTREAL	11.674836
RTDOTE

For each dotted pair in the list that is returned, the first value is an integer code for the information type, and the second value is the information. The list format depends on the element type: node, link, or polygon.

Information List Format for Nodes

Type	Information
0	Persistent topology ID (RTREAL).
-1	Element type code (RTSHORT). With node lists, always 1, meaning node element.
-2	Entity name of the node object (RTREAL).
10	Coordinates of the node object (RTPOINT).
40	Node resistance (RTREAL). Relevant only for nodes belonging to network or polygon topologies.

Information List Format for Links

Type	Information
0	Persistent topology ID (RTREAL).
-1	Element type (RTSHORT). With link lists, always 2, meaning link element.
-2	Entity name of the link object (RTREAL).
1	Topology ID of start node (RTREAL).
2	Topology ID of end node (RTREAL).
3	Topology ID of left polygon (RTREAL). Relevant only if the link belongs to a polygon topology. Links in a polygon topology can belong to two adjacent polygons, one on the left, and one one the right.
4	Topology ID of right polygon that shares this link (RTREAL). Relevant only if the link belongs to a polygon topology.
40	Forward resistance of the link (RTREAL).
41	Reverse resistance of the link (RTREAL).
70	Link direction (RTSHORT): -1, 0, or 1, where -1 = Reverse, 0 = Bidirectional, and 1 = Forward.

Information List Format for Polygons

Type	Information
0	Persistent topology ID (RTREAL).
-1	Element type (RTSHORT). With polygon lists, always 3, meaning polygon element.
-2	Entity name of the polygon centroid (RTREAL).
10	Coordinates of the polygon centroid (RTPOINT).
50	Perimeter of the polygon (RTREAL).
51	Area of the polygon (RTREAL).

When a topology is built, it is given a set of object data fields. Their purpose is to contain the information listed in the preceding tables.

The following sample loads and then opens a network topology for read using tpm_acload() and tpm_acopen() respectively. A element id is obtained using tpm_elemid() with the topology id returned by tpm_acopen(). Tpm_elemget() is called with all required parameters. A resbuf is populated with information associated with the specified element, a portion of which is then displayed. The resbuf is then released as required.

char* pszTopoName = "NetTopo";
int returnCode = tpm_acload(pszTopoName, NULL);
int topoWriteAccess = 0;
ade_id topoId = tpm_acopen(pszTopoName, topoWriteAccess);
int elementType = 2;
long elementIndex = 1;
ade_id elementID = tpm_elemid(topoId, elementType, elementIndex);
struct resbuf* pElementInfoRb = tpm_elemget(topoId, elementID);
if (NULL != pElementInfoRb){
    struct resbuf* rb = pElementInfoRb;
    while(NULL != rb) {
        if (rb->restype == RTSHORT && (rb->resval.rint == 0)) {
            acutPrintf(
                "\nThe specified elements topology id is: %.0lf"
                , rb->rbnext->resval.rreal);
            break;
        }
        rb = rb->rbnext;
    }
}
else {
    acutPrintf(
        "\nThe specified element was not found.");
}
acutRelRb(pElementInfoRb);
tpm_acclose(topoId);
tpm_acunload(pszTopoName);