Graph Applet HTML Generator

Graph Applet HTML Generator Syntax Reference

The syntax for invoking the Graph Applet HTML Generator is

   %DS2GRAF(argument=value, argument=value,...)

You must include the DS2GRAF macro call with your SAS code. You cannot call it from a SAS command line. When including the macro call in your SAS code, you can use a list of arguments that are contained within parentheses and are separated with commas.

Use this syntax reference to determine the valid values and uses for the Graph Applet HTML Generator. To help you locate the appropriate arguments, we have grouped them into the following categories:

Generating and Saving the HTML File
Defining How the Data is Graphed
Specifying Page and Graph Formatting
Enabling Character Transcoding
Using Style Sheets

Some arguments are required and are noted as such in their descriptions. If an argument is required only in some cases, the exceptions are noted. The macro provides default values for some arguments. (Default values are shown in bold.) If the default value is acceptable, do not include the argument on the macro invocation. If you want to use a value other than the default, specify the argument and the value on the macro invocation.

Note: For SAS 9.2 or later, the DS2GRAF macro is no longer supported. The documentation on this Web site is for Version 9.0 or earlier of SAS. Please migrate your applications to use the GPLOT/GCHART procedures with ODS and the Java or ActiveX device driver.

Generating and Saving the HTML File

Note: All the arguments in this section are required unless you are accepting the default value.

device=java | activex

specifies if the HTML will be rendered using Graph Applet or SAS/GRAPH Control for ActiveX. The default is to generate HTML for use by the Graph Applet. If you are not using the Graph Applet, you must specify DEVICE=ACTIVEX.

htmlfile=external-filename

specifies the name of the HTML file where the formatted output will be written. If the file you specify does not exist, it is created for you.

Note: HTMLFILE and HTMLFREF are mutually exclusive arguments.

htmlfref=fileref

specifies the SAS fileref that points to the location of the HTML file where the formatted output should be written. If the file you specify does not exist, it is created for you. When naming files, avoid using any of these reserved names.

Note: HTMLFILE and HTMLFREF are mutually exclusive arguments.

openmode=APPEND | REPLACE

indicates whether the new HTML output overwrites the information currently in the specified file or if the new output is appended to the end of the existing file. The default value is REPLACE. If you do not want to replace the current contents, supply APPEND to add your new HTML-enhanced output to the end of an existing file.

Note: OPENMODE=APPEND is not valid is you are writing your resulting HTML to a PDS on z/OS.

pw=password

specifies the password needed to access a password-protected data set. This argument is required if the data set has a READ or PW password. (You do not need to specify this argument if the data set has only WRITE or ALTER passwords.)

runmode=B | S

specifies whether you are running the macro in batch or server mode. Batch mode means that you are submitting the DS2GRAF macro in the Program Editor or you have included it in a SAS program. Server mode is used with Application Dispatcher applications and causes the generator to print the HTTP header required by Application Dispatcher. For more information, refer to the SAS/IntrNet Application Dispatcher documentation at http://support.sas.com/documentation.

Defining How Data is Graphed

The following arguments specify how the data should be processed. All required arguments are explicitly noted.

data=SAS-data-set-name

specifies the SAS data set that contains the data you want to graph. This argument is required. However, if you omit the data set name, the generator attempts to use the most recently created SAS data set.

specifies the type of graph to generate. This argument is required. The table below shows the supported values for this argument.

Value	Description
`BAR`	Vertical Bar Chart
`VBAR`	Vertical Bar Chart
`HBAR`	Horizontal Bar Chart
`PIE`	Pie Chart
`PLOT`	Scatter Plot without points joined
`SCATTER`	Scatter Plot without points joined
`LINE`	Scatter Plot with points joined

shape=value

specifies the shape of the bar or marker in the graph. The table below lists the supported values for this argument. Note that the values are based on the value you supplied for GRAPHTYP.

