tpm_tracealloc

Allocates the tracing model.

ade_id

tpm_tracealloc(

ade_id tpm_id,

char *node_res,

char *link_dir,

char *link_forward_res,

char *link_reverse_res);

Returns a tracing model ID or ADE_NULLID.

tpm_id	The topology ID.
node_res	Expression for node resistance. NULL = Default resistance.
link_dir	Expression for link direction. NULL = Default direction.
link_forward_res	Expression for forward link resistance. NULL = Default resistance.
link_reverse_res	Expression for reverse link resistance. NULL = Default resistance.

This function sets the values for the specified topology to the parameters you enter. The values stored in topology object data when the topology was created are used as defaults if you omit parameters. You can enter any valid expression that evaluates to a numeric result.

The tracing model can be used only with a network or polygon topology.

When you enter a value other than NULL for any of the optional resistance arguments, this value is used for all objects in the topology of the appropriate type. It overrides the corresponding value attached to the object. For example, if node_res is set to NULL, the tracing model uses the value attached to topology object data when calculating the trace. If node_res is set to 10.0, all nodes in the topology are overridden with the value of 10.0 when the trace is calculated.

If you want to omit the optional parameters, you can either enter NULL to invoke a default value or leave out the parameter altogether, as with other Visual LISP functions. However, before you omit optional parameters, note the dependency relationships indicated by bracketed groups. For example, if you want to use the link_dir parameter, you must enter a node_res parameter.

Important! When using the Topology API to perform a network trace, such as a Best Route analysis, the source topology used to create the trace topology should not be unloaded or erased until after all API calls relating to the trace have been made. This is because the trace topology references the nodes and links in the source topology. It does not create its own. So, in order to do anything with the elements of the trace, the source topology must remain loaded.

For example, the following Best Route code will silently fail:

char* pszTopoName = "NetTopo";
int topoWriteAccess = 1;
int returnCode = tpm_acload(pszTopoName, NULL);
ade_id topoId = tpm_acopen(pszTopoName, topoWriteAccess);

ade_id networkTraceId = tpm_tracealloc(topoId, NULL, NULL, NULL, NULL);

struct resbuf* pNodeListRb = acutBuildList(
                                RTREAL, 7.0,
                                RTREAL, 1.0,
                                RTREAL, 4.0,
                                RTREAL, 9.0,
                                RTREAL, 5.0,
                                RTREAL, 6.0,
                                RTREAL, 8.0,
                                0);
ade_id bestRouteTraceId = tpm_tracebestroute(topoId, networkTraceId, pNodeListRb);

acutRelRb(pNodeListRb);
tpm_acclose(topoId);
tpm_acunload(pszTopoName);

ade_id BestRouteTraceElement = tpm_tracebestroutescan(networkTraceId, 3);

The simple solution is to defer the calls to tpm_acclose and tpm_acunload until after all tpm_tracebestroutescan calls.