Product	Release
SAS/GIS	9.2

The GIS Procedure

COVERAGE Statement

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

The COVERAGE statement performs the following actions:

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

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]

COVERAGE Statement Operations

In a COVERAGE statement, the operation is one of the following:

CONTENTS
CREATE
DELETE
REPLACE
UPDATE.

The following sections contain descriptions of the COVERAGE statement operations.

CONTENTS Operation

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 Operation

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 Operation

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 Operation

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 Operation

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

<libref.catalog.>coverage-entry

In a COVERAGE statement, 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).

COVERAGE Statement Optional Arguments

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.

DESCRIPTION='string'
SPATIAL=spatial-entry
WHERE=('where-string-1 <... 'where-string-n')

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

The following sections contain descriptions of additional COVERAGE statement options.

DESCRIPTION= Argument

DESCRIPTION=`string'

DESCRIPTION= 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= Argument

SPATIAL=spatial-entry

SPATIAL= 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= Argument

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

WHERE= 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. However, the WHERE expression must delineate a bounded geographic region. 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]

COVERAGE Statement 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

SAS/GIS(R) 9.2: Spatial Data and Procedure Guide