Graph Type	Value	Default for Graph Applet	Default for SAS/GRAPH Control for ActiveX
Bar Charts	`Block` `Cylinder` `Hexagon` `Pentagon` `Prism` `Star`	`Hexagon`	`Cylinder`
Scatter Plots	`Box` `Circle` `Cross` `Sphere` `None`	`Box`	`Sphere`
Pie Charts	Not Supported

The default values for the SHAPE argument are:

legend=Y | N

determines whether or not a legend is displayed. A legend is displayed by default.

state=Y | N

determines whether or not state is saved with a cookie. The default action is to attempt to save state. This argument is not valid for use with the ActiveX control.

To save state means that you can customize the graphic displayed by the applet (using the pop-up menus), drill down within the graphic, and return to the first graphic as you customized it. If you do not save state, when you return to the graphic it will appear as it did before you customized it.

Note that saving state does not work in all browsers. The browser must support scripting (JavaScript or VBScript) and the use of cookies.

depvar=var

specifies which SAS variable you want represented as the dependent variable in your graph. This argument is required.

depthvar=variable_name

specifies the variable used to create the third dimension in a 3-D graph. The values for this variable become the Z axis.

This argument is valid on with vertical bar charts and scatter plots.

indepvar=var

specifies which SAS variable you want represented as the independent variable in your graph. This argument is required.

groupvar=var

specifies which SAS variable you want represented as the group variable in your graph. This variable is initally ignored if you specify IGGROUP=Y.

sbgrpvar=var

specifies which SAS variable you want represented as the subgroup variable in your graph. This variable is initially ignored if you specify IGSBGRP=Y.

cntlout=value

specifies the name of the CNTLOUT data set that you generated using PROC FORMAT. The information in this data set is used to generate JavaScript functions that enable support for user-defined formats. Because the JavaScript requires that all user-defined formats be in this data set, you should always generate the data set, not modify it by hand. The PROC FORMAT statement used to build the data set should be:

   proc format cntlout=data_set_name (where=(type is ('C' 'N' 'P'))) <format_options>

Refer to the PROC FORMAT documentation for information on generating a CNTLOUT data set.

Note: This argument is not valid for use with the ActiveX control.

drildown=Y | N

determines whether or not the drill-down capability is enabled. The default value is N (drill down is not enabled).

drilfunc=value

specifies the name of the JavaScript function that you have written and made available to the HTML file. In most cases, the provided drill behavior is sufficient. If it is not sufficient, and you are comfortable creating your own script, you can use this argument to override the default drill-down capability.

drilmode=ANY | LOCAL | HTML | SCRIPT

specifies the type of drill down. The default is value is ANY, which means that when the applet receives a drill-down event, it attempts to perform a "local" drill down. If the local drill down isn't successful, it attempts an "html" drill down, followed by a "script" drill down.

Notes:

Use LOCAL when you want to drill down on a subgroup in a chart. Local drill down is not valid for use with the ActiveX control.
You must specify SCRIPT if you are also using DRILFUNC.
You must specify a DRILURL if you are using DRILMODE=HTML.

drilstrp=N | Y | C

removes preceding and trailing white space from drill-down substitution patterns before adding them the generated drill-down string. The default value is N, which is also achieved by omitting this argument from the macro call. Use the values as described below:

N leaves the drill-down string unaltered.
Y removes the white space and blanks from the beginning and end of the drill-down string.
C compresses (removes) all white space and blanks in the drill-down string.

Note: This argument is not valid for use with the ActiveX control

driltarg=value

specifies the name for the target window for where the drill-down results are to be displayed. The default is the current browser window. The names can be either values assigned in the HTML page ( e.g., names for FRAMES) or the standard HTML target names such as:

_self for the current window
_blank for a new window
_parent for the parent window for the frameset
_top for the "top" document

Refer to an HTML syntax guide for the valid values of a TARGET attribute.

drilurl=http://your-server-name/%nrstr({&tag,[f]}{...}).html

