The GIS Procedure

MAP Statement

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

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

Operations

CONTENTS

prints information about the specified map entry to the OUTPUT window, including the following items:

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

PRESENT

creates an HTML file to display a GIS map on the web using ODS and the IMAGEMAPS option.

REPLACE

overwrites the specified map 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 map entry.

For a REPLACE operation, 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 Argument

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

<libref.catalog.>map-entry

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

Options

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 argument with a slash (/). [cautionend]

ACTION=(operation-arguments)

The following list contains descriptions of the ACTION arguments.

COMMAND= 'command-name' | variable

specifies the commands to be run when either a COMMAND or a SYSTEMCOMMAND action is executed in the map. Valid values are:

'command-1 <;command-2; ...>': To specify commands explicitly, enclose them in quotation marks. Separate multiple commands with semicolons.
variable: specifies the variable containing the commands in the linked data set.

The COMMAND= parameter is used only by the COMMAND and SYSTEMCOMMAND type actions and is a required argument. If the action type is COMMAND, COMMAND= refers to a SAS command. If the action type is SYSTEMCOMMAND, it refers to a host operating system command.

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=action-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 option in the MAP statement.

CREATE

add a new action to the map.

DELETE

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

CAUTION:: Use DELETE with care.
The GIS procedure does not prompt you to verify the request before it deletes the action from the map.

FORMULA= <libref.>catalog.entry.type

specifies a formula catalog entry to be used by an FSVIEW action. A FORMULA entry must be a fully qualified three- or four-level name. If the name is three levels, it is assumed to be in the WORK library. FORMULA is used only by the VIEW type action, and it is an optional argument.

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.

IMAGEVAR=variable-name

specifies the name of the variable in the LINK= data set which contains the image to display for the current selected feature. IMAGEVAR is used only by an IMAGE type action, and it is a required argument.

LINK=link-name

specifies an attribute data set link. If the link does not exist, you can create it in the same MAP statement with the ATTRIBUTE= option. A LINK is required for all action types except a SPATIALINFO action.

MAPVAR=<variable-name>

specifies the name of the variable in the LINK= data set containing the three-level name of the map to be opened when a particular feature is selected. MAPVAR is used only by the TYPE=DRILLDOWN type action and is a required 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]

OUT=data-set-name

specifies an output data set. OUT= is required for DATA and PROGRAM actions. It is optional for COMMAND and SYSTEMCOMMAND type actions.

OUTMODE = REPLACE | APPEND | APPEND_NEW

specifies how to the action writes to the OUTPUT data set.

REPLACE: overwrites the existing data set. REPLACE is the default.
APPEND: writes the observations to the end of the existing data set.
APPEND_NEW_: creates a new data set the first time the action is executed, and appends to this data set each additional time the action is executed.

REDISTRICT=variable-name

opens the Redistricting Window to adjust totals in adjoining areas.

REDISTRICTLAYER=layer-name

specifies the name of the polygonal layer to be themed by the redistricting action. REDISTRICTLAYER= is used only by the REDISTRICT type action and is a required argument.

REDISTRICTVAR=variable-name

specifies the name of the variable in the LINK data set upon which the redistricting will be based. REDISTRICTVAR= is used only by the REDISTRICT type action and is a required argument.

RENAME=new-action-name

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

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

REPLACE

replaces the named action, or, if it does not exist, creates a new action with that name.

SCREEN=<libref.>catalog.entry.type

specifies a screen catalog entry to be used by an FSBROWSE action. A SCREEN entry must be a fully qualified three- or four-level name. If the name is three levels, it is assumed to be in the WORK library. SCREEN is used only by the BROWSE type action, and it is an optional argument.

SOURCE='filename' | <libref.>catalog.entry.type | fileref

specifies the location of the source code for a PROGRAM type action. The following are valid locations:

'filename': an external file containing SAS code. The host-path filename must be enclosed in quotation marks.
libref.catalog.entry.type: the three- or four-level name of a catalog entry containing the SAS code. A three-level name is assumed to be in the WORK library. Valid values for type are SOURCE and SCL.
fileref: a one-level name is assumed to be a SAS fileref. If the fileref does not exist, the action is created, and a warning is printed to the log.

The SOURCE parameter is used only by a PROGRAM type action and is a required argument.

SUMMARYVAR=(variable-1 <,variable-2>... | _ALL_)

specifies a list of NUMERIC variables to display in the Redistricting Window when a REDISTRICT type action is executed. Only NUMERIC variables are valid because redistricting sums the values for each new district. Specifying SUMMARYVAR=(_ALL_) displays sums for every numeric variable. SUMMARYVAR is used only by the REDISTRICT type action. The default is _ALL_.

TYPE

used with CREATE to select an action type. The following are valid arguments:

BROWSE: opens an FSBROWSE window on a data set.
COMMAND: runs a SAS command.
DATA: subsets the current selections and write attribute data into a data set.
DRILLDOWN: opens another map associated with the current feature.
IMAGE: displays an image associated with the selected map feature.
PROGRAM: creates a data set and run a SAS program against its observations.
REDISTRICT: opens the Redistricting Window to adjust totals in adjoining areas.
SPATIALINFO: displays the current feature in the Spatial Info Window.
SYSTEMCOMMAND: runs a command from the host operating system.
VIEW: opens an FSVIEW window on a data set.

