The GIS Procedure

MAPLABEL Statement

Applies, modifies, or deletes labels on a map.

MAPLABEL<operation> <option>

Operations

CONTENTS

prints label information to the Output window. If you specify

_ALL_, every label not associated with a layer is printed.
TEXT='string', only labels matching that text are printed. The comparison is case sensitive.
ROW=integer, only the label at that row is printed.

If no labels are output, a NOTE is printed to the log.

CREATE

creates a new label or labels. Unlike CREATE operations for other PROC GIS statements, duplicate labels are allowed.

DELETE

removes the specified labels and, depending on which optional arguments are specified, possibly deletes the label data set. The only valid optional arguments for DELETE are DATASET=, MAP=, LAYER=, TEXT=, IMAGE=, ROW=, and _ALL_. Any others will be ignored.

If you specify

DATASET=data-set-name as the only argument, the label data set is deleted.
MAP=map-entry as the only argument, the label data set reference is removed from the map entry, and the data set is deleted. If you do not specify MAP=, and all of the rows in the label data set are deleted, you are cautioned that any maps using the deleted data set will generate a WARNING when opened.
ROW=, only the label at that data set row is deleted. ROW= and _ALL_ are not allowed together. If you use ROW= and TEXT=, the TEXT= is ignored and the label at that row is deleted.
TEXT='string', every label literal having this exact string is removed from the label data set.

Note: Literal labels are those not associated with a specific layer.
IMAGE=, the specified image is deleted.
_ALL_, every label that is not associated with a layer is removed from the label data set.

Either DATASET= or MAP= is required or no deletions can occur.

Any DELETE operation that deletes all of the rows in the label data set also causes the data set to be deleted. If a data set is deleted, a NOTE is printed to the log. If MAP= is present and the label data set is deleted, the reference to the data set within the map entry is removed.

A note is printed in the log upon completion of a successful deletion.

REPLACE

replaces an existing label specified by TEXT='string' of ROW=. If the label does not exist, a CREATE is performed.

UPDATE

modifies an existing label.

Options

_ALL_

affects the behavior of the following operations:

In a CONTENTS operation, _ALL_ prints every label that is not associated with a layer to the Output window.
In a DELETE operation, _ALL_ deletes every label not associated with a layer.

_ALL_ has no effect on CREATE, REPLACE, or UPDATE operations. If _ALL_ is detected, it is ignored.

_ALL_ cannot be used in the same statement with ROW= or TEXT= options.

ATTACH_TO=MAP | WINDOW

controls the label positioning and is a required argument.

MAP: The label is attached to a location on the map. As you move the map in the window, the label moves with the map.
WINDOW: The label is attached to the map window. It remains fixed relative to the window as you move the map in the window.

COLOR=color-name | CXrrggbb

specifies the text color. The default color is BLACK.

color-name: is a SAS color-name, for example GREEN or RED.
CXrrggbb: is an RGB color, for example CX23A76B.

For more information about color-naming schemes, see "SAS/GRAPH Colors" in SAS/GRAPH: Reference

DATASET=<libref.data-set-name

specifies the label data set to which new labels are appended. If the data set does not exist, it is created.

If you specify a one-level data set name, the WORK library is assumed. If you specify both DATASET= and MAP=, and the map already references a label data set, the data set names are compared. If they are not the same and FORCE was not specified, a warning is printed, and the run group is terminated.

FONT=fontname | DEFAULT

fontname

specifies the font for the label text.

The following are some examples:

FONT = 'Times New Roman-12pt-Roman-Bold'
FONT = 'Display Manager font'
FONT = 'Sasfont (10x15) 10pt-9.7pt-Roman-Normal'

If the specified font is not found when the map is opened, the default system font is substituted and a note is printed to the log.

DEFAULT

assigns the default font to the label.

FORCE

replaces the existing label data set reference in a map when both DATASET= and MAP= are specified. If the map already references a label data set, its data set name is compared to the name specified with DATASET=. If they are not the same, the FORCE option causes the map's label data set reference to be overwritten and a note printed to the log. The map's original label data set is not deleted.

FRONT | BACK

FRONT	causes an image label to be drawn over the map features. This is the default for image labels.
BACK	causes an image label to be drawn beneath the map features.

