Annotate Variables

Annotate Variables

When an Annotate data set is processed , the Annotate facility looks at the values of specific variables in order to draw graphics. This section describes all of the Annotate variables in alphabetical order. Not all variables are used with all functions. Refer to the description of the individual functions in Annotate Functions on page 615 for more information about how each variable is used with each function. For a summary of Annotate variables and their uses, see Table 24.1 on page 591.

ANGLE Variable

Specifies the angle at which the graphics output is drawn.

Type: numeric

Default: function dependent

Syntax

ANGLE=0 360;

Functions

The ANGLE variable is function dependent.

If function is	then the ANGLE variable specifies
LABEL	the baseline angle of the character string with respect to the horizontal. With the LABEL function, the pivot point is at (X,Y) and the direction of rotation is counterclockwise. The default value is 0.
PIE	the starting angle of the slice arc, measured counterclockwise. The default for the first PIE function is ANGLE=0 (horizontal, or 3:00 postion), or is the ending point of the arc of the previous slice. Specify a value for the ANGLE variable if you want the next slice to start at an angle that is different from the edge of the previous slice, or if you want the first slice to start at an angle other than horizontal.
PIEXY	the angle that works with the SIZE variable to establish the new XLAST, YLAST point relative to the last pie element established with the PIE or PIECNTR functions. The angle is measured counterclockwise starting at the 3:00 position. The default value is 0.

CBORDER Variable

Draws a colored border around text or symbols.

Type: character

Length: 8 for color codes and up to 64 for color names

See also: CBOX

Syntax

CBORDER= color CTEXT ;

color

• specifies the color that fills the box. The color value can be any SAS/GRAPH color name . See Chapter 6, SAS/GRAPH Colors and Images, on page 91 for more information about specifying colors.

  Specifying a null value for the color value (CBOX= )cancels the CBOX variable.

CTEXT

• draws the border in the same coloras the text or symbol. The text color is determined by (1) the COLOR variable or (2) the CTEXT=graphics option or (3) the first color in the colors list.

Functions

You can use the CBORDER variable with these functions:

• LABEL

• SYMBOL

Details

Once you have specified CBORDER, it remains in effect for all subsequent observations that use the LABEL or SYMBOL function and draws a border around all text or symbols. To turn off the border for subsequent text or symbols, specify CBORDER= .

To fill the area defined by CBORDER, use the CBOX variable in conjunction with CBORDER.

CBOX Variable

Draws a solid box behind the text or symbol and fills the box with the specified color.

Type: character

Length: 8 for color codes and up to 64 for color names

See also: CBORDER

Syntax

CBOX= color CBACK ;

color

• specifies the color that fills the box. Color is any SAS/GRAPH color name. See Chapter 6, SAS/GRAPH Colors and Images, on page 91 for more information about specifying colors.

  Specifying a null value for color (CBOX= )cancels the CBOX variable.

CBACK

• fills the box with the same color as the background color of the graph. The background color is either (1) the color specified by the CBACK= graphics option or (2) the default background color for the device.

Functions

You can use the CBOX variable with these functions:

• LABEL

• SYMBOL

Details

Once you have specified CBOX, it remains in effect for all subsequent observations that use the LABEL or SYMBOL function.

The color of the text or symbol within the box is controlled by the COLOR variable.

By default, the solid box has no border. To add a colored border to the box, use the CBORDER variable in conjunction with CBOX.

COLOR Variable

Specifies the color used by the function.

Type: character

Length: 8 for color codes and up to 64 for color names

Default:

1. first color in colors list of the COLORS= graphics option

2. first color in device's default colors list.

Syntax

COLOR= color ;

color

• specifies any SAS/GRAPH color name. See Chapter 6, SAS/GRAPH Colors and Images, on page 91 for more information about specifying colors.

Functions

The COLOR variable is function dependent.

If function is	then the COLOR variable specifies
BAR	the color that outlines and, optionally , fills the bar if a pattern is specified in the STYLE (patterns) STYLE Variable (Patterns) on page 662 variable. If no pattern is specified, the color value is applied only to the outline of the bar.
DRAW, DRAW2TXT	the color of the line.
FRAME	the color of the outline of the frame. If a fill pattern is specified, color also determines the color of the inside of the frame.
LABEL	the color of the text.
PIE	the color for the pie slice if a pattern is specified with the STYLE (patterns) STYLE Variable (Patterns) on page 662 variable. If no pattern is specified, color determines the color of the outline of the pie slice.
POINT	the color of the point.
POLY	the fill color for the interior of the polygon if a pattern is specified with the STYLE variable. If the STYLE variable is missing or EMPTY, color is ignored. Use the POLYCONT function to specify the outline color.
POLYCONT	the color that outlines the polygon when used with the first POLYCONT function. COLOR is ignored for subsequent POLYCONT functions in the POLYCONT sequence.
SYMBOL	the color that draws the symbol.

