Annotate Functions

In an Annotate data set, the value of the FUNCTION variable specifies what action the observation performs . Annotate functions act in conjunction with Annotate variables that determine where and how to perform the action. Many of these variables are function-dependent, that is, what they do depends on the function they are used with. For example, with the LABEL function the STYLE variable specifies a font; with the BAR function, STYLE specifies a pattern.

This section describes all of the values of the FUNCTION variable. For each function it

describes the function's action.
notes whether the function updates the internal coordinate variables XLAST, YLAST and XLSTT, YLSTT.
describes how other Annotate variables behave with the function. For a complete description of each variable, see Annotate Variables on page 642.

For a summary of drawing and programming tasks performed by the FUNCTION variable, see Table 24.2 on page 594 .

The variables that are available for use with each function are listed in Figure 24.4 on page 593.

BAR Function

Draws a rectangle whose lower-left corner is defined by the internal variables (XLAST, YLAST) and whose upper-right corner is defined by the specified X, Y variable pair. You can define the color of the fill, the fill pattern, and the edge lines to be drawn.

Updates: XLAST, YLAST

Syntax

FUNCTION= BAR ;

Associated Variables

COLOR= color

specifies the color of either the interior of the bar or the outline of the bar. Color can be any SAS/GRAPH color name . The part of the bar affected depends on the value of the STYLE variable. If STYLE specifies a pattern or fill, the COLOR variable determines the color of the interior. If STYLE specifies an empty pattern, the COLOR variable determines the color of the outline of the bar.

GROUP = group-value

MIDPOINT = midpoint-value

SUBGROUP = subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

HTML= link-string

specifies the text that defines the link for drill-down.

LINE=0 3

specifies the direction in which to adjust the outline of the bar. Use LINE values 1 and 2 to offset a particular bar from an axis or adjoining area. The following figure illustrates LINE values.

Figure 25.1: LINE Values for Bars

SIZE = thickness

specifies a line thickness for the rectangle

STYLE= fill-pattern

specifies the pattern that fills the bar. Fill-pattern can be the following bar and block patterns:

SOLID

S

a solid fill.

EMPTY

E

an empty fill.

style < density >

a shaded pattern:

style can be R X L

density can be 1 5

WHEN= B A

specifies when to draw the bar in relation to other procedure output. See WHEN Variable on page 666.

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

define the upper-right corner of a bar (rectangle) whose lower-left corner is (XLAST,YLAST). Use the Z variable only when you are annotating output from the G3D procedure. Figure 25.2 on page 617 illustrates the use of these coordinates.

Figure 25.2: Points Used to Construct a Bar

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. The XC variable can be used only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for Y or YC variable. The YC variable can only be used with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

Details

Figure 25.2 on page 617 shows how the XLAST, YLAST, and X, Y variables define the diagonal corners of the bar. With character data, the XC and YC variables are used in place of the X and Y variables. The values of the XLAST and YLAST variables are usually initialized with a MOVE function or another function that updates the XLAST and YLAST pair. When the XC variable is used, set XSYS= 2 . When the YC variable is used, set YSYS= 2 .

CNTL2TXT Function

Copies the values of the internal coordinates stored in the variable pairs (XLAST, YLAST) to (XLSTT, YLSTT).

Updates: XLSTT, YLSTT

Syntax

FUNCTION= CNTL2TXT ;

Details

You can use CNTL2TXT to calculate the position of labels on a graph. For example, the following DATA step uses CNTL2TXT to position a pie slice label in the center of the arc and just beyond the arc itself, as shown in Figure 25.5 on page 619.

Figure 25.5: Labeled Pie Slice

First, use the PIE function to draw the pie slice:

 data pielabel;     retain xsys ysys '3';     length function style $ 8;     function='pie'; size=20; x=30; y=30;        style='empty'; rotate=45; output;

Then use the PIEXY function to calculate a point outside of the arc as shown in Figure 25.3 on page 618.

 /* find a point that is half of the arc (rotate*.5) */        /* and is 4 units beyond the radius (size=1.1) */     function='piexy'; angle=rotate*.5; size=1.1; output;

