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.

Example 1: Define a Universal Coverage

Example 2: Define a Coverage Subset

Syntax

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

Summary of Optional Arguments

DESCRIPTION='string'

specifies a descriptive phrase that is stored in the description field of the GISCOVER entry.

SPATIAL=spatial-entry

specifies the GISSPA-type entry to which the coverage definition refers.

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.

Required Argument

coverage-entry

specifies 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).

Operations

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

CONTENTS: prints information about the specified coverage entry. 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.
An error occurs if the specified coverage entry does not exist.

Restriction:No additional arguments (other than the coverage entry name) are used with the CONTENTS operation.

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

Requirement:For the CREATE operation, you must also specify the WHERE= argument.

DELETE: removes the specified coverage entry. 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.
An error occurs if the specified coverage entry does not exist.

Restriction:No additional arguments (other than the coverage entry name) are used with the DELETE operation.

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

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_.

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.

Requirement: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.

Options

When you specify CREATE, REPLACE, or UPDATE for theoperation argument in a COVERAGE statement, you can specify one or more of the following additional optional arguments. Separate the list of options from the coverage-entry argument with a slash (/).

DESCRIPTION='string': specifies a descriptive phrase, up to 256 characters long, that is stored in the description field of the GISCOVER entry.

Default:Blank

SPATIAL=spatial-entry: specifies the GISSPA-type entry to which the coverage definition refers. 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.

Default:Current spatial entry

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. The where-string value 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.

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'.

Examples

Example 1: 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;

Example 2: 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;