The GIS Procedure

POLYGONAL INDEX Statement

Creates, replaces, modifies, or deletes polygonal index data sets by using a libref and polygonal index references from a spatial entry.

Syntax

POLYGONAL INDEX operation polygonal-index </ options>;

Summary of Optional Arguments

AREA

calculates the enclosed areas and perimeter lengths for the lowest-level area composite that is specified on the COMPOSITE= argument.

CENTROID<=GEOMETRIC | VISUAL>

specifies the type of centroid data that is returned.

COMPOSITE=(composite-name-1<, ..., composite-name-n>)

specifies the composite or list of composites that define the boundaries of the enclosed polygonal areas that are used to create the index.

ERRORS<=number>

specifies whether messages about any topological errors that are detected while the index is being constructed are written to the SAS log.

FORCE

indicates that an existing polygonal index data set that is specified in the OUT= argument can be overwritten.

KEEP

specifies that polygonal index data sets are to be retained when the index definition is removed from the spatial entry.

OUT=data-set-name

names the index data set that you want to create, replace, or update.

Required Argument

polygonal-index

specifies the polygonal index that you want to create, delete, replace, or update. The polygonal-index value must conform to the following rules for SAS names:

The name can be no more than 32 characters long.
The first character must be a letter or underscore (_). Subsequent characters can be letters, numeric digits, or underscores. Blanks are not permitted.
Mixed-case names are honored for presentation purposes. However, because any comparison of names is not case-sensitive, you cannot have two names that differ only in case (for example, State and STATE are read as the same name).

Operations

You must specify one of the following values for the operation keyword:

CREATE: creates a polygonal index data set and stores the polygonal index definition in the current spatial entry. The POLYGONAL INDEX CREATE statement does not overwrite existing index definitions or data sets. A warning is issued and processing of the current RUN group is halted if either a polygonal index definition or a SAS data set with the specified names already exist. Use POLYGONAL INDEX REPLACE to replace an existing index definition or data set.

Requirement:For the CREATE operation, you must specify both the COMPOSITE= and OUT= arguments.

DELETE: removes the specified polygonal index definition from the spatial entry. By default, the POLYGONAL INDEX DELETE statement also deletes the associated index data set. You can use the KEEP option to prevent the index data set from being deleted.
A warning is issued and processing of the current RUN group is halted if the specified polygonal index does not exist.

For DELETE, you can also specify the special value _ALL_ for the polygonal-index argument to delete all the polygonal index definitions in the current spatial entry.

Restriction:KEEP is the only additional argument (other than the polygonal index name) that can be used with the DELETE operation.

CAUTION:

Use DELETE with care.

The GIS procedure does not prompt you to verify the request before deleting an existing polygonal index. Be especially careful when you use the _ALL_.

REPLACE: overwrites the polygonal index definition in the current spatial entry or creates a new polygonal index definition if the specified index does not exist.

Requirement:For the REPLACE operation, you must specify both the COMPOSITE= and OUT= arguments.

Note:If the data set that is specified in the OUT= argument already exists and belongs to a different spatial entry, you must specify the FORCE argument to cause it to be overwritten.

UPDATE: modifies only the specified characteristics for an existing polygonal index. A warning is issued and processing of the current RUN group is halted if there is no existing polygonal index with the specified name.

Note:If the data set that is specified in the OUT= argument already exists and belongs to a different spatial entry, you must specify the FORCE argument to cause it to be overwritten.

Options

When you specify CREATE, REPLACE, or UPDATE for the operation argument in the POLYGONAL INDEX statement, you can specify the one or more of the following additional optional arguments. When you specify DELETE for the operation argument, only the KEEP option is allowed. Separate the list of arguments from the polygonal index name with a slash (/).

