Product	Release
SAS/GIS	9.2

The GIS Procedure

SPATIAL Statement

SPATIAL <operation> <libref.catalog.>spatial-entry </ options>;

The SPATIAL statement performs the following actions:

selects the spatial entry on which subsequent statements operate
displays information about the contents of a spatial entry
creates a new spatial entry, replaces an existing spatial entry, or modifies the characteristics of an existing spatial entry
deletes a spatial entry.

A spatial entry is a SAS catalog entry of type GISSPA that defines the components of a SAS/GIS spatial database. The definition specifies which SAS data sets contain spatial information, how the data sets are related, and what roles the variables play.

Any composites, polygonal indexes, and lattice hierarchies that are created or updated during an invocation of the GIS procedure are stored in the current spatial entry. Any subsequent COVERAGE statements that are issued within the PROC GIS step subset the data in the current spatial entry.

No additional arguments (other than the spatial entry name) are used when the operation keyword is omitted. An error occurs if there is no existing spatial entry that has the specified name.

Note: When creating or replacing spatial entries, you can either define entirely new spatial entries or merge two or more existing spatial entries. [cautionend]

SPATIAL Statement Operations

In a SPATIAL statement, the operation keyword can be one of the following:

CONTENTS
CREATE
DELETE
REPLACE
UPDATE.

Note: If you omit the operation keyword, the SPATIAL statement makes the specified spatial entry the current spatial entry for subsequent operations. No SPATIAL statement options can be used in a spatial assignment statement. [cautionend]

The following sections contain descriptions of the SPATIAL statement operations.

CONTENTS Operation

CONTENTS prints information about the specified spatial entry to the Output window, including the following:

a list of the dependent data objects (data sets or other spatial entries) that store the spatial data
a list of the SAS data sets (chains, nodes, details, and polygonal indexes) that store the spatial data
a list of the composites for the spatial data
the lattice hierarchy for the spatial data
the storage projection characteristics of the spatial data.

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

Note: The specified spatial entry does not become the current spatial entry for subsequent operations unless no spatial entry is currently selected. [cautionend]

CREATE Operation

CREATE generates a new spatial entry in which subsequent composites, polygonal index names, and lattice hierarchies that are specified in the GIS procedure are stored. The new spatial entry becomes the current spatial entry for subsequent operations.

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

For a SPATIAL CREATE statement, you must also specify both the CHAINS= and NODES= arguments or the MERGE= argument.

DELETE Operation

DELETE deletes the specified spatial entry. By default, any polygonal index data sets that are referred to in the spatial entry are also deleted. The chains, nodes, or details data sets that are referred to in the spatial entry are not deleted. To retain existing polygonal index data sets when the spatial entry is deleted, use the KEEP argument in the SPATIAL DELETE statement.

KEEP is the only additional argument (other than the spatial entry name) that can be used with this operation. An error occurs if the specified spatial entry does not exist.

Note: For the DELETE operation, you can also specify the special value _ALL_ for the spatial entry name argument to delete all spatial entries in the current catalog. [cautionend]

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

REPLACE Operation

REPLACE overwrites the specified spatial entry or creates a new entry if an entry with the specified name does not exist. The specified spatial entry becomes the current spatial entry for subsequent operations. The SPATIAL REPLACE statement has the effect of canceling all previously issued SPATIAL CREATE, COMPOSITE, POLYGONAL INDEX, and LATTICE statements for the specified spatial entry.

For the SPATIAL REPLACE statement, you must specify both the CHAINS= and NODES= arguments or the MERGE= argument.

UPDATE Operation

UPDATE modifies the specified spatial entry by applying new values for specified arguments. The updated spatial entry becomes the current spatial entry for the subsequent operations.

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

Spatial-Entry Name Argument

In a SPATIAL statement, the spatial entry name argument identifies the GISSPA-type entry that you want to create, replace, update, delete, or make the current spatial entry. The general form of the argument is

<libref.catalog.>spatial-entry

CAUTION:: Do not use host commands to move or rename SAS data sets that are referenced in GISSPA entries.
Moving or renaming a data set that is referred to in a spatial entry breaks the association between the spatial 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.

SPATIAL Statement Optional Arguments

When you specify CREATE, REPLACE, or UPDATE for the operation keyword, you can specify one or more of the following optional arguments after the spatial entry name.

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

CARTESIAN | LATLON
CHAINS=data-set
DEGREES | RADIANS | SECONDS
DESCRIPTION='string'
DETAILS=data-set
EAST | WEST
KEEP
MERGE=(spatial-entry-list) <EDGEMATCH <LINKONLY> | OVERLAP <ZEROMISS>> <ERROR_ROW=integer>
MULT=multiplier-value
NODES=data-set
NORTH | SOUTH

When you specify DELETE for the operation keyword, only the following option is allowed:

KEEP.

The following sections contain descriptions of the optional SPATIAL statement arguments.

CARTESIAN | LATLON Argument

CARTESIAN | LATLON

This argument specifies the coordinate system that is used in the stored spatial data.

CARTESIAN: data is in an arbitrary rectangular (plane) coordinate system.
LATLON: data is in a geographic (spherical) coordinate system.

The default is LATLON.

Note: The CARTESIAN and LATLON arguments are ignored when the MERGE= argument is used. [cautionend]

CHAINS= Argument

