The GIS Procedure

COVERAGE Statement

Displays information about the contents of a coverage entry, creates a new coverage entry, replaces an existing coverage entry, modifies the characteristics of a previously created coverage entry, or deletes a coverage entry.

COVERAGE operation <libref.catalog.>coverage-entry </ options>;

Operations

CONTENTS

prints information about the specified coverage entry to the Output window, including the WHERE expression that defines the spatial database subset and details of the spatial database as provided by the SPATIAL CONTENTS statement.

No additional arguments (other than the coverage entry name) are used with this operation. An error occurs if the specified coverage entry does not exist.

CREATE

creates a new coverage entry.

An error occurs if a coverage entry with the specified name already exists. The CREATE operation does not overwrite existing coverage entries. Use the REPLACE operation to replace an existing entry.

For a COVERAGE CREATE statement, you must also specify the WHERE= argument.

DELETE

removes the specified coverage entry.

No additional arguments (other than the coverage entry name) are used with this operation. An error occurs if the specified coverage entry does not exist.

For the DELETE operation, you can also specify the special value _ALL_ for the coverage entry name argument to delete all coverage entries in the current catalog.

CAUTION:: Use DELETE with care.
The GIS procedure does not prompt you to verify the request before deleting the coverage entry. Be especially careful when you use _ALL_.

Note: You must specify new coverages for any map entries that refer to the deleted coverage entry. [cautionend]

REPLACE

overwrites the specified coverage entry or creates a new entry if an entry with the specified name does not exist. The REPLACE operation has the effect of canceling the previously issued CREATE operation for the specified coverage entry.

For a REPLACE operation, you must also specify the WHERE= argument.

UPDATE

modifies the specified coverage entry by applying new values for specified arguments.

An error occurs if there is no existing coverage entry with the specified name.

Coverage Entry Name Argument

The coverage entry name argument identifies the coverage entry that you want to create, delete, replace, or update. The coverage-entry name 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 are read as the same name).

Options

When you specify CREATE, REPLACE, or UPDATE for the operation in a COVERAGE statement, you can specify one or more of these options following the coverage entry name.

Note: Separate the list of arguments from the coverage-entry with a slash (/). [cautionend]

DESCRIPTION='string'

specifies a descriptive phrase, up to 256 characters long, that is stored in the description field of the GISCOVER entry. The default description is blank.

SPATIAL=spatial-entry

specifies the GISSPA-type entry to which the coverage definition refers. The default is the current spatial entry.

An error occurs if there is no existing spatial entry that has the specified name, or if you omit this argument when no spatial entry is currently selected.

WHERE=('where-string-1 <... 'where-string-n')

specifies a WHERE expression that subsets the chains data set to define a geographic coverage of a spatial database. Where-string can contain a complete valid WHERE expression of 200 characters or fewer.

To specify a WHERE expression greater than 200 characters, you must break the expression into separate quoted strings. When WHERE= is processed, the strings are concatenated, with a space between each string, and the entire expression is evaluated.

You can specify multiple WHERE expressions to delineate the coverage. If you are using multiple strings, each string does not have to contain a complete WHERE expression, but the concatenated expression must be valid.

You can use any of the variables in the chains data set in the WHERE expression, not just the coordinate variables. When the map is opened, only those chains that match the WHERE clause are read in. You can use only variables in the WHERE expression, not composites. Specify WHERE='1' to define a coverage that includes the entire spatial database.

Note: The WHERE= argument is required when you use the CREATE or REPLACE operation. [cautionend]

Details

A coverage entry is a SAS catalog entry of type GISCOVER that contains information about the spatial data that is used to create a map. The entry also contains a subsetting WHERE expression to define the subset of spatial data, or coverage, of the map that you want to display.

For example, you could create a coverage entry, MYCAP, that contains geographic information for your state capital. MYCAP subsets the spatial database that is defined in the spatial entry MYSTATE, which contains geographic information that is used to create a map of your entire state.

Note: Even if you want to display the entire geographic scope of your spatial data and not a subset, you must still create a coverage entry by using WHERE='1'. [cautionend]

Examples

Define a Universal Coverage

The following code fragment creates a coverage entry that is named GMAPS.USA.ALL.GISCOVER. The code defines a coverage of the entire spatial database that is defined in GMAPS.USA.USA.GISSPA:

proc gis cat=gmaps.usa;
   spatial usa;
   coverage create all / where='1';
run;

Define a Coverage Subset

Assume that the chains data set for the current spatial entry has the variables STATEL and STATER that contain FIPS state codes for the states on the left and right side of each chain. The following code fragment creates a coverage entry that is named SOUTHEAST of type GISCOVER. The code defines a coverage of only the selected states from the current spatial entry:

coverage create southeast /
   where=("statel in (1,12,13,28,37,45,47) |
           stater in (1,12,13,28,37,45,47)");
run;

Top of Page