FUNCTION Variable

Specifies a graphics command or programming function for the Annotate facility to perform.

Type: character

Length: 8

Default: LABEL

Syntax

FUNCTION= function-name ;

function-name

• specifies the name of an Annotate function. The function-name value can be any of the following.

  BAR	draws and, optionally, fills a rectangle.
  CNTL2TXT, DRAW2TXT	copies (XLAST, YLAST) to (XLSTT, YLSTT), overwriting the previous values of (XLSTT, YLSTT).
  COMMENT	places comments in your data set. The observation is ignored when the data set is processed.
  DEBUG	writes the values of all Annotate variables to the SAS log before and after the next observation.
  DRAW	draws a line in the graphics output.
  FRAME	draws a border around the area defined by XSYS and YSYS and specifies a background color for the framed area .
  IMAGE	displays an image in the graphics output from the current (X,Y) coordinates to the coordinates that are associated with the IMGPATH variable.
  LABEL	draws text and is the default for the FUNCTION variable.
  MOVE	moves to the specified point (does not draw a line).
  PIE	draws a pie slice, arc, or circle that can be filled.
  PIECNTR	sets new center and radius values. The PIEXY function can use this information in a later observation.
  PIEXY	returns the coordinates of a point on a pie slice. Other functions can use this information in a later observation.
  POINT	draws a point.
  POLY	begins drawing a polygon (first vertex). Use the POLYCONT function in successive observations to supply the remaining vertices.
  POLYCONT	continues drawing a polygon.
  POP	gets values from the LIFO stack and changes the current value of (XLAST, YLAST) and (XLSTT, YLSTT) to those values.
  PUSH	puts the current values for (XLAST, YLAST) and (XLSTT, YLSTT) in the LIFO stack.
  SWAP	exchanges the values of (XLAST, YLAST) and (XLSTT, YLSTT).
  SYMBOL	draws a symbol. See Figure 7.21 on page 202 for a list of the symbols.
  TXT2CNTL	copies the values (XLSTT, YLSTT) to (XLAST, YLAST), overwriting the previous values of (XLAST, YLAST).

  All other variables in the observation that contain the function act as parameters for the action. For a detailed description of each function and the Annotate variables that can be used in conjunction with it, see Annotate Functions on page 615.

GROUP Variable

Positions graphics elements on the bars of a vertical or horizontal bar chart drawn using the GROUP= option in the GCHART procedure.

Type: Numeric or character; must match the type of the GROUP= variable used in the GCHART procedure.

Length: Should match the length of GROUP= variable in the GCHART procedure.

Default: none

Restriction: Used only with vertical or horizontal bar charts produced by the GCHART procedure.

Syntax

GROUP= group-value ;

group-value

• references value(s) of the variable that is identified by the GROUP= option in the GCHART procedure either as a variable name or as an explicit data value. Group-value can be one of the following:

  group-variable	the name of a group variable.
  group-data-value	a specific numeric data value.
  group-data-value	a specific character data value.

  To annotate all the bars in a horizontal or vertical bar chart, specify a variable name. To annotate a bar chart for a specific value of the GROUP variable, specify a specific value.

Functions

You can use the GROUP variable only with the data coordinate systems 1, 2, 7, and 8, and with these functions:

• BAR

• DRAW

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

Using the GROUP variable is similar to using the X and Y variables with data system coordinates to position graphics elements in a vertical or horizontal bar chart.

Figure 25.14 on page 649 shows how the GROUP variable works with the SUBGROUP and MIDPOINT variables to label the bars of a vertical bar chart.

Figure 25.14: Using the GROUP Variable to Position a Label in a Bar Chart

The label showing the number of units that were sold in Dallas in the year 1997 is positioned by the values that are assigned to these Annotate variables:

• GROUP=YEAR (where YEAR is a variable in the GCHART data set)

• MIDPOINT=CITY (where CITY is a variable in the GCHART data set)

• SUBGROUP=ITEM (where ITEM is a variable in the GCHART data set).

HSYS Variable

Defines the coordinate system and area of the output used by the SIZE variable to display the Annotate graphics. Additionally, you can use the HSYS variable with client-side annotation with Java or ActiveX to control the markersize and linesize for the BAR, DRAW, DRAW2TXT, POLY, and SYMBOL functions.

Type: character

Length: 1

Default: 4

Syntax

HSYS= coordinate-system ;

coordinate-system

• specifies a value that represents a coordinate system. Values can be 1 through 9 and A through C as shown in the following table:

  Absolute Systems	Relative Systems	Coordinate System Units
  1	7	percentage of data area
  2	8	data values
  3	9	percentage of graphics output area
  4	A	cell in graphics output area
  5	B	percentage of procedure output area
  6	C	cell in procedure output area

  These values are also used by the XSYS and YSYS variables. See Coordinate Systems on page 596 for a description of the areas and coordinate systems.

