SAS, Version 8: 508 Graphs

The GACCESSIBLE Macro: Usage Documentation

The GACCESSIBLE macro makes it easy for you to associate usability information with graphs that you produce for Web display using ODS with the GIF, Java-based, or ActiveX-based device drivers. The accessibility information can include descriptive text and/or data that is relevant to the graph, such as the summary statistics that are represented by a bar chart.

As with any macro in SAS, to use the GACCESSIBLE macro you must create the macro in the SAS environment before you can invoke it in your SAS session. The process is discussed later on this page.

Note. For detailed information on using macros, see the %MACRO Statement in the SAS Help facility.

The GACCESSIBLE macro provides several parameters. Based on your parameter specifications, the macro

Writes descriptive text and/or relevant data to a corresponding graph's output HTML file.
Automatically creates a link that can access the accessibility information.

The accessibility link is visible by default in the graph's output HTML file so that you can test and verify that information during graph development. You can hide the link text for production graphs so that the link does not distract from the graph presentation but can nevertheless be detected by an accessibility aid, such as a screen reader.

The accessibility information that is written to the graph's output HTML file is written within a JavaScript function that is called when the accessibility link is selected from the HTML page. The JavaScript function regenerates the output page's HTML so that the page displays the accessibility information rather than the graph.

Generally when using the GACCESSIBLE macro, you use ODS to generate the graph, and then invoke the macro to write the accessibility information to the graph's output HTML file. To generate multiple graphs in the same output file, you repeat the same sequence for each graph: 1) generate the graph using ODS, and then 2) invoke the macro to write that graph's accessibility information to the output file.

In order for both ODS and the GACCESSIBLE macro to write to the same output file, you must define the output file on a FILENAME statement, and then use the defined fileref on both the ODS HTML statement and on the GACCESSIBLE macro. You must also use appropriate options on the ODS HTML statement to control the HTML tags that are written to the output file. The specific requirements are discussed in detail in Controlling the Output that is Written to the Output File.

Creating the GACCESSIBLE Macro in the SAS Environment
Invoking the GACCESSIBLE Macro in a SAS Session
Controlling the Output that is Written to the Output File

Creating the GACCESSIBLE Macro in the SAS Environment

The code for the GACCESSIBLE macro has been written for you, but you have to introduce that code into the SAS environment. There are numerous ways to do that. For example, you can submit the macro source code in the current SAS session so that the macro is available during the session, or you can store the code in a way that makes it available to any SAS session.

Compiling the Macro Code for Use in a Single SAS Session

If you just want to see how the GACCESSIBLE macro works -- or if you seldom expect to use it -- you can copy the macro source code and paste it into your SAS session. When you submit the code, the macro is complied and becomes available to your session.

Using this technique, the macro is available to the current SAS session, but it would not be available to a subsequent SAS session unless you submit the macro code in that session also.

Storing the Macro Code for Use in Any SAS Session

If you frequently need to generate accessibility information for your graphs, you may want to copy the GACCESSIBLE macro's source code into a file and store the file in a location where the SAS macro processor can find it. That way the code will always be readily available.

One way to store macro code so that it is available to any SAS session is to use the SASAUTOS= system option. SASAUTOS= declares a storage location as an autocall library, which is a SAS library containing files that define SAS macros.

Note. In order to use the autocall facility, the SAS option MAUTOSOURCE must be in effect.

Here are general steps for setting up an autocall library for the GACCESSIBLE macro. The specific steps you need to follow will vary, depending on your operating environment and SAS configuration.

Copy the GACCESSIBLE macro's source code to a text file and save the file so that it is available in your operating environment. For example, in a Windows or UNIX environment, you might name the file gaccessible.sas and store it in a directory that can be accessed from your SAS session.
Use the SASAUTOS= system option to add the macro file's storage location to the autocall library. The general syntax for SASAUTOS= is
```
   SASAUTOS= library-specification |
      (library-specification-1 . . . , library-specification-n)
```
The libray-specification identifies a location that contains library members that contain a SAS macro definition. A location can be a SAS fileref or a host-specific location name enclosed in quotation marks.
Specify the SASAUTOS= option in a configuration file or on an OPTIONS statement in your SAS session. For example, in a Windows operating environment, you could submit the following OPTIONS statement in your SAS session:
```
   options sasautos=(sasautos,'macro-dir');
```
In this OPTIONS statement, macro-dir is the path to the directory where you stored the file gaccessible.sas.

Note. If you put the SASAUTOS= option in a configuration file, or if you specify it on an OPTIONS statement in an autoexec file, the storage location will be defined as an autocall library each time you start a SAS session. That way the macro will be available any time you need it, but it will not be compiled unless you use it.

Consult the SAS Help facility for more information on the SASAUTOS= system option, on autocall libraries, and on configuration and autoexec files.

Invoking the GACCESSIBLE Macro in a SAS Session

The general syntax for the GACCESSIBLE macro is

   %GACCESSIBLE( FILEREF=fileref
                 <,DESC=text>
                 <,DSN=SAS-data-set, VARS=variable(s)>
                 <,HIDDEN=TRUE|FALSE>
                );

