Working with Spatial Data Using SAS/GIS Software

POLYGONAL INDEX Statement

POLYGONAL INDEX operation polygonal-index </ arguments>;

The POLYGONAL INDEX statement creates, modifies, or deletes polygonal index data sets using a libref and polygonal index references from a spatial entry. Polygonal indexes delineate enclosed areas in the spatial data by noting the chains that form polygons. The spatial database must include a polygonal index data set for each feature 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 (GISSPA) entry to determine area boundaries. The composites used for polygonal indexes must have the CLASS attribute AREA (or one of the political subdivision area classes such as COUNTRY, STATE, or COUNTY which imply AREA).

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. [cautend]

POLYGONAL INDEX Statement Operations

In a POLYGONAL INDEX statement, the operation is one of the following:

CREATE
DELETE
REPLACE
UPDATE

The following list contains descriptions of the POLYGONAL INDEX statement operations:

CREATE

CREATE creates a polygonal index data set and stores the polygonal index definition in the current spatial entry.

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. The POLYGONAL INDEX CREATE statement does not overwrite existing index definitions or data sets. Use POLYGONAL INDEX REPLACE to replace an existing index definition or data set.

For a POLYGONAL INDEX CREATE statement, you must specify both the COMPOSITE= and OUT= arguments.

DELETE

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 using the _ALL_ keyword.

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 argument to prevent the index data set from being deleted.

KEEP is the only additional argument (other than the polygonal index name) that can be used with this operation. 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.

REPLACE

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.

For a POLYGONAL INDEX REPLACE statement, you must specify both the COMPOSITE= and OUT= arguments.

Note: If the data set 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. [cautend]

UPDATE

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. If an existing data set owned by a different spatial entry specified in the OUT= argument already exists, you must use the FORCE argument to cause it to be overwritten.

Polygonal-index

In a POLYGONAL INDEX statement, the polygonal-index argument names the polygonal index you want to create, delete, replace, or update.

The polygonal-index value must conform to the 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).

Optional Arguments

When you specify CREATE, REPLACE, or UPDATE for the operation in a POLYGONAL INDEX statement, you can specify the following additional arguments following the polygonal index name.

COMPOSITE
ERRORS
FORCE
KEEP
OUT

Note: Separate the list of arguments from the polygonal index name with a slash (/). [cautend]

The following list contains descriptions of optional POLYGONAL INDEX statement arguments:

COMPOSITE

COMPOSITE=(composite-1<, ..., composite-n>) specifies the composite or list of composites that define the boundaries of the enclosed polygonal areas used to create the index. If the composite list consists of a single composite name, 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 AREA.

Note: The COMPOSITE= argument is required when you use the CREATE or REPLACE keyword. [cautend]

ERRORS

ERRORS<=number> specifies whether messages about any topological errors that are detected while the index is being constructed are written to the SAS log. 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

FORCE indicates that an existing polygonal index data set specified in the OUT= argument can be overwritten 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

KEEP specifies that polygonal index data sets are to be retained when the index definition is removed from the spatial entry. This option is valid only with the DELETE operation.

OUT

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

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

If you use a one-level name, the data set will be created (or replaced) in the library specified in the CATALOG= option on the PROC GIS statement. Use a two-level name to override the default library. [cautend]

CAUTION:: Do not use host commands to move or rename polygonal index data sets. Because the polygonal index data set names are referred to in GISSPA entries, moving or renaming a polygonal index data set breaks the association between the GISSPA entry and the data set. To prevents breaking the association, use the GIS MOVE statement with the CHECKPARENTS option instead of a host command.

POLYGONAL INDEX Statement Example

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

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

Chapter Contents
Previous
Next
Top of Page