Figure 25.3: Position Calculated with the PIEXY Function

At this point, the XLAST and YLAST variables contain the coordinates of the point that is calculated by PIEXY. However, (XLAST, YLAST) cannot be used directly by text functions. Use CNTL2TXT to copy the coordinates in (XLAST, YLAST) to the XLSTT and YLSTT variables, which text functions can use. Figure 25.4 on page 618 shows the results.

 function='cntl2txt'; output;

Figure 25.4: Coordinates after Using the CNTL2TXT Function

Now you can use the LABEL function to write the label as shown in Figure 25.5 on page 619. Specify missing values for the X and Y variables to force LABEL to use the XLSTT and YLSTT variables instead of the X and Y variables.

 /* write the label 'Slice 1' and position it to     */        /* the right of the point stored in XLSTT and YLSTT */     function='label'; text='Slice 1'; angle=0; rotate=0;        position='6'; style='swissb'; size=4; x=.; y=.;        output;  run;     /* draw the Annotate graphics */  proc ganno anno=pielabel;  run;  quit;

COMMENT Function

Inserts comments within the Annotate data set. The obser vations generated by the COMMENT function are ignored when the data set is processed .

Syntax

FUNCTION= COMMENT ;

Associated Variables

TEXT= text-string
- specifies the comment to write to the data set.

DEBUG Function

Writes the values of internal coordinates and Annotate variables to the SAS log before and after processing the next command (unless it is DEBUG) in the Annotate DATA step.

Syntax

FUNCTION='DEBUG';

DRAW Function

Draws a line in the graphics output from the (XLAST, YLAST) coordinates to the (X, Y) coordinates specified in the function.

Updates: XLAST, YLAST

Syntax

FUNCTION= DRAW ;

Associated Variables

COLOR= color

specifies the color of the line that is being drawn. Color can be any SAS/GRAPH color name.

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

HSYS= coordinate-system

specifies the coordinate system for the SIZE variable. See HSYS Variable on page 649 for an explanation of coordinate-system .

LINE=1 46

specifies the line type of the line that is being drawn. See Specifying Line Types on page 207 for an illustration of the line types.

SIZE= line-thickness

specifies the thickness of the line that is being drawn. The units depend on the value of the HSYS variable. For example, if HSYS= 3 , the SIZE variable is in units of percent of the graphics output area. If HSYS= 4 , the SIZE variable is in units of cells of the graphics output area.

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. See Figure 25.6 on page 621 for examples of line thicknesses.

Figure 25.6: Sample Line Thicknesses Used with the SIZE Variable

WHEN= B A

specifies when to draw the line in relation to other procedure output. See WHEN Variable on page 666.

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

specify the endpoint of a line drawn from (XLAST, YLAST) to (X,Y).

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. The XC variable can be used only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y or YC variable. The YC variable can be used only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable (PROC G3D only). See ZSYS Variable on page 676 for an explanation of coordinate-system .

DRAW2TXT Function

Draws a line from (XLAST, YLAST) to (XLSTT, YLSTT) without updating any of those variables.

Syntax

FUNCTION= DRAW2TXT ;

Associated Variables

COLOR= color

specifies the line color. Color can be any SAS/GRAPH color name.

HSYS= coordinate-system

specifies the coordinate system for the SIZE variable. See HSYS Variable on page 649 for an explanation of coordinate-system .

LINE=1 46

specifies the line type of the line that is being drawn. See Specifying Line Types on page 207 for an illustration of the line types.

SIZE= line-thickness

specifies the thickness of the line that is being drawn. See DRAW Function on page 620 for details.

WHEN= B A

specifies when to draw the line in relation to generation of the procedure output. See WHEN Variable on page 666.

Details

DRAW2TXT is useful for underlining text.

DRAW2TXT does not update the (XLAST, YLAST) or (XLSTT, YLSTT) coordinates; neither can it interrupt a POLYCONT sequence.

FRAME Function