The FILEREF= parameter is always required to specify the corresponding graph's output HTML file. The file specification must be an existing SAS fileref.
To include a description with the accessibility information, use the DESC= parameter to specify the text. If the text contains special characters -- such as a single or double quote, a left or right parenthesis, or a comma -- you must use a macro quoting function such as %STR to quote these characters. See the reference documentation for more details.
To include relevant data with the accessibility information, use the DSN= parameter to the specify the SAS data set that contains the data, and also the VARS= parameter to indicate which variables to use from that data. Typically the data that you point to with these parameters is data that you generate in your SAS program, using a procedure like PROC SUMMARY or PROC MEANS.
To hide the footnote link that points to the accessibility information, set the HIDDEN= parameter to TRUE. The default is FALSE.

A typical macro call might resemble the following:


%gaccessible(fileref=out,
             desc=This is a bar chart of age summarized by height,
             dsn=work.sumclass, vars=age height,
             hidden=true);

Use the Examples links in the left column of this page to see some SAS programs that use the GACCESSIBLE macro.

Although the FILEREF= parameter is the only parameter that is always required, you must also use either DESC= to provide a description, or DSN= and VARS= to provide data; otherwise, the macro has no information to write to the output file. Typically, you will probably want to provide both descriptive text and related data.

If you use the DESC= parameter, the descriptive text is written to an HTML paragraph that serves as the first paragraph for the accessibility information.

If you use the DSN= and VARS= parameters, the requested data is written to an HTML table below the descriptive text (if any). Column headings in the table are written within <TH> elements that have their SCOPE= attributes set to the value COL, as in

<TH SCOPE='COL'>Age</TH>

The value COL for the SCOPE attribute indicates that each header cell provides header information for the data within its column. The setting ensures that a screen reader has maximum flexibility for navigating the table data. For example, a user could toggle the reader so that it reads all the values in a single column. Or a user could toggle the reader so that it skips to a particular value within the table.

Controlling the Output that is Written to the Output File

In order for both ODS and the GACCESSIBLE macro to be able to write to the same output HTML file, you must use a FILENAME statement to define a fileref for the output file. In addition, you must use appropriate options on the ODS HTML statement to control the opening and closing HTML tags that ODS writes to the output file.

Here is the general form required for your SAS program. The statements assume that the GACCESSIBLE macro has been defined in an autocall library and so will be recognized when invoked. This general form does not include procedures like PROC MEANS or PROC SUMMARY that might be used to generate summary statistics that can be shown with the accessibility information. The form simply focuses on the statements that are required for writing the graphics and usability information to the output HTML file.


/* Define a fileref for the HTML output.
 *------------------------------------------------------------*/
filename out 'output-file-specification';

/* Generate graphics output and usability information for the
 * first graph.
 *------------------------------------------------------------*/
ods html gpath=graphics-location
   file=out (no_bottom_matter);
   one-or-more-proc-statements for graph output
   ods html close;
   %gaccessible(fileref=out, desc=Text for first graph);

/* Redefine the fileref so new ODS content is appended to the
 * file and does not replace existing content. Do this by
 * using the MOD option on the FILENAME statement.
 *------------------------------------------------------------*/
filename out 'output-file-specification' mod;

/* Optionally generate additional graphics and accessibility output.
 * Repeat this block for each set of output.
 *------------------------------------------------------------*/
ods html gpath=graphics-location
  file=out (no_top_matter no_bottom_matter);
  one-or-more-proc-statements for additional graph output
  ods html close;
  %gaccessible(fileref=out, desc=Text for graph);

/* Write the closing HTML tags to output file and close file.
 *------------------------------------------------------------*/
ods html file=out (no_top_matter);
ods html close;

Here is the general form described in more detail:

Use a FILENAME statement to specify a fileref for the output HTML file. This will enable both ODS and the GACCESSIBLE macro to open and append to the same file.
Use an ODS HTML statement to open the HTML destination for output. For device drivers that generate images (GIF, JAVAIMG, ACTXIMG), use the GPATH= option to specify a location for the images. On the FILE= (alias BODY=) option, you must specify the defined fileref. You must also use the NO_BOTTOM_MATTER suboption to prevent ODS from writing HTML closing tags to the output file. This ensures that the GACCESSIBLE macro can append the accessibility information to the file later in the program.
Use one or more graph procedures to generate the graphics output.
Use an ODS HTML CLOSE statement to close the output file. This will allow the GACCESSIBLE macro to get write access to the file.
Invoke the GACCESSIBLE macro. On the FILEREF= parameter, specify the same fileref that was used for the corresponding graph output. Use other parameters as desired. The macro will automatically close the output file when it is done appending the accessibility information to the file. It does not, however, write HTML closing tags to the file. You must use ODS to do that.
Redefine the fileref, this time using MOD on the FILENAME statement. This ensures that additional ODS output is appended to the file and does not replace existing content.
Optionally, generate additional graphics and accessibility output in the file. The ODS HTML statement for each set of graphics output must suppress both top and bottom matter (opening and closing HTML tags) in the output file.
When you are done generating output, generate closing HTML tags by submitting one last ODS HTML statement with the NO_TOP_MATTER suboption (do not use the NO_BOTTOM_MATTER suboption). Then submit the ODS HTML CLOSE statement. ODS writes the HTML closing tags to the output file, and then closes the file for the final time.

To see some SAS programs that use the GACCESSIBLE macro, use the Examples links in the right column of this page.

E-mail This Page

FOCUS AREAS

508 GRAPHS in SAS, Version 8

EXAMPLES

508 INFO

SAS, Version 8: 508 Graphs

The GACCESSIBLE Macro: Usage Documentation

Creating the GACCESSIBLE Macro in the SAS Environment

Invoking the GACCESSIBLE Macro in a SAS Session

Controlling the Output that is Written to the Output File

E-mail:
Password