defines the URL to display when the user clicks on a graph element. The URL contains variables that enable the applet to drill down on any valid element. For information about how to supply the drill URL, see Enabling Drill Down.

formats=Y | N

indicates whether to use the formats defined in the SAS data set. Graph Applet and the ActiveX control support these formats, which are supplied by SAS. If you do not want to use the defined formats when graphing this data, then specify FORMATS=N.

Graph Applet also supports user-defined formats. If your formats are user-defined, you must also specify the CNTLOUT argument.

iggroup=Y | N

specifies to initially ignore any group variable. That is, initially, the chart does not use the variable assigned via the GROUPVAR argument.

This argument is not valid for use with the ActiveX control.

igsbgrp=Y | N

specifies to initially ignore any subgroup variable. That is, initially, the chart does not use the variable assigned via the SBGRPVAR argument.

This argument is not valid for use with the ActiveX control.

labels=Y | N

indicates whether to use the SAS variable labels defined in the data set as your graph labels. If you do not specify this argument, the generator attempts to use the variable label. If a label does not exist, the generator uses the variable name. Specify LABELS=N to force the generator to use variable names in your graph instead of the variable labels.

round=number

rounds the values of numeric variables to the number of decimal places specified by NUMBER.

Note: For better formatted output, apply a format to the appropriate data values prior to invoking the Graph Applet HTML Generator.

where=where-expression

specifies a valid WHERE clause that selects observations from the SAS data set. Using this argument, you can subset your data based on the criteria specified in the where expression.

Note: If your expression contains any special characters (for example, % , & ), include %NRBQUOTE in the argument in order to process these characters correctly. This example shows the correct way to specify Int%.

   where=%NRBQUOTE(value="Int%")

Specifying Page and Graph Formatting

The following arguments provide formatting information to the the Graph Applet HTML Generator. The generator does not check for errors on fonts, colors, or sizes you specify. It simply allows any value you type. So, you should specify values that are supported on the system where the HTML page will be viewed.

Giving color to graph elements

You can specify the color associated with the areas of the applet or the ActiveX control. Use the following arguments to specify these colors. You can specify color values as a color name or a RGB value. See the list of color names that are supported by Graph Applet. (No equivalent list is provided for the ActiveX control.)

cback=value

specifies a background color for the applet or control. This color should be a good contrast for your backdrop color and the color of your text.

cbackdrp=value

specifies the color of the backdrop in the actual applet or for the walls of the ActiveX control. This color should be a good contrasting color with your foreground color.

cfore=value

specifies the foreground color. This color is the first color used in the bars of a bar chart.

Note: This attribute is not supported in Release 8.1 or later of the SAS System.

colors=value1 value2 ...

specifies the list of colors to use in the graphic. When specifying colors, separate individual color values using a space, not a comma or a vertical bar.

colorvar=var

specifies the variable whose color should be applied to the color of the markers in a scatter plot.

coutline=value

specifies the outline color. This color is used to outline:

the bars on bar charts.
the slices on pie charts.
the symbol and the line on scatter plots.

cpieside=value | SAME

specifies the color of the side of a 3-D pie chart. If you specify a color value, that color is used as the side color. If you do not include CPIESIDE in the macro invocation, or if you specify SAME, the side color is the same as the top color for the slice of the pie chart.

gback=VERTICAL | HORIZONTAL

instructs the applet to draw a gradient-colored background and specifies the orientation of the color gradient. The colors that are used to draw the background are defined by the values of the GBACKS and GBACKE arguments. The GBACK argument is ignored if a value is specified for the IBACKLOC argument.

gbacke=color | BLUE

specifies the bottom color if GBACK=VERTICAL or the right color if GBACK=HORIZONTAL.

gbacks=color | WHITE

specifies the top color if GBACK=VERTICAL or the left color if GBACK=HORIZONTAL.

mcolors=value1 value2 ...

specifies the list of colors that are available to users from the Colors selection of the Graph menu. When specifying colors, separate the color values using a space, not a comma or a vertical bar.