CHAINS=data-set

CHAINS= names the SAS data set that contains chain definitions for the spatial database. A chain is one or more line segments that connect one node (or point on the map) to another. For example, a series of chains can represent a railroad or a river.

Note: The CHAINS= argument is required when you use the CREATE or REPLACE keyword and do not specify the MERGE= argument. [cautionend]

DEGREES | RADIANS | SECONDS Argument

DEGREES | RADIANS | SECONDS

This argument specifies the coordinate units for the stored spatial data when the coordinate system is geographic (LATLON). The default is RADIANS.

Note: This argument is ignored when the CARTESIAN or MERGE= arguments are used. [cautionend]

DESCRIPTION= Argument

DESCRIPTION=`string'

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

DETAILS= Argument

DETAILS=data-set

DETAILS= names the SAS data set that contains detail definitions for the spatial database. Details are the points at angle breaks in chains. They provide a finer granularity for the chain's line segments. A data set that contains detail definitions might describe the curvy outline of a coastal road.

EAST | WEST Argument

EAST | WEST

This argument specifies the hemisphere in which the spatial data points lie. The default is EAST. EAST refers to points east of the Prime Meridian (0 degrees) at Greenwich, England, while WEST refers to points west of the Prime Meridian.

If your data is in the Western Hemisphere, longitude values (the X coordinates) are negative, that is -35° 45' 08". If your data is in the Western Hemisphere but has positive longitudes, your map is displayed flipped or with the east and west directions reversed. See Preparing Spatial Data for an example of this behavior. Applying the WEST argument to the spatial data causes the longitudes to be negated when the data is read in, and the map is displayed correctly.

Note: This argument is ignored when the CARTESIAN or MERGE= arguments are used. [cautionend]

KEEP Argument

KEEP

KEEP specifies that polygonal index data sets are not deleted when the spatial entry is deleted. This option is valid only with the DELETE operation.

MERGE= Argument

MERGE=(<spatial-entry-list.>) <EDGEMATCH <LINKONLY> | OVERLAP> <ZEROMISSING> <ERROR_ROW=integer>

MERGE= lets you build a new spatial entry by referencing two or more existing spatial entries. The dependent data sets for the spatial entries are not actually combined when you use the MERGE argument; the new spatial entry includes them by reference. An error occurs if any of the specified spatial entries do not exist.

You can specify any of the following additional arguments in conjunction with the MERGE= argument:

EDGEMATCH <LINKONLY>: matches common boundaries between the merged spatial entries. Missing values along common boundary chains are filled in where possible by using values from the adjoining spatial data sets. The affected chains data sets are rewritten unless the LINKONLY option is specified, and you cannot reverse the operation.
ZEROMISSING: treats any left/right attribute value of zero as a missing value. Otherwise zero is considered to be a valid value when performing an EDGEMATCH merge.
ERROR_ROW=integer: prints an enhanced error message for the specified spatial data row during an EDGEMATCH merge operation. This option can be useful for determining what caused a specific row to fail to merge. The basic log warning will print the row number for unmatched chains in all of the merged data sets. Any of these chain numbers can be used as the ERRORROW= target.
OVERLAP: merges spatial entries without attempting to match boundaries. The chains data sets for the merged entries are not rewritten. This is the default behavior.

MULT= Argument

MULT=multiplier-value

MULT= specifies a constant value by which the stored spatial data coordinates are multiplied. The default is MULT=1.

Note: This argument is ignored when the MERGE= argument is used. [cautionend]

NODES= Argument

NODES=data-set

NODES= names the SAS data set that contains node definitions for the spatial database. A node is a point on the map, usually representing the intersection of latitude and longitude positions. For example, a node can represent the intersection of two streets.

Note: The NODES= argument is required when you use the CREATE or REPLACE keyword and do not specify the MERGE= argument. [cautionend]

NORTH | SOUTH Argument

NORTH | SOUTH

This argument indicates the hemisphere in which the spatial data points lie. The default is NORTH.

If your data is in the southern hemisphere, latitude values (the Y coordinates) are negative, for example, -45° 12' 33". If your data is in the southern hemisphere, but the latitude values are positive, your map is displayed inverted with the north and south directions reversed. Applying the SOUTH argument to the spatial data causes the latitude values to be negated when the data is read in, and the map is displayed with the correct side up.

Note: This argument is ignored when the CARTESIAN or MERGE= arguments are used. [cautionend]

SPATIAL Statement Examples

Define the Current Spatial Entry

The following code fragment makes MAPS.NC.NC.GISSPA the current spatial entry that is used for subsequent operations:

proc gis cat=maps.nc;
   spatial nc;

Update an Existing Spatial Entry

The following code fragment replaces the existing details data set with MAPS.USAD for the existing MAPS.USA.USA.GISSPA spatial entry:

spatial update maps.usa.usa / details=maps.usad;

Merge Three Existing Spatial Databases

The following code fragment creates a new spatial entry that is named TRIANGLE.GISSPA in the current catalog by merging three existing spatial entries, ORANGE, DURHAM, and WAKE. In this example, each of the spatial entries to be merged is stored in a different library. See Working with Spatial Data for more information about merging.

spatial create triangle / merge=(gmap1.orange.orange,
                                 gmap2.durham.durham,
                                 gmap3.wake.wake);

Top of Page

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