FRONT | BACK

controls how an image label is drawn relative to map features.

FRONT

causes an image label to be drawn over the map features.

BACK

causes an image label to be drawn beneath the map features.

Default FRONT

Note These options do not apply to text labels.

IMAGE='path-name' | <libref.>catalog.entry<.IMAGE> | fileref specifies the location of an image to use as an image label on the map.

'path-name'

specifies a host directory path to an image file.

Example image='C:\My SAS Files\photo.gif'

<libref.>catalog.entry<.IMAGE>

specifies an IMAGE type catalog entry for the image label.

If you omit the library name from the statement, the WORK library is the default.

fileref

specifies an active SAS fileref that points to an external file for an image label.

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 specify a one-level name, the map entry is assumed to be in one of two catalogs. It will be 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.

MAPLABEL Statement 159

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<units>> <, y<units>> <, 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).

y

is the number of units to move the label up (positive numbers) or down (negative numbers).

units

is one of the following values:

PERCENT | PCT

specifies that the X and Y coordinate 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, if both the X and Y coordinates are set to 50, then the label origin remains in the center of the window. Negative values and values greater than 100% are not allowed.

PIXEL

specifies that the X and Y coordinate 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. The shift can be horizontal, vertical, or both so that the label is placed just within the window when the map is opened.

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.

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

offset = ( 10 real, )

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

offset = ( 20 pct, 40 pct )

To set only the Y offset, specify one value preceded by a comma, as in the following example:

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= because 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 Map window, a warning is printed to the log when the map is opened. The label is moved to be within the window.

ONSCALE=(scale <units>)

specifies a map scale at which the label is turned on when the map view is zoomed.

scale

specifies the map scale value at which the label is turned on.

units

specifies the units for the scale value.

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 (kilometers per centimeter).

ENGLISH

sets the scale units to MI/IN (miles per inch).

Default METRIC OFFSCALE=(scale <units>)

specifies a map scale at which the label is turned on off when the map view is zoomed.

scale

specifies the map scale value at which the label is turned off.

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 (kilometers per centimeter).

ENGLISH

sets the scale units to MI/IN (miles per inch).

Default METRIC

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

specifies the horizontal and vertical coordinates for the label. ORIGIN= explicitly positions the label anywhere on the map. Unlike the POSITION= location, the label

MAPLABEL Statement 161

is not centered about this point. The lower left corner of the label is placed at the specified ORIGIN location.

x

specifies the X coordinate (horizontal axis) y

specifies the Y coordinate (vertical axis) units

can be one of the following values:

PERCENT | PCT

specifies that the X and Y coordinate 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, if both the X and Y coordinates are set to 50, then the label origin remains in the center of the window. Negative values and values greater than 100% are not allowed.

PIXEL

specifies that the X and Y coordinate 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. The label shifts horizontally, vertically, or both to be just within the window when the map is opened.

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.

To set only the X coordinate, specify one value with or without a following comma, as in the following examples:

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, as in the following examples:

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, as in the following 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.