Functions

You can use HSYS with these functions, all of which also use the SIZE variable:

• DRAW

• DRAW2TXT

• FRAME

• LABEL

• PIE

• PIECNTR

• SYMBOL

Details

The coordinate system that you specify with the HSYS variable affects how the function interprets the value of the SIZE variable. For example, if you use HSYS= 3 and SIZE=10 with the DRAW function, the thickness of the line is 10 percent of the graphics output area. If you use HSYS= 1 and SIZE=10 with DRAW, the thickness of the line is 10 percent of the data area.

HTML Variable

Defines a link in the HTML file created for a drill-down graph. This link is associated with an area of the graph and contains valid HTML syntax that can point to a report or another graph that you want to display when the user drills down on the area.

Type: character

Length: up to 1024

Default: none

Syntax

HTML= link-string ;

link-string

• specifies the text that defines the link for drill-down. For more information about drill-down graphs and how to specify the link string, see Adding Links with the HTML= and HTML_LEGEND= Options on page 574.

Functions

You can use the HTML variable with these functions:

• BAR

• FRAME

• IMAGE

• LABEL

• PIE

• POLY

• SYMBOL

Details

Use a LENGTH statement to set the length of the HTML variable to the longest string you need for the link string. Be sure to set the HTML value to a null if you continue writing observations to the annotate data set after you are done assigning links. For example, the following code defines link information for two squares, but then sets the HTML variable to null when drawing a frame; otherwise the backgound area within the frame will use the link information from the last defined HTML value and become a hot zone in the graph.

 data squares;       length function style color $ 8              html text $ 15;       xsys='3'; ysys='3';          /* draw a green square */       color='green';       function='move'; x=10; y=65; output;       function='bar';  x=30; y=95; style='solid';       html='href=green.gif'; output;          /* draw a red square */    color='red';    function='move'; x=60; y=65; output;    function='bar';  x=80; y=95;       html='href=red.gif'; output;       /* draw a blue frame */    function='frame'; color='blue'; style='empty';       /* set null link for background area in frame */       html=''; output;  run; 

IMGPATH Variable

Specifies an image to be displayed from the current (X,Y) coordinates to the (X,Y) coordinates that are associated with this variable.

Type: character

Length: 255

Syntax

IMGPATH = fileref external-file ;

fileref

• specifies an existing fileref that points to an external image file.

external-file

• specifies the full path or full file name of an external image file. The format of the external file specification varies between operating envirionments.

Details

The IMGPATH variable can be used only with the IMAGE Function on page 625.

The manner in which the specified image is to be displayed is determined by the STYLE Variable (Images) on page 662.

LINE Variable

Controls the drawing of a line by determining either the type of line to draw or the relative position of the line.

Type: numeric

Default for all functions: 1

Syntax

LINE= line-type ;

Functions

The behavior and syntax of the LINE variable is function-dependent.

• BAR

  • In the BAR function, valid values for the LINE variable can be 0, 1, 2, or 3. These values determine how the outline of the bar is to be drawn, as shown in the following figure.A value of 0 draws the outline all the way around the bar. A value of 1 draws the outline only on the vertical sides of the bar. A value of 2 draws the outline only on the horizontal sides of the bar. A value of 3 draws no outline.

    
    Figure 25.15: LINE Values for Bars

• DRAW, DRAW2TXT, FRAME, POLY

  • Valid values are whole numbers from 0 to 46. A value of 0 specifies that the line not be drawn. A value of 1 specifies a solid line. The remaining values specify different segmented lines, as illustrated in Figure 7.22 on page 208.

• PIE

  • Valid values are 0, 1, 2, or 3. The value specifies which lines of a pie slice are to be drawn for the current arc, as shown in Figure 25.16 on page 653.

    
    Figure 25.16: LINE Values Used with the PIE Function

MIDPOINT Variable

Positions graphics elements on the bars of a vertical or horizontal bar chart drawn by the GCHART procedure.

Type: Numeric or character; must match the type of the MIDPOINT= variable in the GCHART procedure.

Length: Should match the length of the MIDPOINT= variable in the GCHART procedure.

Default: none

Restriction: Used only with vertical or horizontal bar charts produced by the GCHART procedure.

Syntax

MIDPOINT= midpoint-value ;

midpoint-value

• references midpoint data value(s) in the GCHART procedure either as a variable name or as an explicit data value. Midpoint-value can have one of the following forms:

  midpoint-variable	the name of a midpoint variable.
  midpoint-data-value	a specific numeric data value.
  midpoint-data-value	a specific character data value.

  Generally, specify a variable name if you want to annotate all of the bars in a horizontal or vertical bar chart. To annotate a bar chart for a specific value of the MIDPOINT variable, specify a specific value.

