Using SAS/GRAPH to Generate Client Graphs for ActiveX or Java

Beginning with Version 8, SAS/GRAPH provides two device drivers for generating SAS/GRAPH output as client graphs: the ACTIVEX and JAVA drivers. When used with the Output Delivery System (ODS) to create HTML output, both drivers generate JavaScript in the output HTML file. The ACTIVEX driver generates JavaScript that an ActiveX-enabled Web browser can use to render a graph using the SAS/GRAPH Control for ActiveX. The JAVA driver generates JavaScript that a Java-enabled Web browser can use to render a graph using one of the SAS/GRAPH Applets for Java.

The ACTIVEX and JAVA drivers must be used with ODS to produce HTML output, and they can only be used with procedures GCHART, GCONTOUR, GMAP, GPLOT, or G3D.

Note. Beginning with Release 8.1, you can also use the JAVAMETA driver with ODS. For details, see the SAS/GRAPH MetaViewApplet.

• SAS/GRAPH and ODS
• Using the ACTIVEX or JAVA Driver
• Archive Locations for Required ActiveX or Java Class Files
• Drill-down Capabilities in the Client Graphs

SAS/GRAPH and ODS

ODS (the Output Delivery System), first introduced in version 7.01 of The SAS System, provides a new way of producing SAS output. Previously, when you ran graphical procedures, you produced a GRSEG entry or an image or some other static representation. With ODS, you can generate that output in HTML files, using the DEVICE= option on a GOPTIONS statement to indicate the type of output you want to display in your HTML pages.

In SAS/GRAPH Version 7.01, only the GIF device driver was available for use with ODS. DEVICE=GIF generates all graphs as GIF images. SAS/GRAPH Version 8 introduced the ACTIVEX and JAVA device drivers for use with ODS. DEVICE=ACTIVEX generates JavaScript that allows an ActiveX-enabled Web browser to render graphs using the SAS/GRAPH Control for ActiveX. DEVICE=JAVA generates JavaScript that allows a Java-enabled Web browser to render graphs using one of the SAS/GRAPH Applets for Java.

Whereas GIF images are rendered on the SAS server (the computer where the SAS session is running), the client graphs are rendered on the client computer that is running the browser and displaying the graph. Rendering a graph on the client computer makes it possible for you to customize that graph without re-running the SAS/GRAPH program that generated it.

The ODS HTML output contains all of the HTML tags and JavaScript code needed to reproduce SAS/GRAPH procedure output on the client computer. When the HTML file is opened in a viewer (for example, a Web browser) that is capable of rendering a graph from JavaScript, you can customize, query and otherwise interact with the graph. For example, you can change a bar chart to a pie chart, and then change the colors of the pie slices.

Using the ACTIVEX or JAVA Driver

To use the ACTIVEX or JAVA driver, you must also use ODS. Your SAS/GRAPH program must do each of the following:

• Use the ODS HTML statement to specify HTML output. Use the BODY= (alias FILE=) option to specify a name for the output HTML file. When used with the ACTIVEX or JAVA drivers, ODS automatically creates the HTML file and writes to it the HTML tags and JavaScript needed to display the graphs generated while the HTML destination is open.
• Use the DEVICE= option on a GOPTIONS statement. Specify DEVICE=ACTIVEX to generate an HTML page for the SAS/GRAPH Control for ActiveX. Specify DEVICE=JAVA to generate an HTML page for a SAS/GRAPH Applet for Java.
• Run a graphics procedures that supports the ACTIVEX or JAVA device drivers. Those procedures are GCHART, GCONTOUR, GMAP, GPLOT, and G3D.
• Close the HTML destination by specifying an ODS HTML CLOSE statement. When the output HTML file is opened in an appropriate browser, the browser executes the JavaScript, which renders all the generated graphs.

The following code generates a GraphApplet for Java in the output file myGraph.html. The code assumes an input data set named MyData, which contains the variable X:

ods html body='myGraph.html';
goptions device=java;
proc gchart data=myData;
  vbar X;
run;
quit;

ods html close;