AREA: calculates the enclosed areas and perimeter lengths for the lowest-level area composite that is specified on the COMPOSITE= argument. The calculated area is added to the polygonal index data set in a variable named AREA. A label for the AREA variable contains the storage area units. The calculated perimeter is added to the polygonal index data set in a variable named PERIMETER. A label for the PERIMETER variable contains the units.

CENTROID<=GEOMETRIC | VISUAL>

specifies the type of centroid data that is returned.

GEOMETRIC: returns the actual calculated centroids, which might not fall within the boundaries of their corresponding polygons. The coordinates are added to the polygonal index data set in variables that are named CTRX and CTRY. Labels for the CTRX and CTRY variables contain the storage projection units and indicate that this is a GEOMETRIC centroid. Specifying the CENTROID argument by itself returns the same results as specifying CENTROID=GEOMETRIC.

VISUAL: returns adjusted centroids that are moved to be within the boundaries of their corresponding polygons. The coordinates are added to the polygonal index data set in variables that are named CTRX and CTRY. Labels on the CTRX and CTRY variables contain the storage projection units and indicate that this is a VISUAL centroid.

COMPOSITE=(composite-name-1<, ..., composite-name-n>): specifies the composite or list of composites that define the boundaries of the enclosed polygonal areas that are used to create the index. If the composite-name list consists of a single composite, you can omit the parentheses. An error occurs if any of the specified composites are not defined in the current spatial entry or if any do not have the CLASS attribute of AREA.

Note:The COMPOSITE= argument is required when you use the CREATE or REPLACE operation.

ERRORS<=number>: specifies whether messages about any topological errors that are detected while the index is being constructed are written to the SAS log. A polygon boundary consists of a single chain with the same starting and ending node, or multiple chains that form a closed boundary. The starting node for each boundary chain must be the ending node of the previous chain. The ending node of the last chain must be the beginning node of the first boundary chain. A topology error occurs when the polygon is not closed. You can specify the ERRORS argument with no added parameter to print all topological error messages, or you can add the =number parameter to specify the maximum number of topological error messages that will be written to the log.

FORCE: indicates that an existing polygonal index data set that is specified in the OUT= argument can be overwritten, even if it belongs to a different spatial entry. If you omit this option, the data set is not replaced and a warning is issued.

KEEP: specifies that polygonal index data sets are to be retained when the index definition is removed from the spatial entry.

Restriction:This option is valid only with the DELETE operation.

OUT=data-set-name: names the index data set that you want to create, replace, or update.

Note:The OUT= argument is required when you use the CREATE or REPLACE operation.

CAUTION:

Do not use host commands to move or rename polygonal index data sets.

Because the polygonal index data set names are stored in GISSPA entries, moving or renaming a polygonal index data set breaks the association between the GISSPA entry and the data set. To prevent breaking the association, use the PROC GIS MOVE statement with the CHECKPARENT option instead of a host command.

Details

Polygonal indexes delineate enclosed areas in the spatial data by noting the chains that form polygons. This statement is also used to compute the enclosed areas, the centroid coordinates, and the perimeter lengths of the individual polygons.

The spatial database must include a polygonal index data set for each feature type that you intend to represent as an area layer in the map. For example, to represent states and counties as enclosed areas, you must have separate polygonal indexes for each.

The POLYGONAL INDEX statement uses composite values from the current spatial entry to determine area boundaries. The composites that are used for polygonal indexes must have the CLASS attribute AREA (or one of the political subdivision area classes such as COUNTRY, STATE, or COUNTY that imply AREA by default).

Polygonal index definitions are stored in the currently specified spatial entry. An error occurs if you submit a POLYGONAL INDEX statement when no spatial entry is currently selected.

Note: You can use the SPATIAL CONTENTS statement to view the polygonal index definitions for a spatial entry.

Example

The following code fragment builds a polygonal index data set that is named GMAPS.STATEX. The data set identifies the boundaries of the polygons for the area feature that is identified by the STATE composite in the current spatial entry:

polygonal index create state / composite=state
                               out=gmaps.statex;
run;