UPDATE

modifies existing actions in the map that is being updated. Specify the action to be updated with the NAME=action-name argument. You specify NAME=_ALL_ to 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.

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.

AGGREGATE | DISAGGREGATE

AGGREGATE: sets a flag so that polygonal areas with identical ID values are considered as one. For example, if you are selecting from the STATE layer and click on North Carolina, all the Outer Banks islands are also selected.
DISAGGREGATE: sets a flag so that polygonal areas with identical ID values are treated independently. For example, if you are selecting from the STATE layer of the North Carolina map and click on Emerald Isle, only that one island gets selected. DISAGGREGATE is the default.

ATTRIBUTE=(attribute-arguments)

copies, deletes, or updates data links between the chains data set and attribute data sets. The following are the arguments used with ATTRIBUTE:

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.

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.

CREATE

adds a new attribute data link to the map.

DATASET=libref.data-set-name

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

DATAVAR=(variable-name-1 <, ...variable-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.

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.

CAUTION:: Use DELETE with care.
The GIS procedure does not prompt you to verify the request before it deletes the action from the map.

FROM=map-entry

used with the ATTRIBUTE COPY operation, 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.

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]

RENAME=new-link-name

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

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

UPDATE

modifies existing data links in the map that is being updated. Specify the link to be updated with the NAME=link-name argument. Specify NAME=_ALL_ to 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_.

CARTESIAN | LATLON

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

CARTESIAN

data is in an arbitrary rectangular (plane) coordinate system

LATLON

data is 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]

CBACK=color

specifies the background color of the map. CBACK= must specify a predefined SAS color name, and RGB color code in the form CXrrggbb, an HLS color code in the form Hhhhlllss, or a gray-scale color code in the form GRAYll. For more information about color naming schemes, see "SAS/GRAPH Colors" in SAS/GRAPH: Reference. The default map background color is WHITE.

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 operation. [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.

DEGREES	units for LATLON data are measured in decimal degrees.
RADIANS	units for LATLON data are measured in radians. RADIANS is the default.
SECONDS	units for LATLON data are measured in seconds.

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]

FORCE

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

IMAGEMAP =(HTML=(layer-links | ) DEFAULT=link-name)

provides details for building an HTML version of a GIS map through ODS.

Note: The IMAGEMAP= argument is valid only with the PRESENT operation in the MAP statement. [cautionend]

The PRESENT operation uses the SAS Output Delivery System (ODS) to generate an HTML page with aGIF image of the map. The GIF image can be a static image or can contain clickable map points or polygons. Each selectable map feature is associated with a URL. The URL addresses are contained in one or more variables in a SAS data set that is linked to the map.

The following options are used to specify the linked data set and the URL-related variables for specific map layers:

_ALL_ = variable-name: declares that all of the selectable map layers use the URLs stored in the specified data set variable.
HTML = (layer-entry-1 = variable-name <, layer-entry-2=variable-name ...>): associates different URL-related variables with specific layers.
DEFAULT = link-name: specifies the link name for the attribute data set that contains the URL-related variables.

LABEL= libref.data-set | NONE | DELETE| HIDEALL | UNHIDEALL

assigns or removes the specified label data set reference to the map. If the map already has a label data set, the original is deassigned. However, it is not overwritten.

LABEL=<libref.>data-set: assigns the specified data set reference to the map entry. An error occurs if the specified data set does not exist. If the libref is not specified, the default WORK library is used.
LABEL=NONE: unassigns the current label data set from the map entry, but the data set is not deleted.
LABEL=DELETE: unassigns the current label data set from the map entry, and deletes the data set.
LABEL=HIDEALL: hides all of the labels in the target map. HIDEALL does not remove the label data set reference from the map entry.
LABEL=UNHIDEALL: displays all of the labels in the target map. UNHIDEALL does not display labels attached to layers that are not displayed, nor does it display labels that would not be displayed at the current scale of the map.

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 operation. [cautionend]

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

specifies a list of GISLAYER-type entry names that 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 that are removed from the map's current layer list. The layer entries are not deleted. They remain in their respective catalogs.

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

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

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

removes the specified layer(s) from the LAYERSON 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>) | _ALL_

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 LAYERSOFF 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 LAYERSOFF 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 parameters 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 -=, +=, or both. 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.

LEGEND=HIDEALL | UNHIDEALL | REMOVALL

used in conjunction with the MAP UPDATE statement to hide, display, or remove map legends:

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.

CAUTION:: This behavior is immediate and permanent.
You cannot restore the legends and will have to recreate them.

Only one of the LEGEND= options can be specified at a time.

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 might be too small.

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 operation in the ACTION or ATTRIBUTE argument.

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.

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

lists the layers to be selectable when the map opens. All other layers will be unselectable.

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

adds layers to the current list of selectable layers.

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

removes layers from the current list of selectable layers.

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

lists the layers to be unselectable when the map opens. All other layers will be selectable.

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

adds layers to the current list of unselectable layers.

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

removes layers from the current list of unselectable layers.

Details

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, the name of the data set that contains labels for map features, and the names of any other associated SAS data sets.

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 the following:

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

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;

Top of Page