Using Spatial Data with SAS/GIS Software

MAP Statement

MAP operation <libref.catalog.>map-entry </ options>;

Description

Displays information about the contents of a map entry
Creates a new map entry, replaces an existing map entry, or modifies the characteristics of a previously created map entry
Deletes a map entry.

A map entry is a SAS catalog entry of type GISMAP that defines the displayed features of a map. The definition specifies which layers the map contains and which coverage of the spatial database is used. The map entry also stores legend definitions and action definitions for the map, information about the projection system used to display the map, and the names of any associated SAS data sets and of the data set that contains labels for map features.

MAP Statement Operations

In the MAP statement, operation can be one of the following:

CONTENTS
CREATE
DELETE
REPLACE
UPDATE

The following list contains descriptions of the MAP statement operations:

CONTENTS

Prints information about the specified map entry to the OUTPUT window, including

A list of the data objects (coverage and layer entries and label data set) that compose the map entry
Details of the spatial database as provided by the COVERAGE CONTENTS and SPATIAL CONTENTS statements
Details of the layer definitions as provided by the LAYER CONTENTS statement
Lists of the projection method that is used to display the map
A list of associated data sets and link names
A list of the GIS actions that have been defined for the map
A list of legend definitions for the map.

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

CREATE

Creates a new map entry that defines a map that can be displayed in the GIS Map window.

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

For a MAP CREATE statement, you must also specify the COVERAGE= and LAYERS= arguments.

DELETE

Removes the specified map entry.

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

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

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

REPLACE

Overwrites the specified map entry. The MAP REPLACE statement has the effect of canceling the previously issued MAP CREATE statement for the specified map entry.

For a MAP REPLACE statement, you must also specify the COVERAGE= and LAYERS= options.

UPDATE

Modifies the specified map entry by applying new values for specified arguments.

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

Map-Entry Name

In the MAP statement, the map entry identifies the map entry you want to create, delete, replace, or update. The general form of the argument is

<libref.catalog.>map-entry

If you specify a one-level name, the map entry is assumed to be in the catalog that is specified in the PROC GIS statement or in the most recently issued CATALOG statement. An error occurs if no catalog has previously been specified.

The map-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).

MAP Statement Optional Arguments

When you specify CREATE, REPLACE, or UPDATE for the MAP operation, you can specify one or more of the following options following the map-entry name.

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

CARTESIAN | LATLON
COVERAGE=<libref.catalog.>coverage-entry
DEGREES | RADIANS | SECONDS
DESCRIPTION='string'
DETAILS | NODETAILS
LAYERS=(layer-entries)
LAYERS+=(layer-entries)
LAYERS-=(layer-entries)
LAYERSON=(layer-entries) | _ALL_
LAYERSON+=(layer-entries)
LAYERSON-=(layer-entries)
LAYERSOFF=(layer-entries) | _ALL_
LAYERSOFF+=(layer-entries)
LAYERSOFF-=(layer-entries)
MULT=multiplier-value
LABEL= libref.data-set | NONE
ACTION=(operation-arguments)
ATTRIBUTE=(attribute-arguments)
RENAME_LAYER old-name = new-name
LEGEND=HIDEALL | UNHIDEALL | REMOVALL
FORCE
NOWARN

The following list contains descriptions of additional MAP statement options:

CARTESIAN | LATLON

Specifies the coordinate system used for the displayed spatial data. The default is LATLON.

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

Note: The map entry must use the same coordinate system as the spatial entry from which the map is derived. If the spatial entry specifies the CARTESIAN coordinate system, then you must also specify the CARTESIAN argument for the MAP statement. If the spatial entry specifies the LATLON coordinate system, then you must also specify the LATLON argument for the MAP statement. [cautionend]

COVERAGE=<libref.catalog.>coverage-entry

Specifies the coverage entry to which the map refers. The coverage determines the geographic extent of the map.

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

DEGREES | RADIANS | SECONDS

Specifies the coordinate units for the displayed spatial data when the coordinate system is geographic (LATLON). The default is RADIANS.

The unit system that you select defines the allowable range for coordinate values. For example, if you specify DEGREES, then all X coordinate values must be in the range -180 to 180, and all Y coordinate values must be in the range -90 to 90.

DESCRIPTION='string'

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

DETAILS | NODETAILS

Specifies whether detail coordinates are read for the entire map. The default is NODETAILS.

Note: You can use the LAYER statement's DETAILS and DETAILON= options to control the display of detail coordinates for a particular layer. The MAP statement's DETAILS option overrides the LAYER statement's DETAILS option. [cautionend]