Functions

You can use the MIDPOINT variable only with the data coordinate systems 1, 2, 7, and 8, and with these functions:

• BAR

• DRAW

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

Using the MIDPOINT variable is similar to using the X and Y variables to position graphics elements in a vertical or horizontal bar chart when using data system coordinates. For example, suppose you produce a vertical bar chart in which the chart variable CITY produces a bar for each city in a data set. The height of each bar is determined by the value of the SUMVAR= variable, UNITS.

You can label these bars by assigning the chart variable CITY to the Annotate MIDPOINT variable. The MIDPOINT variable provides the x coordinate for the label. By default, Annotate assigns the statistic variable, in this case the SUMVAR= variable, UNITS, to the Annotate Y variable, which provides the y coordinate for the label.

Figure 25.17 on page 655 shows how the values of the MIDPOINT and Y variables position the label that shows the number of units sold in Atlanta. The value, which is calculated and printed by the LABEL function, is 56.

Figure 25.17: Using the MIDPOINT Variable to Position a Label in a Bar Chart

The labels in this figure are positioned by the values that are assigned to these Annotate variables:

• MIDPOINT=CITY (where CITY is the chart variable); the MIDPOINT variable provides the horizontal coordinate in the vertical bar chart.

• Y=UNITS (where UNITS is the SUMVAR= variable); the Y variable provides the vertical coordinate. By specifying Y=units/2, you can vertically center the label in the bar.

Note: In a horizontal bar chart, the MIDPOINT variable controls the y coordinate and the statistic variable controls the x coordinate.

CAUTION:

• Be careful when using MIDPOINT and X and Y variables in the same data set. Using the MIDPOINT and X variables in an Annotate data set that is used to annotate a VBAR chart or the MIDPOINT and Y variables in the same data set used to annotate an HBAR chart can cause unexpected results. When annotating a VBAR chart, the Annotate facility uses the MIDPOINT variable as the horizontal coordinate if it exists in the Annotate data set and ignores the X variable. Consequently, you should use the MIDPOINT variable as the horizontal coordinate for all observations in an Annotate data set if you use it for one.

  A similar behavior occurs if you use both the MIDPOINT and Y variables in an Annotate data set that is used to annotate HBAR charts. The MIDPOINT variable is always used, regardless of whether it has a missing value, and the Annotate facility ignores the Y variable. In this case, as well, use the MIDPOINT variable for the vertical coordinate for all observations in an Annotate data set if you use it for one.

POSITION Variable

Controls placement and alignment of a text string specified by the LABEL function.

Type: character

Length: 1

Default: 5

Syntax

POSITION= text-position 0 ;

text-position

• specifies the placement of the text string in relation to the position that is defined by the X and Y variables. Text-position can be one of the characters 1 through 9, A through F, <, +, or >. These characters represent the positions that are described in the following table:

  Position	Right Aligned	Centered	Left Aligned
  One cell above	1	2	3
  Centered	4 <	5 +	6 >
  One cell below	7	8	9
  Half cell above	A	B	C
  Half cell below	D	E	F

  These positions are illustrated in Figure 25.19 on page 658.

Figure 25.19: Effect of POSITION Values on Text Strings

• specifies a pause in the string in order to change an attribute, such as the color of the text.

Details

Stacking text strings To stack text strings, specify a different position value of each string. Figure 25.18 on page 657 shows two ways to stack text.

Figure 25.18: Combining POSITION Values to Stack Text

Positioning numeric labels The <, +, and > positions perform the same function as 4, 5, and 6, respectively, but are recommended only for labels that are numbers. The <, +, and > positions are especially useful when you are labeling a horizontal bar chart. You can use <, +, or > if the numbers in your font are significantly smaller than the text and you are having trouble centering labels. If the numbers in your font are the same height or close to the same height as the text, you can use positions 4, 5, and 6 to center the labels.

Note: You cannot stack <, +, and > positions as you can 4, 5, and 6 positions.

Changing attributes in the middle of a text string 0 is a special value to use when you want to pause and then continue a text string. With this value you can change colors, fonts, and so on in the middle of a line, while retaining the exact position of the text at the pause. When POSITION='0', the combined text string is left-justified beginning at the point that is defined by the X and Y variables. However, you must define missing values for X for the continuation string. The following Annotate data set changes the font in the middle of the string. The result is shown in Figure 25.20 on page 659.

 data anno;     length style $ 8 text $ 12;     xsys='3'; ysys='3'; hsys='3'; x=5; y=50;        style='swissb'; size=10; text='This is the';        position='0'; output;     x=.; style='swissbi'; text=' ITALIC font';         output;  run; 