Draws a border around the portion of the display area defined by the XSYS and YSYS variables. Optionally specifies a background color for the framed area.

Syntax

FUNCTION='FRAME';

Note: The FRAME function is not supported for client-side annotate with Java.

Associated Variables

COLOR= color

specifies the frame color and, if the STYLE variable is specified, fills the interior of the frame. Color can be any SAS/GRAPH color name.

HSYS= coordinate-system

specifies the coordinate system for the SIZE variable. See HSYS Variable on page 649 for an explanation of coordinate-system .

Note: The HSYS variable is not supported for client-side output with ActiveX.

HTML= link-string

specifies the text that defines the link for drill-down.

LINE=1 46

specifies the line type with which to draw the frame. See Specifying Line Types on page 207for an illustration of the line types.

SIZE= line-thickness

specifies the thickness of the line with which to draw the frame. See DRAW Function on page 620 for details.

Note: The SIZE variable is not supported for client-side output with ActiveX.

STYLE= fill-pattern

specifies the pattern that fills the area that is bounded by the frame. Fill-pattern can be the following bar and block patterns:
SOLID

S

a solid fill.

EMPTY

E

an empty fill.
style<density>

a shaded pattern:

style can be R X L

density can be 1 5
See also the discussion of fill patterns for bars and blocks in VALUE= on page 171.

WHEN= B A

specifies when to draw the frame in relation to other procedure output. See WHEN Variable on page 666

XSYS= coordinate-system

YSYS= coordinate-system

define the area to be enclosed by the frame. For example, if XSYS= 1 and YSYS= 1 , the frame encloses the axis area as shown in Figure 25.7 on page 623. See XSYS Variable on page 670 and the YSYS variable on YSYS Variable on page 674 for an explanation of coordinate-system .

Figure 25.7: Frame Created When XSYS= 1 and YSYS= 1

If XSYS= 3 and YSYS= 3 , the frame encloses the entire graphics output area, as shown in Figure 25.8 on page 624.

Figure 25.8: Frame Created When XSYS= 3 and YSYS= 3

The values for XSYS and YSYS do not have to be the same. If XSYS= 3 and YSYS= 5 , the frame encloses the entire width of the graphics output area; however, vertically, the frame only encloses the procedure output area as shown in Figure 25.9 on page 624.

Figure 25.9: Frame Created When XSYS= 3 and YSYS= 5

See XSYS Variable on page 670 and YSYS Variable on page 674 for an explanation of these variables and the areas that they affect.

Details

Use FRAME to simulate the CBACK= graphics option on devices (such as plotters ) that do not support that option. For devices that do support the CBACK= graphics option, FRAME works in addition to that option. FRAME does not alter the (XLAST, YLAST) coordinates. See CBACK on page 266 for more information on CBACK=.

IMAGE Function

Displays an image in the graphics output from the current (X,Y) coordinates to the (X, Y) coordinates that are associated with the IMGPATH variable.

Updates: XLAST, YLAST

Syntax

FUNCTION= IMAGE ;

Associated Variables

HTML= link-string

specifies the text that defines the link for drill-down.

IMGPATH= fileref external-file

specifies the image file to be displayed in the graphics output. The syntax of external file specifications varies across operating environments.

STYLE = TILE FIT ;

specifies how the image is to be applied to fill the specified area of the graphics output. The default value of TILE replicates the image to fill the area. The FIT value stretches a single instance of the image to fill the area.

X= horizontal-coordinate ;

specifies the horizontal coordinate that determines the size of the image displayed in the graphics output.

Y= vertical-coordinate ;

specifies the vertical coordinate that determines the size of the image displayed in the graphics output.

Z= depth-coordinate ;

specifies the depth coordinate for 3D output.

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

Details

The following example shows how the IMAGE function adds a single stretched instance of an image to the graphics output, beginning at the current coordinates and ending at the specified coordinates:

 x=10; y=5; function='move' output;  x=35; y=15; imgpath='/images/gifs/picture.gif';  style='fit';  function='image'; output;

LABEL Function