LAYERS=(<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Specifies a list of GISLAYER-type entry names. The specified layers form the complete list of layers in the map entry. If the map entry already contains a list of layers, they are replaced by these layers.

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

LAYERS+= (<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Specifies a list of GISLAYER-type entry names. These layers are added to the map's current layer list.

LAYERS-= (<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Specifies a list of GISLAYER-type entry names. These layers are removed from the map's current layer list. However, the layer entries are not deleted. They remain in their respective catalogs.

LAYERSON= (<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Specifies a list of GISLAYER-type catalog entries that will be turned on for this map. All other layers will be turned off. Any on-scale/off-scale settings are deactivated. Specifying LAYERSON=(_ALL_) turns all layers on.

LAYERSON+= (<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Adds the specified layer(s) to the LAYERSON list and deactivates any on-scale/off-scale settings for the specified layer(s).

LAYERSON-= (<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Removes the specified layer(s) from the LAYERS ON list and deactivates any on-scale/off-scale settings for the specified layer(s).

LAYERSOFF= (<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Specifies a layer (or list of layers) to be turned off for this map. All other layers are turned on. Any on-scale/off-scale settings are deactivated. Specifying LAYERSOFF=(_ALL_) turns all layers off.

LAYERSOFF+= (<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Adds the specified layer(s) to the "LAYERS OFF" list and deactivate any on-scale/off-scale settings for the specified layer(s).

LAYERSOFF-= (<libref.catalog.>layer-entry-1 <, ..., <libref.catalog.>layer-entry-n>)

Removes the specified layer(s) from the "LAYERS OFF" list and deactivates any on-scale/off-scale settings for the specified layer(s).

Note: The following information applies to the LAYERSON and LAYERSOFF options:

If a layer in any of the lists does not exist in the map, a warning is issued and that layer is ignored. (A missing layer does not end the current RUN-group processing.) Each layer is evaluated individually, so if other layers are valid they are toggled appropriately.
If a layer is in both the LAYERSON list and the LAYERSOFF list, this condition generates a warning and ends that RUN-group.
If one of the LAYERS options is specified in addition to LAYERSON or LAYERSOFF, the LAYERS parameter are processed first. Therefore, if a layer is removed from the map by using the LAYERS parameter, it cannot be referenced in a LAYERSON/LAYERSOFF parameter in that same statement. This action generates a warning, but the RUN-group processing does not stop.
If both LAYERSON and LAYERSOFF are used in the same statement, both parameters must specify -= and/or +=. Specifying both LAYERSON=(...) and LAYERSOFF=(...) in the same statement causes a conflict, and therefore is not allowed.
The _ALL_ option cannot be mixed with layer names, that is, _ALL_ must appear by itself.
_ALL_ cannot be used with either the += or the -= operators.

MULT= multiplier-value

Specifies a constant integer value by which spatial data coordinates are multiplied when the data are displayed. The default is MULT=1E7. If the unit multiplier is too large, it is recomputed when the map is opened, and a note is printed to the SAS log showing the new value. If your map opens and appears to be empty, your MULT value may be too small.

LABEL= <libref.data-set> | NONE assigns or removes a label data set reference. LABEL= <libref.data-set>

Assigns the specified label data set to the map. If the map already has a label data set, the original is deassigned. However, it is not overwritten. LABEL=NONE deassigns the current label data set from the map entry, but the data set is not deleted.

ACTION= (arguments)

Lets you copy, delete, or update GIS actions that are associated with a map entry. The arguments that are used with ACTION are

COPY
DELETE
UPDATE
NAME=action-name | _ALL_
WHEN= OFF | IMMEDIATE | DEFER
FROM=map-entry
RENAME=new-action-name

The following list contains descriptions of the ACTION options:

COPY

Copies existing actions from one map entry to another. Specify the map entry that contains the actions to be copied with the FROM=map-entry argument. The actions are copied to the map that is specified in the MAP statement.

Specify the actions to be copied with the NAME=link-name argument. If you specify NAME=_ALL_ you copy all actions in the specified map. Existing actions in the map to be updated are not overwritten unless you specify the FORCE argument.

DELETE

Removes an existing action from the map entry. Specify the action to be deleted with the NAME=action-name argument. If you specify NAME=_ALL_, you delete all actions. Use the NOWARN argument in the MAP statement to suppress messages when an action is not found.

UPDATE

Modifies existing actions in the map that is being updated. Specify the action to be updated with the NAME=action-name argument. If you specify NAME=_ALL_ , you update all actions. NAME= is required for UPDATE.

If you specify a single action, you can use the RENAME=new-action-name argument to change the link name. You cannot use RENAME if you specify NAME=_ALL_.

You can also change the action's execution settings with the WHEN argument.

NAME=action-name | _ALL_

Specifies the action to be copied, deleted, or updated. action-name identifies a single action, while _ALL_ specifies all actions.

Note: You cannot specify NAME=_ALL_ if you are using ACTION UPDATE with the RENAME argument. [cautionend]

WHEN= OFF | IMMEDIATE | DEFERRED

Used with UPDATE to change the execution setting of the specified action.

OFF: The action is not executed when a layer feature is selected.
IMMEDIATE: The action is executed as soon as a layer feature is selected.
DEFERRED: The action's execution must be performed explicitly after a layer feature has been selected.

FROM=map-entry

Used with the ACTION argument COPY operation, FROM= specifies the source map entry that contains actions to be copied. Specify the actions to be copied from the map with the NAME=action-name argument.

RENAME=new-action-name

Renames the link that is specified in the NAME=action-name for UPDATE.

Note: You cannot specify RENAME if you have also specified NAME=_ALL_. [cautionend]

ATTRIBUTE

ATTRIBUTE lets you copy, delete, or update data links. The arguments used with ATTRIBUTE are

CREATE
COPY
DELETE
UPDATE
NAME=link-name | _ALL_
FROM=map-entry
RENAME=new-link-name
DATASET=libref.data-set
COMPOSITE=(composite-name-1 <,...,composite-name-n>)
DATAVAR=(var-name-1 <,...,var-name-n>)

The following list contains descriptions of the ATTRIBUTE arguments:

CREATE

Adds a new attribute data link to the map.

COPY

Copies existing attribute data links from one map entry to another. Specify the map entry that contains the links to be copied by using the FROM=map-entry argument. The links are copied to the map that is specified in the MAP statement.

Specify the link to be copied with the NAME=link-name option. If you specify NAME=_ALL_, you copy all links in the specified map. Existing links in the map to be updated are not overwritten unless you specify the FORCE option in the MAP statement.

DELETE

Removes an existing attribute data link from the map entry. Specify the link to be deleted with the NAME=link-name argument. If you specify NAME=_ALL_, you delete all data links. Use the NOWARN option in the MAP statement to suppress messages when a link is not found. This does not delete the attribute data set, only the link.

UPDATE

Modifies existing data links in the map that is being updated. Specify the link to be updated with the NAME=link-name argument. If you specify NAME=_ALL_, you update all data links. NAME= is required for the UPDATE operation.

If you specify a single link, you can use the RENAME=new-link-name argument to change the link name. You cannot use RENAME if you specify NAME=_ALL_.

NAME=link-name | _ALL_

Specifies the attribute data link to be copied, deleted, or updated. link-name identifies a single data link, while _ALL_ specifies all data links.

Note: You cannot specify NAME=_ALL_ if you are using UPDATE with the RENAME argument. [cautionend]

FROM=map-entry

Used with the ATTRIBUTE COPY operation, FROM= specifies the map entry that contains data links to be copied. Specify the links to be copied from the map with the NAME=link-name argument.

RENAME=new-link-name

Renames the link that is specified in the NAME=link-name for the UPDATE operation.

Note: You cannot specify RENAME if you have also specified NAME=_ALL_. [cautionend]

DATASET=libref.data-set

Specifies the attribute data set when you create a new key link.

COMPOSITE=(composite-name-1 <,...composite-name-n>)

Lists spatial composite names when you create a new key link. These composites are paired with the attribute data set variables that are named in the DATAVAR= option. If the composite names and the data set variable names are the same, you can just specify them once with either the COMPOSITE= or DATAVAR= lists, and those names will be used for both.

DATAVAR=(varname-name-1 <,...var-name-n>)

Lists attribute data set variables when you create a new key link. These variables are paired with the spatial composites that are named in the COMPOSITE= option. If the data set variable names and the composite names are the same, you can just specify them once with either the COMPOSITE= or DATAVAR= lists, and those names will be used for both.

RENAME_LAYER old-name=new-name

Changes the name of an existing layer in the map that is being updated. This argument also changes the name of the layer entry in the catalog.

If other maps use the renamed layer, you must issue a MAP UPDATE statement for those maps as well.

LEGEND=

Use the LEGEND option with the MAP UPDATE statement to hide, display, or remove map legends. The following list contains details on the options that you can use with the LEGEND option:

HIDEALL: Causes all existing legends to be hidden (not displayed) when the map is opened.
UNHIDEALL: Causes all existing legends to be displayed when the map is opened.
REMOVEALL: Removes all of the existing legends from the map. This behavior is immediate and permanent. You cannot restore the legends and will have to recreate them.

You can specify only one of the legend options at a time.

FORCE

Specifies that existing actions or attribute links may be overwritten during copy operations. Use this argument with the COPY argument in the ACTION or ATTRIBUTE argument.

NOWARN

Specifies that messages are not to be issued about actions or attribute links that are not found during deletion. Use this argument when you specify the DELETE argument in the ACTION or ATTRIBUTE argument.

MAP Statement Examples

Define a new map

The following code fragment creates an entry named STORES of type GISMAP in the current catalog. The map is based on the coverage defined in the GISCOVER entry named MALL in the current catalog and uses the GISLAYER entries STORE, FIRE, INFO, PHONE, and RESTROOM in the current catalog.

map create stores / coverage=mall 
                    layers=(store, fire, info, phone, restroom);
run;

Update an existing map definition

The following code fragment updates the MAPS.USA.USA.GISMAP entry to use detail data when the map is displayed:

map update maps.usa.usa / details;
run;

Copy attribute data set links

The following code fragment copies the SIMPLUSR attribute link from GISSIO.SIMPLUS.SIMPLE to WORK.SIMPLE.SIMPLE:

proc gis;
   map update work.simple.simple /
       attribute = (name=simplusr 
                    copy from=gissio.simplus.simple);
   run;

Chapter Contents
Previous
Next
Top of Page