Figure 25.20: Using POSITION= 0 to Change the Attributes of a Text String

ROTATE Variable

Specifies the angle at which to rotate the graphics element.

Type: numeric

Default: 0.00

Syntax

ROTATE= rotation-angle ;

Functions

The ROTATE variable is function dependent.

If function is	then the variable
PIE	specifies the sweep of the generated arc that begins at the angle that is specified by the ANGLE variable that is used with the PIE function.
LABEL	rotates the individual text characters with respect to the baseline.

SIZE Variable

Determines the size of the graphics element with which it is used.

Type: numeric

Length: 8

Default: 1.00 (2 when HSYS=3)

Syntax

SIZE= size-factor ;

Functions

The SIZE variable is function dependent.

If function is	then the variable
DRAW, DRAW2TXT, FRAME, POLY, or POLYCONT	determines the thickness of the line being drawn.
LABEL	specifies the height of the text.
PIE or PIECNTR	determines the radius of the pie.
PIEXY	sets the radius multiplier .
SYMBOL	selects the height of the symbol.

Details

The SIZE variable uses the coordinate system that is specified by the HSYS Variable on page 649, which specifies the type of coordinate system used to generate the graph.

As the thickness of the line increases , it may be impossible to center around a given coordinate. For example, if you specify a thickness of value 2 and HSYS= 4 , the first line is drawn at the (X, Y) coordinates. The second is drawn slightly above the first. The exact amount varies by device, but it is always one pixel in width. A thickness of value 3 produces one line above, one line at, and one line below the (X, Y) coordinate position.

The SIZE variable is equivalent to the HEIGHT= option in the SYMBOL statement. See HEIGHT= on page 187 for details.

See Figure 25.6 on page 621 for examples of line thicknesses.

Figure 25.21: Sample Line Thicknesses Used with the SIZE Variable

STYLE Variable (Fonts)

Specifies a font for text or symbols produced by the LABEL or SYMBOL functions.

Type: character

Length: Depends on specification.

Default: default hardware font

Not supported by: ActiveX (Partial), Java

Syntax

STYLE= font hardware-font-name NONE ;

font

• specifies a font. Font can be either the name of a software font that is stored in a catalog or a hardware font specification of the form HW xxxnnn . For example, STYLE= CENTB specifies a software font that is stored in the catalog SASHELP.FONTS. The maximum length for font is 8 characters.

hardware-font-name

• specifies the name of a hardware font as shown in the Chartype window of the device entry. The maximum length for hardware-font-name is 256 characters. Hardware-font-name must be enclosed in both double and single quotation marks, for example, STYLE=" Palatino-Italic ".

NONE

• specifies the default hardware font.

See Chapter 5, SAS/GRAPH Fonts, on page 75 for more information about specifying fonts.

If the value of the STYLE variable is missing, SAS/GRAPH software searches for a font specification in this order:

1. the font specified by the FTEXT= graphics option

2. the hardware font, if the device supports one

3. the SIMULATE font.

Details

When the STYLE variable is used with the SYMBOL function, it behaves the same as the FONT= option in the SYMBOL statement. By default, no font is specified and the symbol that is specified by the TEXT variable is taken from the special symbol table. If you use STYLE to specify a symbol font, such as Marker, the string that is assigned by the TEXT variable is the character code for a symbol. If you use STYLE to specify a text font, such as Swiss, the string assigned by the TEXT variable is displayed as text. See the FONT= option of the SYMBOL statement for details.

Note: Java does not support the STYLE variable. However, you can use special symbols from the MARKER font by using the SYMBOL function.

STYLE Variable (Images)

Determines the appearance of images specified with the IMGPATH variable and the IMAGE function.

Type: character

Default: TILE

Syntax

STYLE= TILE FIT ;

TILE

• Uses copies of the image to fill the image area.

FIT

• Stretches one instance of the image to fill the image area.

Details

This version of the STYLE variable can be used only with the IMAGE Function on page 625.

STYLE Variable (Patterns)

Specifies a pattern for bars, pies, frames , and rectangles

Type: character

Length: 8

Default: EMPTY PEMPTY MEMPTY

Not supported by: Java (partial), ActiveX (partial)

Syntax

STYLE= fill-pattern ;

fill-pattern

• specifies a pattern to use with the graphics element. The value for fill-pattern is function-dependent:

• Function

  • Valid Fill Pattern Values

• BAR,FRAME

  •  

    SOLID S	Fill with a solid color.
    EMPTY E	No fill.
    style < density >	style	R for right-slanted fill lines, L for left- slanted fill lines, or X for crossing fill lines
    	density	Whole numbers 1 through 5 specify increasing thickness for the fill lines.

  • Note: Client-side rendering using Java or ActiveX supports only SOLID and EMPTY and defaults to EMPTY if any other value is used.

    An illustration of these pattern styles is provided in the definition of the VALUE= option of the PATTERN statement.