If you are familiar with using ODS with SAS/GRAPH, you can see that there are no special requirements for generating client graphs for ActiveX or Java. The ODS syntax is the same as it is for generating GIF images. The device driver that you specify on GOPTIONS DEVICE= determines the type of output that is generated.

Having said that, there are some considerations that you need to make when generating client graphs for ActiveX or Java:

• Only procedures GCHART, GCONTOUR, GMAP, GPLOT, or G3D support the ACTIVEX and JAVA drivers. If you specify these drivers with other SAS/GRAPH procedures, the GIF driver is used instead.
• With the graphics procedures that support the ACTIVEX and JAVA drivers, some features are optimized for the technology used to render the graph. Thus, the ACTIVEX and JAVA drivers do not support every option on those procedures that they support. Similarly, some SAS/GRAPH procedures and global statements have special syntax that is only supported by the ACTIVEX or JAVA drivers. This special syntax has no effect on the server graphs that are generated by other device drivers. For information on the features that are supported by the ACTIVEX and JAVA device drivers, visit the SAS Institute Technical Support Web site and search for Technical Note TS-602 (for the ACTIVEX driver) or Technical Note TS-601 (for the JAVA driver).
• The ODS HTML statement's PARAMETERS= option allows you to specify one or more parameters that can be applied to the client graphs. The parameters set specific graph features, such as the background color or the name of an image to use as the applet background. These parameters are listed and defined in the SAS System Help for the ODS HTML statement. The quickest way to access the documentation for them is to type help ods html in the SAS command line, scroll to the ODS HTML statement, select options, and then scroll to the PARAMETERS= option.
• If you plan to distribute your output HTML files to other people, your SAS/GRAPH program may have to specify archive information that any viewing browser can use to find the class files needed to render the client graphs. For details, see Archive Locations for Required ActiveX and Java Class Files.

Archive Locations for Required ActiveX and Java Class Files

ActiveX controls and Java applets are embedded in Web pages. Unlike embedded images, such as GIF files, an ActiveX control or Java applet is a running program that can react to user input and perform whatever actions have been developed for it. When a browser sees the tag that references the control or the applet, it reads that tag to find out the name and location of the executable code that implements the functionality.

By default in most operating environments, SAS/GRAPH points the browser to the location where The SAS System install process placed the executable code on the computer that generated the graph. If the graph is viewed on the same computer, then the needed file(s) should be found automatically. However, to be able to distribute the graphs for viewing on other computers, you may need to use the ODS HTML statement to specify an archive location that enables those computers to find the required files. The ODS syntax depends on whether you generate a graph for use with ActiveX or Java.

• Archive Locations: SAS/GRAPH Control for ActiveX
• Archive Locations: SAS/GRAPH Applets for Java

Archive Locations: SAS/GRAPH Control for ActiveX

Similar to a PC application, an ActiveX control must be installed on a computer before it can be used. Once installed, it can be used on that computer any time that it is needed.

There are two installation scenarios for the SAS/GRAPH Control for ActiveX:

• The control is installed automatically as part of the install process for SAS/GRAPH or SAS Enterprise Guide
• The control can be installed separately by the setup program, SASGraph.exe.
  • A browser will run the setup program automatically if the path to the program is specified as an attribute on the HTML tag that references the graph.
  • A user can run the setup program independently on a computer that needs the control installed.

During the installation process, the control's class ID, its unique identifier, is entered into the Window's Registry, along with the path to its executable code. Any ActiveX-enabled viewer that wants to use the control calls it by its Class ID and retrieves its associated path from the Registry.

Within an HTML page, the SAS/GRAPH Control for ActiveX is referenced in an <OBJECT> tag, which has a required CLASSID attribute that identifies the control. The <OBJECT> tag resembles the following:

<OBJECT ID="GIDX"
 CLASSID="CLSID:1B5127F3-66C3-11d3-8788-00C04F387B43"
 Width=640
 Height=480
 Align=TOP
>

