The GIS Procedure

LAYERLABEL Statement

Applies, modifies, or deletes labels associated with a specific layer.

LAYERLABEL operation <options>;

Operations

CONTENTS

prints label information to the Output window. If you specify

LAYER=, all labels associated with the specified layer are printed.

Note: If LAYER= is omitted, every label associated with all layers in the map are printed.
_ALL_, every label in the data set associated with a layer is printed.
ROW=integer, only the label at that row is printed.
TEXT='string', every label whose text matches the value of 'string' is printed. The text comparison is case sensitive.

If no labels are printed, 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=, ROW=, IMAGE=, 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 you have deleted all the rows in the label data set, you are cautioned that any maps using the deleted data set will generate a WARNING when opened.
TEXT='string', every literal label 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.
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.
_ALL_, every label associated with any layer is deleted. _ALL_ and LAYER= cannot be used together.
LAYER=, every label associated with this layer is deleted.

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

Any DELETE operation that completely empties 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 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 the labels for the specified layer or the specified label.

If you specify

LAYER=, the labels associated with that layer are replaced. If the specified layer has no labels, a CREATE is performed.
TEXT='string', the existing literal label with that string is replaced. If no label exists, a CREATE is performed.

UPDATE

updates the labels for the specified layer or the specified label.

If you specify

LAYER=, the UPDATE operation is limited to that layer's labels only. If the layer you specify has no labels, an ERROR is printed.
TEXT='string', the existing literal label you specify is modified. If you do not specify TEXT='string', an ERROR is printed.

Options

When you specify CONTENTS, CREATE, REPLACE, or UPDATE for operation in a LAYERLABEL statement, you can specify one or more additional arguments after the layer entry name.

_ALL_

affects the CONTENTS and DELETE operations as follows:.

In a CONTENTS operation, _ALL_ prints every label associated with a layer to the Output window.

In a DELETE operation, _ALL_ deletes every label associated with a layer.

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

Note: _ALL_ cannot be used in the same statement with ROW= or TEXT= options. [cautionend]

ATTRIBUTE_VARIABLE=link.variable

specifies a variable in an attribute data set that supplies label text for the layer.

The link portion of the argument is an attribute data set that is read to get the text string for each map feature to be labeled.

For each chain in the specified layer, the row number of its attribute data in the link data set is determined. The value on that row for the specified variable is used for the label text. The following restrictions apply to the ATTRIBUTE_VARIABLE argument:

MAP= is required because it contains the linked attribute data set names. The link name must already exist in the map entry.
The specified variable must already exist in the link data set.

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.

COMPOSITE=composite-name

specifies a GIS composite that references a variable in a GIS spatial data set. This option is used to create labels on features in a specific map layer.

The label for each feature in the specified layer is created by first determining the row number of each map feature to be labeled. The value of the composite's associated variable for that row is then used as the label for that feature. For example, the chain whose row number in the chains data set is 35 would be labeled with the composite variable's value from row 35. The following restrictions apply to the COMPOSITE argument:

COMPOSITE cannot be used with SAS_VARIABLE or ATTRIBUTE_VARIABLE options.
MAP=map-entry is required because the map entry contains the spatial data set names.
The specified composite must already exist in the map entry.

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=font-name

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'

DEFAULT

assigns the default font to the label. If FONT= is omitted entirely, this is assumed. If the fontname specified for the label is not found when the map is opened, the default system font is substituted and a note is printed to the log.

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=<libref.>catalog.entry | 'pathname'

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

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

LAYER=<libref.catalog>layer-entry

specifies the name of the layer with which to associate the label. The label is displayed when this layer is turned on. The labels are also placed adjacent to the features in this layer as indicated by the POSITION= option.

LAYER= is a required argument for the CREATE, REPLACE, and UPDATE operations.

The layer entry name is determined by the following rules:

A complete three-level name entered as libref.catalog.layer-entry is used as-is.
A one-level entry name can be specified. If you previously set a default libref and catalog with a PROC GIS CATALOG statement, they are used for the layer name.
If you specify a one-level layer name, and the default assigned by a CATALOG statement is used, SAS/GIS checks to make sure the layer name matches the libref and catalog in the MAP= option. If they do not match, a WARNING is printed and the statement is ignored.
If no default libref and catalog are active, but the MAP= option is present, that map libref and catalog is used for the layer name. A NOTE is printed to the log.