If this argument is not specified but a value was specified for colors, the the pop-up menu will display the colors specified in the colors argument. Otherwise, predefined default colors will be listed in the menu.

Note: This argument is not valid for use with the ActiveX control.

Defining the appearance of the graph

In addition to specifying colors for elements in the graph, you can use the following arguments to define other appearance aspects.

backdrp=Y | N

indicates that you want to use an image as a background for the applet. If you specify Y, you must also specify the IBACKLOC argument. If you specify N for this argument, a background color (CBACK) is used.

Notes:

This argument is not valid for use with the ActiveX control.
This argument is valid only for Release 8.2 and earlier of SAS.

grid=Y | N

displays a grid on the graph. If you do not want the graph to contain the grid, specify GRID=N.

ibackloc=image_URL

provides a URL for the image you want to use as a backdrop for the applet area.

This argument is not valid for use with the ActiveX control.

ibackpos=CENTER | SCALE | TILE | POSITION

specifies how to display the background image. There is no default value, so you must specify one of the following:

CENTER: center the image in the applet space
SCALE: scale the image so that it files the space for the applet.
TILE: repeat the image at its normal size (tile) until so that it fills the applet space.
POSITION: position the image, without scaling it, at the location specified by the IBACKX and IBACKY arguments.

This argument is not valid for use with the ActiveX control.

ibackx=x-coordinate ibacky=y-coordinate

specifies the x and y coordinates respectively of the upper left hand corner of the image. Positive values of x and y are relative to the upper left corner of the background area while negative values are relative to the lower right corner of the background area.

You must specify values for both of these arguments if you also specify IBACKPOS=POSITION.

ibackurl=URL

specifies the URL that will be displayed when a user clicks on the background image. This argument is valid only with IBACKPOS=POSITION. If you are including the Powered by SAS logo, you must use this argument to link the image to the SAS Web site.

simpleth=integer | NEVER | 1000

specifies the threshold for determining whether the graph must be rendered using simple geometry. If the number of elements in the chart is equal to or greater than the value specified by this argument, then simple geometry is used (that is, the markers in the plot are rendered in a simpler fashion). If SIMPLETH=NEVER is specified, then simple geometry is never used, regardless of the number of chart elements.

This argument is not valid for use with the ActiveX control.

styleby=CATEGORY | CHART | GROUP | SERIES | SUBGROUP

specifies how colors are applied to the chart.

CATEGORY: the color changes for each category
CHART: all elements in the chart are rendered in one color
GROUP: the color of the element changes based on changing values of the group variable
SERIES: the color of the element changes based on changing values of the depth variable
SUBGROUP: the color of the element changes based on changing values of the subgroup variable.

Note: When a value is specified for the SBGRPVAR argument, then the STYLEBY argument is ignored

view2d=N | Y

indicates how to display the graph. By default, this argument is set to N, which means that the graph is displayed as a three-dimensional graph. If you want to render the graph in only two dimensions, you must include this argument with a value of Y.

Note: Beginning with Release 8.2, you can use this argument with the ActiveX control.

Defining the <APPLET> or <OBJECT> tag

The arguments defined in this section appear on the <APPLET> or <OBJECT> tag in the HTML file. All required arguments are explicitly noted.

archive=value

specifies a URL for the applet JAR file (graphapp.jar). The recommended location (described in the installation instructions) is http://web_server_name/sasweb/graph/graphapp.jar.

This argument is required for Graph Applet. It is not valid for use with the ActiveX control.

codebase=value

specifies a URL that identifies the directory used to find the .class files needed for the applet, or it specifies the path to the installation program for the ActiveX control.

This argument is required for Graph Applet. It is recommended, but it is not required for the ActiveX control.

id=value

specifies the name for this instance of the SAS/GRAPH Control for ActiveX. You need to use this argument only if you have more than one instance of the <OBJECT> tag in your HTML file, and you have included your own scripts or DHTML that communicates with or acts on a particular instance of the control.