• PIE

  •  

    PSOLID PS	Solid fill.
    PEMPTY PE	No fill, the default.
    P density < style < angle >> density		Whole numbers 1 through 5 specify increasing thickness for the fill lines.
    	style	N, the default, optionally specifies parallel fill lines; X optionally specifies crossed fill lines.
    	angle	Optionally specifies the angle of the fill lines. Values range from 0 to 360. The angle is measured counterclockwise from the horizontal. The default is 0 , which draws horizontal lines.

  • Note: Client-side rendering using Java or ActiveX supports only PSOLID and PEMPTY and defaults to PEMPTY if any other value is used.

    An illustration of these pattern styles is provided in the definition of the VALUE= option of the PATTERN statement.

• POLY

  •  

    MSOLID MS	Fill with a solid color.
    MEMPTY ME	No fill, the default.
    M density < style < angle >> density		Whole numbers 1 through 5 specify increasing thickness for the fill lines.
    	style	N, the default, optionally specifies parallel fill lines; X optionally specifies crossed fill lines.
    	angle	Optionally specifies the angle of the fill lines. Values range from 0 to 360. The angle is measured counterclockwise from the vertical. The default is 0 ­ °, which draws vertical lines.

  • Note: Client-side rendering using Java or ActiveX supports only MSOLID and MEMPTY and defaults to MEMPTY is any other value is used.

    An illustration of these pattern styles is provided in the definition of the VALUE= option of the PATTERN statement.

SUBGROUP Variable

Positions graphics elements within subgrouped bars of a vertical or horizontal bar chart produced by the GCHART procedure.

Type: Numeric or character; must match the type of the SUBGROUP variable used in the GCHART procedure.

Length: Should match the length of the SUBGROUP= variable in the GCHART procedure.

Default: none

Restriction: The bar charts must have been produced using the SUBGROUP= option.

Syntax

SUBGROUP= subgroup-value ;

subgroup-value

• references value(s) of the SUBGROUP= variable in the GCHART procedure either as a variable name or as an explicit data value. Subgroup-value can have one of the following forms:

  subgroup-variable	the name of a subgroup variable.
  subgroup-data-value	a specific numeric data value.
  subgroup-data-value	a specific character data value.

  Generally, specify a variable name if you want to annotate all of the bars in a horizontal or vertical bar chart. To annotate a bar chart for a specific value of the SUBGROUP variable, specify a specific value.

Functions

You can use the SUBGROUP variable only with the data coordinate system 1, 2, 7, or 8, and with these functions:

• BAR

• DRAW

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

Using the SUBGROUP variable is similar to using the X and Y variables with data system coordinates to position the graphics elements in subgroup segments in vertical and horizontal bar charts.For example, in a vertical bar chart that produces a bar for each city in a data set, you can easily label the subgroups in each bar by setting subgroup-variable to the GCHART variable by which the bar is being subgrouped. This variable provides the y coordinate of the label (so don t specify a competing value for y, but instead specify y=. or y=y ).

The MIDPOINT variable works well with the SUBGROUP variable to provide the x coordinate. In this example, if you set the MIDPOINT variable to the GCHART variable that contains the names of the cities, the MIDPOINT variable provides your x coordinate. Rather than providing the X and Y variables, you would use the SUBGROUP and MIDPOINT variables. Figure 25.22 on page 665 shows how the SUBGROUP variable works with the MIDPOINT variable to label the bars of a vertical bar chart.

Figure 25.22: Using the SUBGROUP Variable to Position a Label in a Bar Chart

The label showing the number of printers sold in Atlanta is positioned by the values that are assigned to these Annotate variables:

• MIDPOINT=CITY (where CITY is a variable in the GCHART data set)

• SUBGROUP=ITEM (where ITEM is a variable in the GCHART data set).

TEXT Variable

Specifies the text or symbol to be placed on the graphics output.

Type: character

Length: up to 200

Default: blank string

Syntax

TEXT= text-string special-symbol ;

text-string

• specifies the text that is used as a label (LABEL or COMMENT function) or symbol (SYMBOL function). The maximum length for text-string is 200 characters.

special-symbol

• specifies the name of a symbol from the special symbol table that is illustrated in Figure 7.21 on page 202. The maximum length for special-symbol is eight characters.

Functions

You can use the TEXT variable with these functions:

• COMMENT

• LABEL

• SYMBOL

Details

Define the TEXT variable with sufficient length to contain all of the characters in your text string. If you need longer strings, use separate observations and POSITION= 0 to continue the text.

Use a LENGTH statement to set the length of the TEXT variable if the length of a text string is longer than one character.

