tpm_anaoverlay

Up a level

tpm_anaoverlay

Analyzing Functions

Overlays two topologies.

int

tpm_anaoverlay(

ade_id overlay_id,

struct resbuf *overlay_data,

ade_id source_id,

struct resbuf *source_data,

int oper,

ade_id var_id,

char *obj-table,

char *obj_tabledesc,

char *result_name,

char *result_desc);

Returns RTNORM or an error code

See the Visual LISP description of tpm_anaoverlay for information about the list elements in the expr1 resbuf.

If the result_name argument is NULL, the result is a collection of AutoCAD objects. Otherwise it is a new topology that is loaded but not open. The last four parameters have the same mutual dependencies in the ADSRX function as they do in the Visual LISP equivalent, except that you cannot omit any of them. You must use NULL.

The source topology must be of polygon type for union and paste operations. For all other operations, it can be of any topology type, such as node, network, and polygon.

The topology variables ID references a set of topology variables.

Overlay Data Expressions

The overlay_data and source_data arguments are resbufs that are constructed as follows:

struct resbuf *list1;
list1 = acutBuildList(
   RTLB
      RTSTR expr1
      RTSTR colname1
      RTSTR coldsc1
      RTSHORT coltype1
   RTLE
   RTLB
      RTSTR expr2
      . . .
   RTLE
   . . .
0);

Overlay Data Expression Arguments

Result Topology

If the result_name argument is omitted or nil, the result is a collection of AutoCAD objects. Otherwise, it is a new topology that is loaded but not open.

You must specify the list of data values to come from each input topology and the specific data for each.

Additionally, you must specify the name of the result object data table in the objTable parameter to contain the final data. If you do not specify a result table, no data is attached to the resulting topology elements. The function creates this table. If the result table you specify already exists, the function returns an error and cancels the overlay process.

Data derived by the overlay process is also attached to the result object data table. This data is written for each topology element in the resulting topology. It is written for each polygon if the source is a polygon topology, for each link if it is a network topology, or for each node if it is a node topology. The table always includes the following fields:

The result table includes these fields along with the fields that you specify in the arguments you supply for the overlay_data and source_data parameters. Each field name is prefixed with T1_ or T2_ to indicate which topology its data comes from.

For example, if you specify FIELD1, FIELD2 and FIELD3 from table SOIL for the first topology and FIELD1, FIELD4 and FIELD5 from table WATER for the second, the result table has the following fields:

T1_SOIL_FIELD1
T1_SOIL_FIELD2
T1_SOIL_FIELD3
T1_WATER_FIELD1
T1_WATER_FIELD4
T1_WATER_FIELD5

The following sample overlays two polygon topologies which are opened and loaded using tpm_acload() and tpm_acopen() respectively. A resbuf is created which contains data expressions associated with object data attached to the source topology. tpm_anaoverlay() is called with all required parameters. The resulting topology and object data table contains information about the percentage of the source polygons consumed by the overlay, (buffer topology), the median household income and the population density per square mile among others. The input topologies are closed and then unloaded using tpm_acclose() and tpm_acunload() respectively. The resbufs are then released as required.

char* pszOverlayTopoName = "I-95_Buffer";
int topoWriteAccess = 0;
int returnCode = tpm_acload(pszOverlayTopoName, 0);
ade_id topoForOverlayId = tpm_acopen(pszOverlayTopoName, topoWriteAccess);
struct resbuf* pOverlayDataRb = NULL;
char* pszSourceTopoName = "blkgrp";
returnCode = tpm_acload(pszSourceTopoName, 0);
ade_id sourceTopoId = tpm_acopen(pszSourceTopoName, topoWriteAccess);
struct resbuf* pSourceDataRb = acutBuildList(
                                 RTLB,
                                    RTSTR, ":MEDIAN_VAL@RIBLKGRP",  // Data Extension expression
                                    RTSTR, "MEDIAN_VAL",            // Object data column name
                                    RTSTR, "",                      // Object data column description
                                    RTSHORT, 2,                     // Object data column type
                                 RTLE,
                                 RTLB,
                                    RTSTR, ":POP90_SQMI@RIBLKGRP",
                                    RTSTR, "POP90_SQMI",
                                    RTSTR, "",
                                    RTSHORT, 1,
                                 RTLE,
                                 0);
int overlayOperation = 1;
ade_id topoConfigVarId = tpm_varalloc();
char* pszODTable = "BufferOverlayBlkGrp";
char* pszODTableDesc = "BufferOverlayBlkGrp-Desc";
char* pszResultTopoName = "BuffrOverBlkGrp";
char* pszResultTopoDesc = "BuffrOverBlkGrp-Desc";
returnCode = tpm_anaoverlay(
                topoForOverlayId,
                pOverlayDataRb,
                sourceTopoId,
                pSourceDataRb,
                overlayOperation,
                topoConfigVarId,
                pszODTable,
                pszODTableDesc,
                pszResultTopoName,
                pszResultTopoDesc
                );
if (RTNORM == returnCode){
    acutPrintf(
        "\nThe overlay operation was successfully completed.");
}
else {
    acutPrintf(
        "\nThe overlay operation could not be performed.");
}
tpm_acclose(topoForOverlayId);
tpm_acunload(pszOverlayTopoName);
tpm_acclose(sourceTopoId);
tpm_acunload(pszSourceTopoName);
acutRelRb(pOverlayDataRb);
acutRelRb(pSourceDataRb);