Places text in the graphics output. Associated variables can control the color, size, font, base angle, and rotation of the characters displayed.

Updates: XLSTT, YLSTT

Syntax

FUNCTION= LABEL ;

Associated Variables

ANGLE=0 360

specifies the baseline angle of the character string with respect to the horizontal. The pivot point is at (X, Y), and the rotation is in a counterclockwise direction.

CBORDER= color CTEXT

draws a colored border around the text. Color can be any SAS/GRAPH color name.

CBOX= color CBACK

draws a solid, colored box behind the text. Color can be any SAS/GRAPH color name.

COLOR= color

specifies the color of the text. Color can be any SAS/GRAPH color name.

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

HSYS= coordinate-system

specifies the coordinate system for the SIZE variable. See HSYS Variable on page 649 for an explanation of coordinate-system .

HTML= link-string

specifies the text that defines the link for drill-down.

POSITION= text-position

controls the text string placement and alignment. Text-position can be one of the characters 1 through 9, A through F, <, +, or >. Invalid or missing values default to POSITION= 5 . POSITION should always be a character variable of length 1. For details, see POSITION Variable on page 656.

ROTATE= rotation-angle

specifies the rotation angle of each character in the string. It is equivalent to the ROTATE= option in the FOOTNOTE, NOTE, and TITLE statements.

SIZE= height

specifies the height of the text string. The SIZE variable units are based on the value of the HSYS variable.

STYLE= font " hardware-font-name " NONE

specifies the font with which to draw the text that is specified by the TEXT variable. See STYLE Variable (Fonts) on page 661 for a description of the various font specifications.

TEXT=' text-string '

specifies the text to be written. Text-string can be up to 200 characters. 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.

WHEN= B A

specifies when to draw the text strings in relation to other procedure output. See WHEN Variable on page 666

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

specify the start point of the text string. The Z variable can be used only with the G3D procedure. Optionally, you can modify the placement of the text string with the POSITION variable.

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. Use the XC variable only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y or YC variable. Use the YC variable only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

MOVE Function

Moves the drawing pointer to a specific location without drawing a line.

Updates: XLAST, YLAST

Syntax

FUNCTION= MOVE ;

Associated Variables

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

WHEN= B A

specifies when to perform the move in relation to other procedure output. See also WHEN Variable on page 666.

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

specify the coordinates to which the pen is to be moved. The Z variable can only be used with the G3D procedure.

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. Use the XC variable only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y or YC variable. Use the YC variable only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

Details

Use MOVE to prepare for a DRAW command, a BAR command, or programming functions.

PIE Function

Draws pie slices in the graphics output.

Updates: XLAST, YLAST to coordinates for center of the slice.

Syntax

FUNCTION='PIE';

Associated Variables

ANGLE= starting-angle

specifies the starting angle of the slice arc. The default is 0.00 (horizontal) if the ANGLE variable is not specified for the first slice. After the first slice, the default is the ending angle of the slice arc just drawn if ANGLE=. (missing). Therefore, you can specify consecutive pie slices more easily by omitting the start and end calculations that are otherwise required. If you want the next slice to start at an angle that is different from the ending angle of the previous slice, you must specify a value for the ANGLE variable.

COLOR= color

specifies the color of the pie slice, if a pattern is specified in the STYLE variable. If you specify STYLE= EMPTY , the COLOR variable also specifies the outline color of the pie slices. Color can be any SAS/GRAPH color name.

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

HSYS= coordinate-system

specifies the coordinate system for the SIZE variable. See HSYS Variable on page 649 for an explanation of coordinate-system .

HTML= link-string

specifies the text that defines the link for drill-down.

LINE=0 3

specifies which slice line (or lines) to draw. See Figure 25.10 on page 629 for line values and their actions. LINE=0 draws only the outside of the arc and enables you to draw a circle.

Figure 25.10: LINE Values Used with the PIE Function

ROTATE= rotation-angle

specifies the angle of rotation or the delta angle of the slice arc. The default is 0.00.