WHEN Variable

Specifies when the function is performed in relation to generating other graphics output for the procedure or in relation to generating other Annotate graphics.

Type: character

Length: 1

Default: B

Syntax

WHEN= B A;

B A

• specifies whether to draw the annotation before (B) or after (A) the graph. These values are not case sensitive. A missing value is equivalent to specifying B.

  Note: Some annotations coded with WHEN= B that work on the server may not be visible with client-side rendering using Java or ActiveX because the annotations are drawn behind the backplane. The only solution is to code WHEN= A .

Functions

You can use the WHEN variable with these functions:

• BAR

• DRAW

• DRAW2TXT

• FRAME

• LABEL

• MOVE

• PIE

• PIECNTR

• PIEXY

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

Normally, observations in an Annotate data set are processed sequentially. If you use the WHEN variable, all those observations with a WHEN value of B are processed first, the procedure output is then processed (if one is to be produced), and finally the observations with a WHEN value of A are processed.

X Variable

Identifies the x coordinate of where a graphics element is to be drawn.

Type: numeric

Default: value of XLAST or XLSTT

Syntax

X= horizontal-coordinate ;

Functions

You can use the X variable with these functions:

• BAR

• DRAW

• IMAGE

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Note: The X or XC variable is required unless either the MIDPOINT, GROUP, or SUBGROUP variable provides the horizontal coordinate.

Details

Specify a corresponding vertical coordinate when using the X variable. This vertical coordinate can be specified with the Y, YC, MIDPOINT, or SUBGROUP variables, depending on the type of graph that you are annotating.

The X variable uses the units that are specified in the XSYS variable. If you use XSYS= 2 and the data axis is typed as character, use the XC variable instead of the X variable.

If the value of the X variable is missing for a function that requires it, the value of the XLAST variable is used with nontext functions and the value of the XLSTT variable is used with text functions.

XC Variable

Identifies the x coordinate of a graphics element when the coordinate value is character.

Type: character

Length: Should match that of the plot variable in the procedure.

Default: the value of XLAST or XLSTT

Restrictions: Used only with output from the GCHART and GPLOT procedures. Ignored if the axes are numeric.

Syntax

XC= character-type-horizontal-coordinate ;

Functions

You can use the XC variable with these functions:

• BAR

• DRAW

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

The XC variable is the character equivalent of the X variable. Use XC when the axis values are character. You must also specify a value of 2 (absolute data values) for the XSYS variable. (See also XSYS Variable on page 670.) If you use a value other than 2 for the XSYS variable, the graphics output is not displayed properly.

Figure 25.23 on page 669 illustrates the XC variable.

Figure 25.23: Using the XC and YC Variables with Character Data

Note: The X or XC variable is required unless either the MIDPOINT, GROUP, or SUBGROUP variable provides the horizontal coordinate.

CAUTION:

• Do not use the X and XC variables in the same data set. Using both X and XC variables in the same data set can cause unpredictable results.

XSYS Variable

Defines the coordinate system and area of the output used by the X and XC variables to display the Annotate graphics.

Type: character

Length: 1

Default: 4

Syntax

XSYS= coordinate-system ;

coordinate-system

• specifies a value that represents a coordinate system. Values can be 1 through 9 and A through C as shown in the following table:

  Absolute Systems	Relative Systems	Coordinate System Units
  1	7	percentage of data area
  2	8	data values
  3	9	percentage of graphics output area
  4	A	cell in graphics output area
  5	B	percentage of procedure output area
  6	C	cell in procedure output area

  These values are also used by the HSYS and YSYS variables. See Coordinate Systems on page 596 for a description of the areas and coordinate systems.

Functions

You can use the XSYS variable with these functions:

• BAR

• DRAW

• FRAME

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

The behavior of the XSYS variable is function-dependent for the following functions:.

BAR, DRAW

The coordinate system that you specify with the XSYS variable affects how the function interprets the value of the X or XC variable. If XC is used, XSYS= 2 must also be used.

FRAME

The XSYS and YSYS variables define the area enclosed by the frame. To draw a frame that encloses the axis area, use XSYS= 1 and YSYS= 1 , as shown in the following figure. Figure 25.24: Frame Created When XSYS= 1 and YSYS= 1 To draw a frame that encloses the entire graphics output area, specify XSYS= 3 and YSYS= 3 , as shown in the following figure. Figure 25.25: Frame Created When XSYS= 3 and YSYS= 3 To limit the size of the frame to the size of the procedure output area, specify a value of 5 for XSYS and YSYS. Note that the values of XSYS and YSYS can differ . You can specify a frame that occupies the entire width of the graphics output area and only the vertical width of the procedure output area by specifying XSYS= 3 and YSYS= 5 , as shown in the following figure. Figure 25.26: Frame Created When XSYS= 3 and YSYS= 5