name=value

specifies the name for this instance of the applet. You need to use this argument only if you have more than one instance of the <APPLET> tag in your HTML file, and you have included your own scripts or DHTML that communicates with or acts on a particular instance of the applet.

height=value

specifies the height in pixels of the applet or control. The default value is 400.

width=value

specifies the width in pixels of the applet or control. The default value is 750.

align=value

specifies the positioning of the applet or control. Possible values are

 LEFT, RIGHT, TOP, BOTTOM,
TEXTTOP, MIDDLE, ABSMIDDLE, BASELINE, BOTTOM

or ABSBOTTOM.

alt=value

used with Graph Applet to specify the text that should be displayed by browsers that understand the <APPLET> tag, but cannot run Java applets. The default value is SAS Institute Inc. Graph Applet.

Note: This argument is not valid for use with the ActiveX control.

hspace=value

specifies the amount of horizontal space in pixels to the left and right of the applet or control.

vspace=value

specifies the amount of vertical space in pixels above and below the applet or control.

General page formatting

The arguments BGTYPE, BRTITLE, CENTER, CTEXT and DOCTYPE apply to the entire page for the current invocation of the macro. So if you append data, the attributes of existing results will not change. You may want to use these arguments only when you replace, rather than append, pages.

The rendering of some formatting arguments varies per browser. Some browsers may not support some of these options.

bgtype=NONE | COLOR | IMAGE

specifies the type of background for your Web page. If you specify COLOR or IMAGE as the value, you must also use the BG argument. Valid values for BGTYPE are

NONE: does not use a background on your Web page. This is the default.
COLOR: causes the generator to use the background color specified in the BG argument. If you specify COLOR as the value, you must also specify the color in the BG argument.
IMAGE: indicates that you want to use a custom image as a background. If you specify IMAGE as the value, you must also specify the BG argument to provide the name and location of the image. Some browsers may not support the use of background images.

bg=value

If you specified BGTYPE=IMAGE, value identifies the fully-qualified path and filename of a background image that you want to use on your Web page. If you specified BGTYPE=COLOR, value indicates the specific background color you want to use on your page. You can specify color values using the color name or the RGB value.

brtitle=value

specifies the value that appears as the title in the browser window title bar. By default, no title is displayed.

center=Y | N

determines whether all the output generated by the current invocation of the macro is centered. (See appending information under General Page Formatting.) The default is no center (N).

ctext=value

indicates whether you use the default global text color defined by the browser or by the color specified here. This affects all the text generated by the current invocation of the macro. You can override the color for an element using the color specification arguments. For example, specifying a color for title lines in your via the TCOLOR argument overrides the value specified by CTEXT. You can specify color values using the color name or the RGB value.

doctype=3.2 | value

specifies the information that is provided for the DOCTYPE tag in the HTML file. The default value is 3.2, which writes the following line to the top of your HTML file:

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

If you want something other than the default text, you can provide the exact line to be added. If you supply a blank for value, nothing is added to the top of the file. If you supply a value other than 3.2, you must include the exact text that you want added. For example, if you want to reference a different DTD, you must provide the entire string, including !DOCTYPE and the opening and closing angle brackets.

encode=Y | N

specifies whether the generator replaces angle brackets with the appropriate ASCII character representation so that the brackets display in the browser. To have the Graph Applet Generator check for the characters "<" and ">" and encode them as ASCII characters, select Y. This will display the actual brackets in the browser. By default, the brackets will be encoded. To not encode them and have the generator pass the brackets to the browser (where the browser will attempt to act on them as an HTML-formatting instruction), select N.

pagepart=ALL | HEAD | BODY | FOOT

specifies which parts of the HTML page is written to the file. You may want to write only some parts of the page if you are appending the results to an existing file. The valid values are:

ALL: writes the HTML header information, your formatted SAS data, and the HTML footer information to the specified file. This is the default behavior and it should be used when you are not appending additional information to the file.
HEAD: writes the HTML header information and your formatted SAS data to the HTML file. It does not include the HTML footer information. You should use HEAD when you are going to append additional output to this file from one of the formatters or from the Graph Applet Generator.
BODY: writes only your formatted SAS data to the specified file.
FOOT: writes your formatted SAS data and the HTML footer information to the specified file.

For more information, see Using Page Formats.

saspower=value

adds the Powered by SAS logo to the bottom of the HTML page. You must provide the name and location of the image. This image automatically links to the SAS Web site. The value for this argument should be a fully-qualified pathname or valid URL. The default is not to display any image. Omit this argument if you do not want to use this image or have not acquired the logo.

Use of this image is by permission only. See the Powered by SAS logo guidelines and agreement.

septype=NONE | RULE | IMAGE

specifies the type of separator that you want to use between the applets in your output. The generator uses a separator whenever it is invoked. Valid values are

NONE: overrides the default value and does not include a separator between the applets in your output.
RULE: This is the default. This value causes the generator to separate the applets in your output by adding the <HR> tag (a horizontal rule) to the HTML file following the end of the applet.
IMAGE: indicates that you want to use a custom image as a separator. If you specify IMAGE, you must also specify the SEPLOC argument to provide the name and location of the image that you want to use.

seploc=image-location

specifies the location of the image that you want to use as a separator between applets in the output. This argument is required if you specify SEPTYPE=IMAGE. The value for this argument should be a fully-qualified pathname or valid URL.

Formatting individual elements

The remainder of the arguments control the formatting of individual elements in the output. If you specify formatting information for an element not included in your output, the information is simply ignored.

When you specify any of these arguments, an HTML tag such as <FONT COLOR=value> is added to all the appropriate lines in your HTML-formatted output.

The TITLE lines

tcolor=value: specifies a color for the SAS TITLE lines. You can specify color values using the color name or the RGB value.
tface=value: specifies a font for the SAS TITLE lines. Valid values are browser specific.
tsize=value: specifies the size of the font used to display SAS TITLE lines. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
ttag=value: specifies the HTML tag name associated with the SAS TITLE lines. The default value is PREFORMATTED + HEADER 3.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the Graph Applet Generator.

The FOOTNOTE lines

fcolor=value: specifies a color for the SAS FOOTNOTE lines. You can specify color values using the color name or the RGB value.
fface=value: specifies a font for the SAS FOOTNOTE lines. Valid values are browser specific.
fsize=value: specifies the default size of the font used to display the SAS FOOTNOTE lines. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
ftag=value: specifies the HTML tag name associated with the SAS FOOTNOTE lines. The default value is PREFORMATTED + HEADER 3.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the generator.

Enabling Character Transcoding

tranlist=transcoding-list-name
charset=character-set-name

For a description of these arguments and an explanation about how to use them, see Implementing Character Transcoding in "Character Transcoding and National Language Support."

Using Style Sheets

Arguments that embed or link to your style sheets

Use the following arguments to specify the location of your style sheets. These arguments are valid for all formatters and are described in Syntax for Including Style Sheets:

Arguments that enable you to specify the CLASS information

bdclass=value: specifies the name of the style sheet class to be used for the document body.
fclass=value: specifies the name of the style sheet class to be used for footnote lines.
sepclass=value: specifies the name of the style sheet class to be used for the page separator. If the separator type is RULE, the supplied value is used on the CLASS attribute of the HR tag. For an IMAGE separator, the supplied value is used on the CLASS attribute of the IMG tag.
spclass=value: specifies the name of the style sheet class to be used for the Powered by SAS logo.
tclass=value: specifies the name of the style sheet class to be used for title lines.

Note: z/OS is the successor to the OS/390 and MVS operating systems. SAS/IntrNet 9.1 for z/OS is supported on the MVS, OS/390, and z/OS operating systems and, throughout this document, any reference to z/OS also applies to OS/390 and MVS, unless otherwise stated.