For example, if you specify these statements, the slice arc that is drawn begins at 90 degrees (vertical) and ends at 135 degrees (90+45):
```
 function='pie'; angle=90; rotate=45; output; 
```
The ANGLE variable is internally updated to the end value, 135 degrees. The value is modified only internally. If a second PIE is used and the ANGLE variable contains a missing value, the start angle is assumed to be the previous end, or 135 degrees. The arc continues from that point.

If you specify the previous statements and then specify these statements, the slice begins at 135 degrees (the end angle from the previous slice) and extends another 45 degrees to the end point, 180 degrees.
```
 function='pie'; angle=.; rotate=45; output; 
```
This action repeats for every missing angle in the sequence.

SIZE= radius

specifies the radius of the circle being drawn. The SIZE variable uses units that are determined by the HSYS variable.

STYLE= fill-pattern

specifies the value of the pattern that fills the pie slices. Fill-pattern can be the following pie patterns:

PSOLID

a solid fill.

PEMPTY

an empty fill.

P density<style<angle>>

a shaded pattern:

density can be 1 5
style can be X N
angle can be 0 360

For example, if STYLE= P5N15 , a pie slice with a fill of parallel lines is produced. The fill uses the heaviest density to draw the lines, and the parallel lines are drawn at a 15-degree angle from perpendicular to the radius of the pie slice. See also the discussion of fill patterns for pie and star charts in VALUE= on page 174.

WHEN= B A

specifies when to draw the pie slice in relation to other procedure output. See WHEN Variable on page 666.

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

define the center of the slice. The pivot point for all slices is the point referenced by X, Y, and Z (with PROC G3D only). The first PIE command that is issued sets the center at the (X,Y) value. If subsequent values for X and Y are missing, the coordinates of the center point are used.

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. Use the XC variable only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y or YC variable. Use the YC variable only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

PIECNTR Function

Sets new center and radius values for later use by the PIEXY function but does not draw an arc.

Updates: XLAST, YLAST

Syntax

FUNCTION='PIECNTR';

Associated Variables

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

HSYS= coordinate-system

specifies the coordinate system for the SIZE variable. See HSYS Variable on page 649 for an explanation of coordinate-system .

SIZE= radius

specifies the new radius of the pie slice. The new radius is used by a subsequent PIEXY function. The HSYS variable determines the SIZE variable units.

WHEN= B A

specifies when to draw the pie slice in relation to other procedure output. See WHEN Variable on page 666

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

define the center and radius of the slice. All slices are referenced from that center. Use the Z variable only with the G3D procedure.

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. Use the XC variable only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y or YC variable. Use the YC variable only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

PIEXY Function

Calculates a point on the outline of the slice arc.

Updates: XLAST, YLAST

Syntax

FUNCTION='PIEXY';

Associated Variables

ANGLE= rotation-angle

specifies the angle of rotation when moving around the perimeter of a pie. The ANGLE variable determines the angle at which the point is located relative to 0 (the three o clock position). The default is 0.00.

SIZE= radius- multiplier

determines the distance from the center of the slice to the point that is being calculated. The point's distance is the current value of the SIZE variable multiplied by the radius (that is, the SIZE variable) of the previously drawn slice. To position a graphics element inside the pie slice, set the SIZE variable to less than 1; to position it outside of the pie slice, set the SIZE variable to greater than 1. For example, if you specify these statements, the point calculated is 1.1 times the radius (where the radius is taken from the SIZE variable that is used with the previous FUNCTION= PIE or FUNCTION= PIECNTR observation).
```
 function='piexy'; size=1.1; output; 
```

WHEN= B A

specifies when to update the internal coordinate pair (XLAST, YLAST) in relation to other procedure output. See WHEN Variable on page 666.

Details

PIEXY does not draw anything but places the calculated coordinates of the point in the internal coordinate pair (XLAST, YLAST). Then you can use XLAST and YLAST with other functions to perform other graphics actions, such as labeling pie slices. If you need to use the calculated position for a text function, use the SWAP or CNTL2TXT to put (XLAST, YLAST) into (XLSTT, YLSTT).