Details

The coordinate system that you specify with the XSYS variable affects how the function interprets the value of the X or XC variable.

Note: Not all coordinate systems can be used with all Annotate variables. For any restrictions, see the individual variables in this section.

Y Variable

Identifies the y coordinate of where a graphics element is to be drawn.

Type: numeric

Default: value of YLAST or YLSTT

Syntax

Y= vertical-coordinate ;

Functions

You can use the Y variable with these functions:

• BAR

• DRAW

• IMAGE

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Note: The Y or YC variable is required unless either the MIDPOINT, GROUP, or SUBGROUP variable provides the vertical coordinate.

Details

Specify a corresponding horizontal coordinate when using the Y variable. You can specify the horizontal coordinate with the X, XC, MIDPOINT, or SUBGROUP variable, depending on the type of graph you are annotating.

The Y variable uses the units specified in the YSYS variable. If you use YSYS= 2 and the axis data is type character, use the YC variable instead of the Y variable.

If the value of the Y variable is missing for a function that requires it, the value YLAST is used for nontext functions and the value of YLSTT is used for text functions.

YC Variable

Identifies the y coordinate of a graphics element when the coordinate value is character.

Type: character

Length: Should match that of the plot variable in the procedure.

Default: YLAST YLSTT

Restrictions: Used only with output from the GCHART and GPLOT procedures. Ignored if the axes are numeric.

Syntax

YC= character-type-vertical-coordinate ;

Functions

You can use the YC variable with these functions:

• BAR

• DRAW

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

The YC variable is the character equivalent of the Y variable. Use YC when the axis values are character. You must also specify a value of 2 (absolute data values) for the YSYS variable. (See YSYS Variable on page 674.) If you use a value other than 2 for the YSYS variable, the graphics output is not displayed properly.

See Figure 25.23 on page 669 for an illustration of the YC variable.

Note: The X or XC variable is required unless either the MIDPOINT, GROUP, or SUBGROUP variable provides the horizontal coordinate.

CAUTION:

• Do not use Y and YC variables in the same data set. Using both Y and YC variables in the same data set can cause unpredictable results.

YSYS Variable

Defines the coordinate system and area of the output used by Y and YC to display the Annotate graphics.

Type: character

Length: 1

Default: 4

Syntax

YSYS= coordinate-system ;

coordinate-system

• specifies a value that represents a coordinate system. Values can be 1 through 9 and A through C, as shown in the following table:

  Absolute Systems	Relative Systems	Coordinate System Units
  1	7	percentage of data area
  2	8	data values
  3	9	percentage of graphics output area
  4	A	cell in graphics output area
  5	B	percentage of procedure output area
  6	C	cell in procedure output area

  These values are also used by the HSYS and XSYS variables. See Coordinate Systems on page 596 for a description of the areas and coordinate systems.

Functions

The YSYS variable is function-dependent, as defined in the XSYS Variable on page 670

You can use the YSYS variable with these functions:

• BAR

• DRAW

• FRAME

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

The coordinate system that you specify with the YSYS variable affects how the function interprets the value of the Y or YC variable.

Note: Not all coordinate systems can be used with all Annotate variables. For any restrictions, see the individual variables in this section.

Z Variable

Identifies the z coordinate of where a graphics element is to be drawn.

Type: numeric

Length: 8

Default: none

Restrictions: On the server, is used only with output from the G3D procedure. For client-side annotation with Java or ActiveX, you can use the Z variable with GMAP, GCHART, GCONTOUR, GPLOT, and G3D, for example to add annotations above the plane of the map.

Syntax

Z= depth-coordinate ;

Functions

You can use the Z variable with these functions:

• BAR

• DRAW

• IMAGE

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

The Z variable uses the units that are specified in the ZSYS variable.

ZSYS Variable

Defines the coordinate system and area of the output used by Z variable to display the Annotate graphics.

Type: character

Length: 1

Default: 2

Syntax

ZSYS= coordinate-system ;

coordinate-system

• specifies a value that represents a coordinate system. Values can be 1, 2, 7, or 8 as shown in the following table:

  Absolute Systems	Relative Systems	Coordinate System Units
  1	7	percentage of data area
  2	8	data values

  See Coordinate Systems on page 596 for a description of the areas and coordinate systems.

Functions

You can use the ZSYS variable with these functions:

• BAR

• DRAW

• IMAGE

• LABEL

• MOVE

• PIE

• PIECNTR

• POINT

• POLY

• POLYCONT

• SYMBOL

Details

The coordinate system that you specify with the ZSYS variable affects how the function interprets the value of the Z variable.

Note: Not all coordinate systems can be used with all Annotate variables. For any restrictions, see the individual variables in this section.