The GIS Procedure

SPATIAL Statement

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, modifies the characteristics of an existing spatial entry, or deletes a spatial entry.

Example 1: Define the Current Spatial Entry

Example 2: Update an Existing Spatial Entry

Example 3: Merge Three Existing Spatial Databases

Syntax

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

Summary of Optional Arguments

CARTESIAN | LATLON

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

CHAINS=data-set

names the SAS data set that contains chain definitions for the spatial database.

DEGREES | RADIANS | SECONDS

specifies the coordinate units for the stored spatial data when the coordinate system is geographic.

DESCRIPTION='string'

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

DETAILS=data-set

names the SAS data set that contains detail definitions for the spatial database.

EAST | WEST

specifies the hemisphere in which the spatial data points lie.

KEEP

specifies that polygonal index data sets are not deleted when the spatial entry is deleted.

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

builds a new spatial entry by referencing two or more existing spatial entries.

MULT=multiplier-value

specifies a constant value by which the stored spatial data coordinates are multiplied.

NODES=data-set

names the SAS data set that contains node definitions for the spatial database.

NORTH | SOUTH

indicates the hemisphere in which the spatial data points lie.

Required Argument

<libref.catalog.>spatial-entry: specifies the spatial (GISSPA) entry that you want to create, replace, update, delete, or make the current 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.

Operations

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 that does not include an operation keyword.

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

An error occurs if the specified spatial entry does not exist.

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

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

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.
The SPATIAL CREATE statement does not overwrite existing spatial entries. An error occurs if a spatial entry with the specified name already exists. Use SPATIAL REPLACE to replace an existing entry.

Requirement:For the CREATE operation, you must also specify both the CHAINS= and NODES= arguments or the MERGE= argument.

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

Restriction:KEEP is the only additional argument (other than the spatial entry name) that can be used with the DELETE operation.

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.

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

Requirement:For the REPLACE operation, you must specify both the CHAINS= and NODES= arguments or the MERGE= argument.

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.

Options

When you specify CREATE, REPLACE, or UPDATE for the operation argument, you can specify one or more of the following additional optional arguments. When you specify DELETE for the operation argument, only the KEEP option is allowed. Separate the list of arguments from the spatial entry name with a slash (/).

CARTESIAN | LATLON

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.

Default:LATLON

Interaction:The CARTESIAN and LATLON arguments are ignored when the MERGE= argument is used.

CHAINS=data-set: 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.

DEGREES | RADIANS | SECONDS: specifies the coordinate units for the stored spatial data when the coordinate system is geographic (LATLON).

Default:RADIANS

Interaction:This argument is ignored when the CARTESIAN or MERGE= arguments are used.

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

Default:The default description is blank.

DETAILS=data-set: names the SAS data set that contains detail definitions for the spatial database. The endpoints of a chain are nodes. Details are the intermediate points along a chain between the nodes that delineate 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: specifies the hemisphere in which the spatial data points lie. EAST refers to points east of the Prime Meridian (0 degrees longitude) 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.

Default:EAST

Interaction:This argument is ignored when the CARTESIAN or MERGE= arguments are used.

KEEP: specifies that polygonal index data sets are not deleted when the spatial entry is deleted.

Restriction:This option is valid only with the DELETE operation.

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

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

Default:OVERLAP

MULT=multiplier-value: specifies a constant value by which the stored spatial data coordinates are multiplied.

Default:1

Interaction:This argument is ignored when the MERGE= argument is used.

NODES=data-set: names the SAS data set that contains node definitions for the spatial database. Nodes are the endpoints of map chains. A node can also be a single map feature represented by a point. A single node can be the endpoint for multiple chains, as at a street intersection.

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

NORTH | SOUTH: indicates the hemisphere in which the spatial data points lie. If your data is in the southern hemisphere (below the equator), 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. The map is displayed with the correct side up.

Default:NORTH

Interaction:This argument is ignored when the CARTESIAN or MERGE= arguments are used.

Details

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.

Examples

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

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

Example 3: 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);