PIEXY assumes that a pie slice has been drawn or that FUNCTION= PIECNTR has been used. Erroneous results can occur if a slice has not been drawn and PIEXY is invoked.

Figure 25.11 on page 632 shows a pie slice that is drawn with the PIE function. Figure 25.12 on page 633 shows a point beyond the arc that was calculated using the PIEXY function.

Figure 25.11: Pie Slice Drawn with the PIE Function

Figure 25.12: Point Calculated with the PIEXY Function

POINT Function

Places a single point at the (X, Y) coordinates in the color you specify. The point is one visible pixel in size.

Updates: XLAST, YLAST

Syntax

FUNCTION='POINT';

Associated Variables

COLOR= color

specifies the color of the point to be drawn. Color can be any SAS/GRAPH color name.

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates when used with HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

WHEN= B A

specifies when to draw the point in relation to other procedure output. See WHEN Variable on page 666

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

specify the coordinates of the point that is to be drawn. Use the Z variable only with the G3D procedure.

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. Use the XC variable only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y or YC variable. Use the YC variable only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

POLY Function

Specifies the beginning point of a polygon. Associated variables can define the fill pattern and color, as well as the line type that outlines the polygon.

Syntax

FUNCTION= POLY ;

Associated Variables

COLOR= color

specifies the color of the interior of the polygon, if a pattern is specified for the STYLE variable. The outline color is specified with the POLYCONT function. Color can be any SAS/GRAPH color name.

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with data coordinate systems 1, 2, 7, and 8.

HTML= link-string

specifies the text that defines the link for drill-down.

LINE=1 46

specifies the line type that outlines the polygon. See Specifying Line Types on page 207 for an illustration of the line types.

SIZE= thickness

specifies a line thickness for the polygon

STYLE= fill-pattern

specifies the value of the pattern that fills the polygon. Fill-pattern can be the following map patterns:

MSOLID

a solid pattern

MEMPTY

an empty pattern

M density < style < angle >>

a shaded pattern:

density can be 1 5
style can be X N
angle can be 0 360.

For example, if STYLE= MSOLID for the POLY function, the fill area that is drawn by the POLYCONT sequence uses a solid fill. If STYLE= M5N15 , the fill area uses a shaded fill of parallel lines. The fill-pattern value M5N15 specifies that the lines use the heaviest density, are parallel, and are drawn at a 15-degree angle from the horizontal. See also the discussion of fill patterns for maps in VALUE= on page 173.

WHEN= B A

specifies when to begin the polygon in relation to other procedure output. See WHEN Variable on page 666

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

specify the initial point of the polygon that is being created. Use the Z variable only with the G3D procedure.

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. Use the XC variable only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y or YC variable. Use the YC variable only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

Details

Use POLY with POLYCONT to define and fill areas in the graphics output. POLY and POLYCONT do not update the (XLAST, YLAST) coordinates.

POLYCONT Function

Continues drawing a polygon begun with the POLY function. POLYCONT specifies each successive point in the polygon definition.

Syntax

FUNCTION= POLYCONT ;

Associated Variables

COLOR= color

specifies the polygon outline color. Color can be any SAS/GRAPH color name. You can specify an outline color only with the first POLYCONT command in the sequence; all subsequent POLYCONT commands ignore the COLOR variable. If you do not specify a color, the POLYCONT function uses the interior color that was specified with the POLY function.

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

WHEN= B A

specifies when to draw the polygon in relation to other procedure output. See WHEN Variable on page 666

X= horizontal-coordinate

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

specify a point on the outline of the polygon that is being created. Use the Z variable only with the G3D procedure.

XSYS= coordinate-system

specifies the coordinate system for the X and XC variable. Use the XC variable only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y and YC variable. Use the YC variable only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

Details

The polygon definition is terminated by a new POLY command or by any of these functions:

BAR
DRAW
DRAW2TXT
FRAME
LABEL
MOVE
PIE
PIECNTR
PIEXY
POINT
SYMBOL