MAP=<libref.catalog>map-entry

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

MAP= is a required argument.

OFFSCALE=(<label-off-scale> <real-units/map-units | METRIC | ENGLISH>)

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.

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

specifies the distance to shift the entire label from its default location. x is the number of pixels to move the label right (positive numbers) or left (negative numbers), and y is the number of pixels to shift 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 pixels, )

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

OFFSET = ( ,-30 pixels, )

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

OFFSET = ( 20 pixels, 40 pixels )

ONSCALE=(<label-on-scale> <real-units/map-units | METRIC | ENGLISH>)

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.

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.

POINTER

POINTER	draws a leader line from the label to its associated map feature.
NOPOINTER	places the label on the map with no leader line. NOPOINTER is the default if POINTER is not present.

POSITION= (integer-1, ..., integer-8)

controls where the labels are placed about the features when you are labeling multiple features associated with a layer.

The new labels are associated with the map features displayed in that layer. The labels are positioned around those features to minimize conflicts and collisions. The POSITION option allows you to specify the order in which the label positions are tried. The following illustrates the syntax of POSITION=:

POSITION=(<TOP_LEFT | TL => integer <,>

<TOP_CENTER | TC => integer <,>

<TOP_RIGHT | TR => integer <,>

<MIDDLE_LEFT | ML => integer <,>

<MIDDLE_RIGHT | MR => integer <,>

<BOTTOM_LEFT | BL => integer <,>

<BOTTOM_CENTER | BC => integer <,>

<BOTTOM_RIGHT | BR => integer <,>)

The following diagram shows all of the positions around a point (X) where a label can be placed:

TL	TC	TR
ML	X	MR
BL	BC	BR

The default position values for these locations are shown in the following diagram:

6	4	1
7	X	2
8	5	3

For example, the first attempt to place the label is made in the number 1 position, and then in the number 2 position, with the number 8 position last. If the label cannot be placed in any of these positions without a collision, and if OVERLAP is not specified, the label will not be displayed when the map is opened, and a warning will be printed to the log at that time.

The following example assigns the position values as indicated:

POSITION=(3 1 4 7 8 5 2 6)

3	1	4
7	X	8
5	2	6

The following restrictions apply to the POSITION argument:

If the keywords, for example, TOP_LEFT, are omitted and only the integer value specified, the values are assigned in left-to-right, top-to-bottom sequence. However, all eight of the values are required.
The OFFSET= option has no effect on this form of the POSITION option. If it is encountered, it is ignored.
Duplicate numbers are not allowed. You cannot have two locations numbered as 5. The allowed integer values are 1-8, inclusive.
The position values are stored in the map entry. There is no need to use them in multiple LAYERLABEL statements. The last POSITION= values specified will be the ones used to determine the locations for the point label when the map is opened.

ROW=integer

specifies a particular label in the data set to update, replace, delete or print. It is not valid for the CREATE operations.

SAS_VARIABLE=variable-name

specifies a variable in the map's chains data set that is used to create labels on features in a specific map layer.

The label for each feature in the specified layer is created by first determining the row number of each map feature to be labeled. The value of the variable for that row is then used as the label for that feature. For example, the chain whose row number in the chains data set is 35 would be labeled with the variable's value from row 35. The following restrictions apply to the SAS_VARIABLE argument:

SAS_VARIABLE cannot be used with COMPOSITE or ATTRIBUTE_VARIABLE options.
MAP=map-entry is required because the map entry contains the spatial data set names.
The specified variable must already exist in the chains data set.

TEXT='string'

specifies the text for a literal label, that is, one not associated with a specific map layer.

For REPLACE, UPDATE, DELETE or CONTENTS operations, string specifies a search string used to locate a specific target label if ROW= is not present. 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 used in a REPLACE or UPDATE statement, the 'string' entered with TEXT is not a search string. It becomes a replacement string for the label at the specified ROW number.

TRANSPARENT | NOTRANSPARENT

TRANSPARENT

enables the map features to show through 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