These options do not apply to text labels.

IMAGE='pathname' | <libref.>catalog.entry<.image> | fileref

specifies the location of an image to use as an image label on the map.

'pathname'

enables you to enter a host directory path to an image file. For example,

IMAGE='C:\My SAS Files\photo.gif'

<libref.>catalog.entry<.image>

uses a .IMAGE type catalog entry for the image label. If you omit the library name from the statement, the WORK library is the default.

fileref

enables you to use an external file for an image label by specifying an active SAS fileref. The host directory path for this fileref is written to the label data set, not to the fileref.

MAP=<libref.catalog>map-entry

indicates the map entry on which to display the labels. If you indicate 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.

If the specified map entry already references a label data set, new labels are appended to that data set.

If the map entry does not reference a label data set, you must provide a label data set name with the DATASET= option. The labels are written to that data set, and the data set is then assigned to the specified map.

For the MAPLABEL statement, either MAP= or DATASET= is required. If both are present and the map already has a label data set, its name must match the name specified in the DATASET= option. One exception is if the FORCE option is also used. In that case, the label data set specified by DATASET= is assigned to the map entry. The map's original label data set is unassigned but not deleted.

OFFSET=(<x> <, y> <<,> units> | <x <units>> <, y units>>)

specifies the distance to move the entire label. X is the number of units to move the label right (positive numbers) or left (negative numbers), and Y is the number of units to move the label up (positive numbers) or down (negative numbers). For example:

To set only the X offset, specify one value, with or without a following comma:

OFFSET = ( 10 real, )

To set both the X and Y offset, specify two values, with or without a comma separating them:

OFFSET = ( 20 pct, 40 pct )

To set only the Y offset, specify one value preceded by a comma:

OFFSET = ( ,-30 pct )

OFFSET= is usually used in conjunction with POSITION= to adjust the position of a label. Moves are relative to the location specified by POSITION=, with OFFSET=(0,0) representing the initial position. You can also apply OFFSET= to the default label position.

The following restrictions apply to the OFFSET= argument:

When both ORIGIN and OFFSET are used, the same units must be specified for both. If no units are specified in the OFFSET= arguments, the unit entered in the ORIGIN= option is used.
OFFSET= is unnecessary with ORIGIN= since ORIGIN= explicitly positions the label and requires no further adjustment. However, if you specify both options, the values of OFFSET= are added to the values of ORIGIN=, and the label is positioned accordingly.
If the resulting location is outside of the GIS window, a WARNING is printed to the log when the map is opened, and the label is moved to be within the window.

ONSCALE=(scale <units>)

scale

specifies a map scale where the label is turned on or off when the map view is zoomed.

units

specifies the units for ONSCALE.

real-units/map-units: enables you to specify various combinations of units. Valid values are KM, M, CM, MI, FT, and IN. Real-units is typically KM, M, MI, or FT, and map-units is usually either CM or IN. Long forms of the unit names, for example KILOMETERS or INCH (singular or plural), are also acceptable.
METRIC: sets the scale units to KM/CM. This is the default if units are omitted.
ENGLISH: sets the scale units to MI/IN.

OFFSCALE=(scale <units>)

scale

specifies a map scale where the label is turned on or off when the map view is zoomed.

units

specifies the units for OFFSCALE.

real-units/map-units: enables you to specify various combinations of units. Valid values are KM, M, CM, MI, FT, and IN. Real-units is typically KM, M, MI, or FT, and map-units is usually either CM or IN. Long forms of the unit names, for example KILOMETERS or INCH (singular or plural), are also acceptable.
METRIC: sets the scale units to KM/CM. This is the default if units are omitted.
ENGLISH: sets the scale units to MI/IN.

ORIGIN=(<x> <, y> <,> <units> | <x <units>> <, y units>>)

specifies the X and Y coordinates for the label. ORIGIN= explicitly positions the label anywhere on the map. Unlike the POSITION= location, the label is not centered about this point. The lower left corner of the label is placed at the specified ORIGIN location.

x indicates the X-coordinate (horizontal axis)
y indicates the Y-coordinate (vertical axis)

Use the following units when attaching labels to the map:

REAL: X and Y values are real-world coordinates based on the underlying spatial data. Negative values can be used to signify the western or southern hemispheres if the spatial data contains them.
PERCENT | PCT: refers to a percentage of the distance from the lower left corner of this bounding box to the label origin. All SAS/GIS maps have a rectangular bounding box that encompasses the extreme limits of the spatial data as subset by the GIS coverage. When a map is first opened in the GIS Map window, the map scale is set to display this entire box in the window. When the map is resized, the label remains in the same relative location, for example, for x=50, y=50 the label origin remains in the center of the map. Negative values and values greater than 100% can be used to place the origin outside of the coverage extents.

Use the following units when attaching labels to the window:

PIXEL: X and Y values are screen coordinates using pixels. The lower left corner of the window is 0, 0. Negative values are not allowed. If a specified pixel value runs the label outside of the window, the label is shifted horizontally, vertically, or both to be just within the window when the map is opened.
PERCENT | PCT: X and Y values are a percentage of the distance from the lower left corner of the map window to the label origin. When the window is resized, the label remains in the same relative location. For example, for x=50, y=50 the label origin remains in the center of the window. Negative values and values greater than 100% are not allowed.

To set only the X coordinate, specify one value with or without a following comma. For example:

ORIGIN = ( 10 pixels, )

ORIGIN = ( 10 pixels )

To set both the X and Y coordinates, specify two values with or without a comma separating them. The units can be specified for both X and Y or once at the end. For example:

ORIGIN = ( 10 pct, 40 pct )

ORIGIN = ( 10 pct  40 pct )

ORIGIN = ( 10  40  pct )

ORIGIN = ( 10, 40, pct )

To set only the Y coordinate, specify one value preceded by a comma. For example:

ORIGIN = ( , 20 pct )

ORIGIN= overrides the POSITION= option if both options are present. Although using the OFFSET= option with the ORIGIN= option is unnecessary, if you also specify OFFSET=, it is applied after the ORIGIN= request has been processed.

If the specified origin or origin plus offset is outside of the overall map bounding box, a warning is printed to the log. No warning is issued if the label runs out of the box, however.

OVERLAP | NOOVERLAP

specifies how labels are treated when they overlap.

OVERLAP: All labels you create with the option will be displayed even if they conflict with other labels.
NOOVERLAP: some of the conflicting labels will be suppressed until you zoom in more closely. This is the default setting.

assigns a single label to a position on the map relative to the map's bounding box.

If the label is attached to the map, the label position is determined using the spatial data bounding box, that is the upper, lower, right and left edges of the coverage extents. If the label is attached to the window, the window edges are used.

The following arguments determine the vertical position of the label:

TOP: places the label along the upper edge of the map or window.
MIDDLE: places the label halfway between the top and bottom edges of the map or window.
BOTTOM: aligns the label with the bottom edge of the map or window.

The following arguments determine the horizontal position of the label:

LEFT: starts the label at the left edge of the map or window.
CENTER: places the label halfway between the left and right edges of the map or window.
RIGHT: aligns the end of the label with the right edge of the map or window. The label is centered horizontally and vertically at the computed position point. You can adjust the initial label position with the OFFSET= option.

ROW=integer

specifies a particular label in the data set to UPDATE, REPLACE, DELETE or print CONTENTS. Not valid for CREATE operations.

TEXT=<'string'

specifies the text for a literal label.

For REPLACE, UPDATE, DELETE or CONTENTS operations, string specifies a search string used to locate a specific target label. When TEXT='string' is used to search for a label, string is case sensitive, and an exact match to the value of the search string must be found. For example, TEXT='Paris' will ignore a label having PARIS as its text. It will also ignore a label having 'Paris Metro' as its text.

If ROW= and TEXT= are both present in a REPLACE or UPDATE statement the 'string' entered with TEXT= is not a search string. It becomes the new text for the label at the specified ROW number.

TRANSPARENT | NOTRANSPARENT

TRANSPARENT

enables the map features to show though the label's bounding box. This is the default if not specified.

NOTRANSPARENT

blocks the display of map features within the label's rectangular bounding box.

These options apply to text labels and image labels stored as catalog entries. They have no effect on image labels stored in an external file.

Top of Page