When a browser sees the <OBJECT> tag, it reads the value that is assigned to the CLASSID attribute, and then looks in the Windows Registry for a control with that ID. If it finds the ID, then the browser retrieves the path to the control's executable code. If it does not find the ID, then the browser returns to the <OBJECT> tag in the HTML file and looks for an optional CODEBASE attribute on the tag. The CODEBASE attribute's value is a string representing the path to the setup program that can install the control. If the CODEBASE attribute is missing, then the browser cannot install the control and so cannot display it on the Web page. If the attribute is present, then the browser retrieves the location of the control's setup program and executes that program, which installs the control on the local computer.

Specifying an Archive Location for the SAS/GRAPH Control for ActiveX

By default, SAS/GRAPH omits the CODEBASE attribute from the <OBJECT> tag that references the SAS/GRAPH Control for ActiveX in an output HTML file. If you view the graph on the same computer that generated the HTML file, then the browser should have no trouble finding the control's executable code. However, if you wish to publish your output on the Web or to mail the results to someone else, it is wise to provide the path to the setup program so that the SAS/GRAPH Control for ActiveX can, if necessary, be installed on the machine that is reading the results. If you provide the path on the CODEBASE attribute, then any browser that opens the HTML file can install the control on the local computer, provided the computer has access to the file at the location that you specify. If you do not provide the path to the setup program, then your users must install the control independently in order to view it on their computers.

To point the CODEBASE attribute to the setup program's location, use the ARCHIVE= option on the ODS HTML statement. On ARCHIVE=, specify a string that represents the location of the executable file, SASGraph.exe. The string that you specify will be used to generate the appropriate setting on the CODEBASE attribute in the output HTML file. Before specifying that string, consider the following:

• The CODEBASE attribute is a URL specifying the location of the control. It can point to a location on a local or networked computer, or it can point to an HTTP link location. It may be a full URL (for example, http://your_server/sasweb/graph/sasgraph.exe) or relative to your Web server (/sasweb/graph/sasgraph.exe). If you are publishing HTML only on Web servers where the control is installed in a common location, it is generally recommended that you use the shorter, relative URL. This will allow the HTML to be moved to any Web server without modifying the HTML (assuming the control is installed on that serve). If you are creating HTML to be viewed directly by a file: URL, sent by e-mail, or copied to Web servers without the control installed, you should use a full URL to point to the SASGraph.exe file at a known location.
• You must specify a string that the browser can interpret. If the setup program is on a local or networked computer, you can simply specify the Windows path to it or use the FILE protocol. If it is on a Web server, use the HTTP protocol.
• You must be certain that the CODEBASE attribute points to file SASGraph.exe in a location that all your users can access. If the file does not already reside in such a location at your site, SAS Institute provides two locations where you can get a copy of it. The file is on the Client Side Components CD-ROM that ships with The SAS System when you license SAS/GRAPH. If that CD-ROM is not available, you can download the file from the SAS Web site. Although you can point CODEBASE to the setup program's location on the SAS site, it is usually better to download the executable file, copy it to a local network location where your users can access it, and point the CODEBASE attribute to that local network location.
• If you have already generated an HTML page without the path to the setup program, you or your users can edit the HTML file directly to add the CODEBASE attribute to the <OBJECT> tag. Alternatively, the setup program can be run like any other setup program on the computer that needs to install the control. For instructions, see Installing the SAS/GRAPH Control for ActiveX.

The following example specifies a Windows path for the setup program, and assumes that all user computers are mapped to that location on a virtual U:\ drive:

ods html body='myGraph.html'
    archive="u:\controls\SASGraph.exe";
goptions device=activex;

ods html body='myGraph.html'
    attributes=("codebase"="u:\controls\SASGraph.exe");
goptions device=activex;

The following example uses the HTTP protocol to specify a URL that points to a location on a Web server:

ods html body='myGraph.html'
    archive="http://www.mysite.com/controls/SASGraph.exe";
goptions device=activex;

Installing the SAS/GRAPH Control for ActiveX

The SAS/GRAPH Control for ActiveX must be installed on each computer that needs to view it. If the control is not already installed on a computer, the browser automatically attempts to install it for you, if the <OBJECT> tag that references the control has the optional CODEBASE attribute defined. CODEBASE identifies the location of the control's setup program, SASGraph.exe. During the setup process, you are given the opportunity to review the licensing requirements, so no files are installed on the computer without your permission.

If the CODEBASE attribute is not present on the <OBJECT> tag, or if a browser cannot find the setup program, you must find out where your site stores the control's setup program, SASGraph.exe. If you cannot locate SASGraph.exe at your site, SAS Institute provides two locations where you can get a copy of it. The file is on the Client Side Components CD-ROM that ships with The SAS System when you license SAS/GRAPH. If that CD-ROM is not available, you can download the file from the SAS Web site.

After locating the file SASGraph.exe, you can install the control in one of the following ways:

• Edit the HTML file to point the CODEBASE attribute to the setup program. In this case, the browser runs the setup program the next time the HTML file is opened or refreshed in the browser. This might be the best option for installing the control in the default location, which is C:\Program Files\SAS Institute\Shared Files\Graph.
• Run the setup program from a command line. This is the only way to install the control in a non-default location.

Editing an HTML File to Install the SAS/GRAPH Conrtol for ActiveX

If the <OBJECT> tag that references the SAS/GRAPH Conrtol for ActiveX does not have a CODEBASE attribute, or if the attribute points to a location that your computer cannot access, then you can edit the HTML file to add or modify the CODEBASE value so that it points to the control's setup program, SASGraph.exe. When you open or refresh the HTML file in your browser, it will run the setup program. If setup runs successfully, it installs the control in the default location, C:\Program Files\SAS Institute\Shared Files\Graph. To install the control in any other location, you cannot let the browser install it for you. Rather, you must run the setup program from the command line, using command-line parameters.

By default, SAS/GRAPH omits the CODEBASE attribute from the <OBJECT> tag. Here is an example:

<OBJECT ID="GIDX"
CLASSID="CLSID:1B5127F3-66C3-11d3-8788-00C04F387B43"
Width=750
Height=400
Align=TOP
>
<PARAM NAME="HoldDisplay" VALUE="1">
<PARAM NAME="BackColor" VALUE="#E0E0E0">
</OBJECT>

You can add the CODEBASE attribute anywhere among the <OBJECT> tag's other attributes. A logical place to add the attribute is below the CLASSID attribute. The following example points to a setup-program location on the local C:\ drive:

<OBJECT ID="GIDX"
CLASSID="CLSID:1B5127F3-66C3-11d3-8788-00C04F387B43"
CODEBASE="c:\SASGraph.exe"
Width=750
Height=400
Align=TOP
>
<PARAM NAME="HoldDisplay" VALUE="1">
<PARAM
NAME="BackColor" VALUE="#E0E0E0">
</OBJECT>

To point to a location on an Internet server, specify a valid URL:

CODEBASE="http://www.myCompany.com/controls/SASGraph.exe"

On the CODEBASE attribute, be sure to enclose the location within double quotation marks.

After you edit the HTML file and open it again in your Web browser, the browser should be able to find the setup program. When the setup program runs, it installs the SAS/GRAPH Control for ActiveX in the default location.

Running SASGraph.exe to Install the SAS/GRAPH Control for ActiveX

The setup program SASGraph.exe installs the SAS/GRAPH Control for ActiveX. If you run the program without command-line parameters, it installs the control in the default location, C:\Program Files\SAS Institute\Shared Files\Graph. To run the setup program, you can double-click on it in the Windows Explorer, or execute the program from a command line.

To install the control in any location other than the default, you must run a local copy of SAS/Graph.exe from the command line, using the appropriate command-line parameters. Here are the steps:

1. Copy the control's setup program SASGraph.exe to a local directory on your computer. The person who created the control should be able to tell you where that file is located for copying.
2. Open a command window, and run your local copy of SASGraph.exe with the following syntax:

   SASGraph.exe -a -p
   

   The setup program will allow you to browse for an installation location.

Archive Locations: SAS/GRAPH Applets for Java

Java applets are designed as network utilities that a browser downloads as needed. The executable code for them does not have to be installed on the local computer. Rather, the computer just needs access the code wherever it resides, whether on the local computer, on a local network server, or on a Web server.

A Java applet is embedded in an HTML file by an <APPLET> tag. When the browser sees the <APPLET> tag, it attempts to load the class files that implement the applet in the browser. Those classes are contained in a Java Archive (JAR) file, which is a file that combines multiple Java class files into a single file. The purpose of a JAR file is to reduce the overhead of transferring the class definitions over a network. The SAS/GRAPH Applets for Java take advantage of this utility so that you can deliver your client graphs for Java across a network or over the Internet.

Note. The SAS/GRAPH MetaViewApplet uses a ZIP file rather than a TAR file to compress its class file. That is because it supports a version of Java that precedes the use of JAR files.

Beginning with Version 8 of The SAS System, there are three separate applets for the client graphs for Java: the ContourApplet, the GraphApplet, and the MapApplet, each of which is delivered in a separate JAR file. Depending on the procedure that you run, SAS/GRAPH automatically references the appropriate JAR file in the output HTML file.

For each of the SAS/GRAPH procedures that support the JAVA device driver, the following table shows the corresponding applet and associated JAR-file name:

The <APPLET> Tag

In an HTML file, each Java applet is referenced in a separate <APPLET> tag. Inside the <APPLET> tag is a required CODE attribute and optional CODEBASE and ARCHIVE attributes that tell the browser where to locate the applet's executable code. CODE identifies the initial class file to open. CODEBASE points to the directory that stores the JAR file, and ARCHIVE points to the specific JAR file that is being used by the applet.

Although the CODEBASE and ARCHIVE attributes are optional, SAS in most operating environments includes them in the output HTML file for the client graphs. In those cases, SAS points the attributes to the location where the SAS install process placed the supplied JAR files on the computer that generated the graph.

Here is an example <APPLET> tag that is generated by a SAS/GRAPH program that is run in the MS Windows operating environment. The CODEBASE and ARCHIVE attributes point to the default installation location in a Windows operating environment (the ellipses (...) represent additional attributes and parameters that will be present, depending on the settings that were in effect when the graph was created):

<APPLET NAME="GIDX"
 CODE="GraphApplet.class"
 CODEBASE="file:///C:\Program Files\SAS Institute\SAS\V8\common\applets"
 ARCHIVE="file:///C:\Program Files\SAS Institute\SAS\V8\common\applets/graphapp.jar"
...
>
...
</APPLET>

Note. It seems redundant to specify a path on both attributes, but our testing at SAS Institute has revealed that the path on both attributes seems necessary for the applets to run consistently well across browsers and operating environments. You can write SAS code that generates the path on both attribute values, or that omits the path from the ARCHIVE attribute. For details, see Specifying a Java Archive Location in a SAS/GRAPH Program.

Because the attributes are pointing to a local directory in the Windows operating environment, the location specification combines the Windows convention of separating directory levels with a backslash (\), and the URL convention of delimiting the other components of the path with a forward slash (/). Here is what each part represents:

When a browser sees the <APPLET> tag, it reads the values that are assigned to the the CODEBASE and ARCHIVE attributes, and looks for the JAR file(s) in the specified location. If it does not find all the JAR files, then it cannot display the graph. In that case, you can specify the archive location in the SAS/GRAPH program and re-run the program, or edit the HTML file to specify the archive location.

Specifying a Java Archive Location in a SAS/GRAPH Program

By default in some operating environments, SAS/GRAPH points the CODEBASE and ARCHIVE attributes to the location where the SAS install process places JAR files. If you view the applets on the same computer that generated the HTML file, then the browser should have no trouble finding the applet's JAR file. However, if you wish to publish your output on the Web or to mail the results to someone else, it is wise to provide the path to the JAR file(s) so that they can be located by any machine that is reading the results. If you generate the HTML files in a mainframe operating environment, you should always specify a path to your JAR file(s) in your SAS/GRAPH programs.

To point the CODEBASE and ARCHIVE attributes to a location other than the default location, use the ODS HTML statement. Your specification must provide both the location and name(s) of the appropriate JAR file(s). Before making the specification, consider the following:

• The location can be on a local or networked computer, or it can be on a Web server. The default location is identified on the SAS System option APPLETLOC. (Run PROC OPTIONS or view the SAS configuration file to find the value of APPLETLOC.)
• You must specify a location that the browser can interpret. If the JAR file is on a local or networked computer, use the FILE protocol to specify the location. If it is on a Web server, use the HTTP protocol.
• You must be certain to point to a location that all your users can access. If all required JAR files do not already reside in such a location, consult your SAS Representative to find out where the JAR files are stored at your site.
• If you have already generated an HTML page without the desired location, you or your users can edit the HTML file directly to specify an archive location.

As noted in the previous section, our testing at SAS Institute has revealed that some browser/operating-environment combinations seems to require the path on both the ARCHIVE and CODEBASE attributes in order for the applets to run. Therefore, SAS/GRAPH generates the path on both attributes. However, some books on JavaScript recommend that you specify a path on CODEBASE, but omit the path on ARCHIVE. The ODS HTML statement provides syntax to support that convention.

Syntax on the ODS HTML statement depends on whether you want to generate the path on both the ARCHIVE and CODEBASE attributes, or whether you want to generate the path only on the CODEBASE attribute, and have ARCHIVE reference only the JAR-file name:

• To generate the path on both attributes, use the ODS HTML statement's ARCHIVE= option. On ARCHIVE=, specify a single string that represents the location and name(s) of the appropriate JAR file(s). The string that you specify will be used to generate the appropriate settings on the CODEBASE and ARCHIVE attributes in the output HTML file.
• To generate the path on CODEBASE but omit the path on ARCHIVE, use the ODS HTML statement's ARCHIVE= and ATTRIBUTES= options. On ARCHIVE=, specify a string that represents only the JAR-file name(s). On ATTRIBUTES=, specify the complete CODEBASE specification. With this syntax, you must be certain to use both options ARCHIVE= and ATTRIBUTES= on the ODS HTML statement.

Example: Generate the path on both attributes. The following example uses the HTTP protocol to specify a URL that points to a JAR file that is located on a Web server:

ods html body='myGraph.html'
    archive="http://www.mysite.com/applets/graphapp.jar";
goptions device=java;

This example generates the following values for the <APPLET> tag's CODEBASE and ARCHIVE attributes in the output HTML file:

<APPLET NAME="GIDX"
 CODE="GraphApplet.class"
 CODEBASE="http://www.mysite.com/applets"
 ARCHIVE="http://www.mysite.com/applets/graphapp.jar"
...

In Release 8.1, information for rendering maps is written to the HTML file in well-known binary form, so the map information is embedded in the HTML file and you only have to indicate the location of the mapapp.jar file to render maps. However, in Version 8, map information is downloaded to the HTML file in JAR files. Thus, if your program generates a map, you must specify the JAR file for the MapApplet and the JAR file for the underlying map. Separate the JAR-file names with a comma:

ods html body='myMap.html'
    archive="http://www.mysite.com/applets/mapapp.jar,us.jar";
goptions device=java;

Example: Generate the path on one attribute. The following example uses the HTTP protocol to specify a URL that points to a JAR file that is located on a Web server:

ods html body='myGraph.html'
    archive="graphapp.jar"
    attributes=("codebase"="http://www.mysite.com/applets");
goptions device=java;

ods html body='myGraph.html'
    attributes=("archive"="graphapp.jar"
                "codebase"="http://www.mysite.com/applets");
goptions device=java;

Either convention generates the following values for the <APPLET> tag's CODEBASE and ARCHIVE attributes in the output HTML file:

<APPLET NAME="GIDX"
 CODEBASE="http://www.mysite.com/applets"
 CODE="GraphApplet.class"
 ARCHIVE="graphapp.jar"
...

In Version 8, if your program generates a map, be sure to specify the JAR file for the MapApplet and the JAR file for the underlying map. Separate the JAR-file names with a comma:

/* Version 8 needs a JAR file for the underlying map. The */
/* JAR file us.jar is not needed in Release 8.1, which    */
/* embeds map information in the HTML file.               */
ods html body='myMap.html'
    archive="mapapp.jar,us.jar"
    attributes=("codebase"="http://www.mysite.com/applets");
goptions device=java;

Can't View the Applet? Edit the Java Archive Location in the HTML File

If someone sends you a Web page but you cannot view the SAS/GRAPH Applet for Java in that page, chances are that the browser cannot find the class files that implement the applet. Those files are contained in a Java Archive (JAR) file.

In the HTML file, the applet is identified on an <APPLET> tag, and the location of the required JAR file(s) is identified on that tag's CODEBASE and ARCHIVE attributes. To view the applet, you must find out where the appropriate JAR file is located at your site, and then edit the HTML file to point the CODEBASE and ARCHIVE attributes to that location. If you cannot access the JAR file in that location, you can copy it to your local or a network computer and use the FILE protocol to point the CODEBASE and ARCHIVE attributes there. Or, you can use HTTP protocol to point the attributes to an Internet server that has the JAR file. Wherever the file is located, you must use either the FILE or the HTTP protocol to specify the location.

The following HTML fragment shows an example <APPLET> tag with the CODEBASE and ARCHIVE attributes pointing to the default location where the SAS install process placed the JAR file in a Windows operating environment. The file name at the end of the ARCHIVE value identifies the JAR file, in this case, graphapp.jar. (For a description of the CODEBASE and ARCHIVE values, see The <APPLET> Tag.) In this example, the ellipses (...) represent additional attributes and parameters that are present in the <APPLET> tag, depending on the settings that were in effect when the graph was created:

<APPLET NAME="GIDX"
CODE="GraphApplet.class"
CODEBASE="file:///C:\Program Files\SAS Institute\SAS\V8\common\applets"
ARCHIVE="file:///C:\Program Files\SAS Institute\SAS\V8\common\applets/graphapp.jar"
...
>
...
</APPLET>

To point the CODEBASE and ARCHIVE attributes to a JAR file that is located on an Internet server, use the HTTP protocol for specifying a valid URL:

<APPLET
CODE="GraphApplet.class"
CODEBASE="http://www.myCompany.com/applets"
ARCHIVE="http://www.myCompany.com/applets/graphapp.jar"
...
>
...
</APPLET>

On both the CODEBASE and ARCHIVE parameters, be sure to enclose the location within double quotation marks.

In Version 8 of the SAS/GRAPH MapApplet, the ARCHIVE attribute references two JAR files, one for the applet itself, and one for the underlying map. For example, the ARCHIVE attribute for a Version 8 applet that uses a map of the United States might look as follows for JAR files that are located in a Windows environment:

<APPLET
CODE="MapApp.class"
CODEBASE="file:///C:\applets"
ARCHIVE="file:///C:\applets\mapapp.jar,us.jar"
...
>
...
</APPLET>

Beginning in Release 8.1, map information is embedded in the HTML file, and the JAR file for the underlying map is not used. In that case, only the location for mapapp.jar is required.

As noted in the previous section, our testing at SAS Institute has revealed that some browser/operating-environment combinations seems to require the path on both the ARCHIVE and CODEBASE attributes in order for the applets to run. Therefore, SAS/GRAPH generates the path on both attributes. However, some books on JavaScript recommend that you specify a path on CODEBASE, but omit the path on ARCHIVE. If you prefer to follow that convention, you can omit the path from the ARCHIVE value:

<APPLET
CODE="MapApp.class"
CODEBASE="file:///C:\applets"
ARCHIVE="mapapp.jar,us.jar"
...
>
...
</APPLET>

Regardless of which convention you observe, after you edit the HTML file and open it again in your browser, the browser should be able to run the applet.

Troubleshooting Viewing Problems for the SAS/GRAPH Applets for Java

If you have problems viewing a SAS/GRAPH Applet for Java, often the problem is caused by the browser's inability to locate and/or load the required JAR file. Such problems often surface as a script error when viewing the HTML file. Most commonly a message like the following is displayed:

Error: Object doesn't support this property or method

Here are some simple things that you can try to correct the problem. You might try them in the order that they are presented here.

1. Verify that the browser supports the appropriate level of Java. You can do this by opening the Java Console window. At least Java 1.1.4 is required.
2. Verify that the CODEBASE and ARCHIVE paths in the <APPLET> tag are correct and point to a copy of the appropriate JAR file. For details, see Archive Locations: SAS/GRAPH Applets for Java.
3. Verify that you have appropriate permissions to load the JAR file. This can particularly be a problem when the HTML file is local and the CODEBASE and ARCHIVE attributes point to an HTTP link requiring user authentication. For example, if the ARCHIVE is http://www.myCompany.com/applets/graphapp.jar and you normally have to log in to view pages on this server, yet your HTML file is local to your computer, then the JAR will not load. The reason is that you have not been authenticated on the HTTP server, so your CODEBASE and ARCHIVE attributes fail. To fix this, first load a page on your HTTP server, then load the local HTML file that references your graph. Because you have now been authenticated for the server, the load should succeed.
4. Remove any classpath environment variables that have been set. The archives in which the applets are distributed contain all the required classes to run the applets. Your classpath may point to old versions of the required classes (for example, for use with webAF). This can cause the applets to fail to load. Most applications allow you to specify a classpath at startup using a startup option. This is often safer for running multiple clients than using the environment variables.
5. Some browsers have a Java Console window, which is a log that lists problems that are encountered when running Java applets in the browser. If your browser supports the Java Console, open the Console window and read the log information to see whether it identifies the problem.

Drill-down Capabilities in the Client Graphs

Beginning in Version 7.01 of The SAS System, SAS/GRAPH can be used with the Output Delivery System (ODS) to generate drill-down graphs. In Version 7.01, only the GIF driver can be used with ODS, and the drill-down mechanism is pixel-driven so that it will work with GIF images. It links designated areas or hot zones of a graph to target output, such as other graphs or reports. This pixel-driven mechanism is fully documented in SAS/GRAPH Software: Reference.

Beginning in Version 8 of SAS/GRAPH, the ACTIVEX and JAVA drivers can also be used with ODS. If your SAS/GRAPH program implements the pixel-driven drill-down mechanism, the client graphs for ActiveX and Java support it, although they do not support the mechanism's ability to implement the drill-down capability in the graph legend.

For the ACTIVEX and JAVA device drivers, there are no special requirements for implementing the pixel-driven, drill-down capabilities as documented for the GIF driver in SAS/GRAPH Software: Reference. Generally, to implement this mechanism in a SAS/GRAPH program, you provide the URL needed to connect the graph to its related output. Your SAS/GRAPH program must do all of the following:

• Use the DEVICE= option on a GOPTIONS statement to specify the device driver you want to use to generate the output. You can use the ACTIVEX, GIF, or JAVA driver.
• Use ODS to specify HTML output and name the output HTML file(s).
• Create at least one HTML variable in the data. The variable must be a character variable, and you must assign to it string values that represent the URL addresses of any target output that you want to associate with the graph.
• Run a SAS/GRAPH procedure to create the drill-down graph(s). This procedure must use an HTML= option to associate the HTML variable(s) with the graph. The ACTIVEX and JAVA drivers do not support the HTML_LEGEND= option, which is ignored if it is used with them.
• If necessary, run the procedures that generate the target output. The target output must be directed to the locations identified by the HTML variable.

For more information on pixel-driven drill-down graphs, see SAS/GRAPH Software: Reference.

The SAS/GRAPH Applets for Java support several drill-down mechanisms or modes. The pixel-driven mechanism is called the URL mode because you have to supply a URL for all the target output. In addition to the URL mode, the applets support several data-driven drill-down modes. The GraphApplet for Java supports three data-driven modes: Local, Script, and HTML. The MapApplet for Java supports two of the modes: Script and HTML. For information on these modes, see Drill-down Modes in the SAS/GRAPH Applets for Java.

Note. SAS/GRAPH Contour Plots do not support any drill-down capabilities, whether the plots are generated with the GIF, ACTIVEX, or JAVA drivers. The ACTIVEX driver only supports the URL drill-down mode, but will support the data-driven modes in a future release of SAS/GRAPH software. The SAS/GRAPH Control for ActiveX can support the Script and HTML drill-down modes, but only when the control is generated with the SAS/IntrNet DS2GRAF macro. For information on using SAS/IntrNet to generate the SAS/GRAPH Control for ActiveX, see The GraphApplet HTML Generator.