Use POLY and POLYCONT together to draw a polygon. The (X, Y) observation from the POLY function and the last (X, Y) observation from POLYCONT are assumed to connect. Thus, you are not required to respecify the first point. For example, these statements draw a pentagon like the one in Figure 25.13 on page 638:

 data house;     retain xsys ysys '3';     length function $ 8;        /* start at the lower left corner */     function='poly'; x=35; y=25; output;        /* move to the lower right corner */     function='polycont'; x=65; y=25; output;        /* move to the upper right corner */     function='polycont'; x=65; y=65; output;        /* move to the center top*/     function='polycont'; x=50; y=80; output;        /* move to the upper left corner and complete the figure */     function='polycont'; x=35; y=65; output;  run;  proc ganno anno=house;  run;  quit;

Figure 25.13: Pentagon Produced with the POLY and POLYCONT Functions

Missing values for the X and Y variables that are specified with POLYCONT are interpreted differently from the way that they are interpreted with the other functions. Other functions use the missing values to request a default value. POLYCONT interprets a missing value as a discontinuity (that is, a hole) in the polygon. If you are not using the data coordinate system and you specify an X or Y value of ˆ’ 999 in a POLYCONT observation, the default of (XLAST, YLAST) is used. Missing values indicate holes and are handled identically in the Annotate facility and the GMAP procedure. See Displaying Map Areas and Response Data on page 1005 for more information on handling missing values.

POP Function

Removes the (XLAST, YLAST) and (XLSTT, YLSTT) values from the LIFO stack and updates the internal coordinate pairs with the retrieved values.

Updates: (XLAST, YLAST) and (XLSTT, YLSTT)

Syntax

FUNCTION= POP ;

Details

Use POP when you want to access the values of (XLAST, YLAST) and (XLSTT, YLSTT) that you most recently stored with the PUSH function. See the PUSH function for a description of the LIFO stack.

PUSH Function

Adds current (XLAST, YLAST) and (XLSTT, YLSTT) values to the LIFO stack.

Syntax

FUNCTION= PUSH ;

Details

The LIFO (last-in-first-out) stack is a storage area where you can keep internal coordinate values for later use by utility functions without recalculating those values. LIFO stacks manage the stored data so that the last data stored in the stack is the first data removed from the stack.

Use the stack to save the current values of (XLAST, YLAST) and (XLSTT, YLSTT) and use them with functions later in the DATA step. You store and retrieve these values from the stack with the PUSH and POP functions. The PUSH function copies the current values of XLAST, YLAST, XLSTT, and YLSTT onto the stack. The POP function copies values from the stack into XLAST, YLAST. XLSTT, and YLSTT.

SWAP Function

Exchanges values of (XLAST, YLAST) with (XLSTT, YLSTT) and vice versa.

Updates: (XLAST, YLAST) and (XLSTT, YLSTT)

Syntax

FUNCTION= SWAP ;

Details

Use SWAP when you want to use both the (XLAST, YLAST) and (XLSTT, YLSTT) coordinates for text and nontext functions, respectively.

SYMBOL Function

Places symbols in the graphics output. Associated variables can specify the color, font, and height of the symbols displayed.

Updates: XLSTT, YLSTT

Syntax

FUNCTION= SYMBOL ;

Associated Variables

CBORDER= color CTEXT

draws a colored border around the text. Color can be any SAS/GRAPH color name.

CBOX= color CBACK

draws a solid, colored box behind the text. Color can be any SAS/GRAPH color name.

COLOR= color

specifies the symbol color. Color can be any SAS/GRAPH color name. The COLOR variable behaves in the same way as the COLOR= option in the SYMBOL statement. See COLOR= on page 185 for details

GROUP= group-value

MIDPOINT= midpoint-value

SUBGROUP= subgroup-value

specify coordinates for HBAR and VBAR charts from the GCHART procedure. Use these variables only with the data coordinate systems 1, 2, 7, and 8.

HSYS= coordinate-system

specifies the coordinate system for the SIZE variable. See HSYS Variable on page 649 for an explanation of coordinate-system .

HTML= link-string

specifies the text that defines the link for drill-down.

SIZE= height

specifies the height of the symbol that is being drawn, using units determined by the HSYS variable. The SIZE variable is equivalent to the HEIGHT= option in the SYMBOL statement. See HEIGHT= on page 187 for details.

STYLE= font " hardware-font-name " NONE ;

specifies the font that is used to draw the symbol that is specified by the TEXT variable. See STYLE Variable (Fonts) on page 661 for a description of the various font specifications.

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 FONT= on page 186 for details.

TEXT= special-symbol text-string ;

specifies the symbol to be displayed. Special-symbol can be up to eight characters long. Values for special-symbol are those described in the VALUE= option of the SYMBOL statement and are illustrated in VALUE= on page 199.

For client-side rendering using ActiveX, the following values are supported: plus, X, star, square, diamond, triangle, dot, circle, ", #, $, %, =. If a symbol is not supported, a plus sign (+) is drawn instead.

For client-side rendering using Java, the following values are supported: plus, X, star, square, diamond, triangle, dot (draws a circle), circle, *, +, >. If a symbol is not supported, a plus sign (+) is drawn instead.

If you also specify a text font with the STYLE variable, you can specify a text string that is displayed as the symbol. The maximum length for text-string is 200 characters.

When the TEXT variable is used with the SYMBOL function, it behaves the same as the VALUE= option in the SYMBOL statement. See VALUE= on page 199 for details.

WHEN= B A

specifies when to draw the symbols in relation to other procedure output. See WHEN Variable on page 666

Y= vertical-coordinate

Z= depth-coordinate (PROC G3D only)

XC= character-type-horizontal-coordinate

YC= character-type-vertical-coordinate

specify the point at which the symbol is placed. Use the Z variable only with the G3D procedure.

XSYS= coordinate-system

specifies the coordinate system for the X or XC variable. Use the XC variable only with XSYS= 2 . See XSYS Variable on page 670 for an explanation of coordinate-system .

YSYS= coordinate-system

specifies the coordinate system for the Y or YC variable. Use the YC variable only with YSYS= 2 . See YSYS Variable on page 674 for an explanation of coordinate-system .

ZSYS= coordinate-system

specifies the coordinate system for the Z variable. See ZSYS Variable on page 676 for an explanation of coordinate-system .

Details

SYMBOL is similar to the LABEL function with these exceptions:

SYMBOL draws symbols. If you do not specify a font, SYMBOL can use the symbols found in Figure 7.21 on page 202.
The text cannot be rotated or angled.
The text string cannot be longer than eight characters.
The text string is always centered with respect to x and y .

TXT2CNTL Function

Copies the values (XLSTT, YLSTT) to (XLAST, YLAST), replacing previous values of (XLAST, YLAST).

Syntax

FUNCTION='TXT2CNTL';

Details

TXT2CNTL allows nontext functions to use the ending position of a text string as a starting or ending point.

BAR Function

Syntax

Associated Variables

Details

CNTL2TXT Function

Syntax

Details

COMMENT Function

Syntax

Associated Variables

DEBUG Function

Syntax

DRAW Function

Syntax

Associated Variables

DRAW2TXT Function

Syntax

Associated Variables

Details

FRAME Function

Syntax

Associated Variables

Details

IMAGE Function

Syntax

Associated Variables

Details

LABEL Function

Syntax

Associated Variables

MOVE Function

Syntax

Associated Variables

Details

PIE Function

Syntax

Associated Variables

See Also

PIECNTR Function

Syntax

Associated Variables

PIEXY Function

Syntax

Associated Variables

Details

See Also

POINT Function

Syntax

Associated Variables

POLY Function

Syntax

Associated Variables

Details

See Also

POLYCONT Function

Syntax

Associated Variables

Details

POP Function

Syntax

Details

PUSH Function

Syntax

Details

SWAP Function

Syntax

Details

SYMBOL Function

Syntax

Associated Variables

Details

TXT2CNTL Function

Syntax

Details