SAS/GRAPH Software: Reference

ODS HTML Statement

The ODS HTML statement opens, manages, or closes the HTML destination. If the destination is open, it produces output that is written in Hyper Text Markup Language (HTML). When used with the GIF device driver and SAS/GRAPH procedures, graphics output is produced as GIF files. The HTML files display the GIF files that are created by the SAS/GRAPH procedures.

Used by:

GANNO, GCHART, GCONTOUR, GFONT, GIMPORT, GMAP, GPLOT, GPRINT, GREPLAY, GTESTIT, GSLIDE, G3D, and G3GRID procedures

Requirements:

If the HTML destination is open, the BODY= argument is required.

Operating Environment Information: In the CMS operating environment, any file specification for the HTML output files must use the URL suboption in order to form valid URLs for a Web browser. [cautend]

Description

This section describes the ODS HTML statement as it relates to SAS/GRAPH procedures.

Syntax

ODS HTML HTML-file-specification(s) | action
<ANCHOR='string'>
<BASE='base-text'>
<GFOOTNOTE | NOGFOOTNOTE>
<GPATH=graphics-location <(URL='Uniform-Resource-Locator' | NONE )>>
<GTITLE | NOGTITLE>
<HEADTEXT='HTML-for-document-head'>
<METATEXT='HTML-for-document-head'>
<NEWFILE=starting-point>
<PATH=file-location <(URL='Uniform-Resource-Locator' | NONE )>>
<RECORD_SEPARATOR='string' | NONE>
<STYLE=style-definition>
<TRANTAB='translation-table'>;

action can be one of

CLOSE

EXCLUDE

SELECT

SHOW

Note: For information on EXCLUDE, SELECT, and SHOW, see The Complete Guide to the SAS Output Delivery System.
HTML-file-specification(s) can be one or more of

BODY=file-specification

CONTENTS=file-specification

FRAME=file-specification

PAGE=file-specification

Note: BODY= is required. If you use FRAME=, you must also use CONTENTS= or PAGE=.

Required Arguments

One of these arguments is required.

CLOSE

closes the HTML destination and closes any HTML files that are currently open.

Featured in:

Example 8. Creating a Simple Web Page with the ODS HTML Statement

EXCLUDE

excludes output objects from the HTML destination.

SELECT

selects output objects to send to the HTML destination.

SHOW

writes to the SAS log the current selection or exclusion list for the HTML destination.

HTML-file-specification

opens the HTML destination and specifies the HTML file or files to write to. You can open up to four HTML files; the file designated by BODY= is required. Whenever you open one of these files, it remains open until you either

close the HTML destination with ODS HTML CLOSE
open a different file for the same HTML file specification.

HTML-file-specification can be one or more of the following arguments. Values for file-specification follow the arguments.

BODY=file-specification
FILE=file-specification

identifies the file that contains the HTML version of the procedure output. With SAS/GRAPH, the body file contains references to the graphics files, which are stored in GIF files. When you view the body file on a browser, the graphs are automatically displayed.

Featured in:

Example 8. Creating a Simple Web Page with the ODS HTML Statement and Example 10. Creating a Bar Chart with Drill-down for the Web

CONTENTS=file-specification

identifies the file that contains a table of contents to the ODS output that is produced while the HTML destination is open. The contents file contains links to the body file(s).

The text of links to graphics output is taken from the description field of the GRSEG catalog entry. Use the DESCRIPTION= option in the procedure to change the link text.

You can display a contents file alone or in conjunction with a frame file. If you display a contents file directly (without using a frame file), selecting a link opens the associated body file, and the contents file is no longer displayed. If you display a contents file with a frame file, the contents file always remains available in the left frame, and selecting a link opens the associated body file in the right frame.

FRAME=file-specification

identifies a file that points to the body file and to either the table of contents file or the page file, or both. If you specify FRAME=, you must also specify either CONTENTS= or PAGE= or both.

When you open the frame file in the browser, it displays the Table of Contents or the Table of Pages or both in the left frame, and the body file in the right frame.

PAGE=file-specification

identifies the file that contains a table of pages to the ODS output that is produced while the HTML destination is open.The pages file contains links to the body file(s). ODS produces a new page of output whenever a procedure explicitly specifies for a new page. The SAS system option PAGESIZE= has no effect on pages in HTML output.

File-specification identifies the file or SAS catalog to write to and can be one of the following:

fileref (<URL='Uniform-Resource-Locator'> <NO_BOTTOM_MATTER> <NO_TOP_MATTER> <DYNAMIC>)
external-file (<URL='Uniform-Resource-Locator'> <NO_BOTTOM_MATTER> <NO_TOP_MATTER> <DYNAMIC> )
entry.HTML (<URL='Uniform-Resource-Locator'> <NO_BOTTOM_MATTER> <NO_TOP_MATTER> <DYNAMIC> )

where

external-file

is the physical name of an external file to write to. For information on specifying external files, see the SAS companion for your operating environment.

fileref

is a fileref that has been assigned to an external file. The fileref must refer to a single file; it cannot point to an aggregate file storage location. Use a FILENAME statement to assign a fileref. See also FILENAME Statement.

entry.HTML

specifies an entry in a SAS catalog to write to.You must also specify a library and catalog. See the discussion on PATH=.

URL='Uniform-Resource-Locator'

provides a URL for file-specification. ODS uses this URL instead of the file name in all the links and references that it creates that point to the file.

Operating Environment Information: In the CMS operating environment, you must use the URL= suboption in the HTML-file specifications for the body, contents, and page files because CMS file names do not form valid URLs. [cautend]

This option is useful for building HTML files that may be moved from one location to another. If the links from the contents and page files are constructed with a simple URL (one name), they work as long as the contents, page, and body files are all in the same location.

NO_BOTTOM_MATTER NOBOT

omits the bottom matter for the file. By default, when you close a file that was open for HTML output of any kind, ODS writes some HTML to the bottom of the file. This HTML ends the file so that it can be viewed cleanly in a browser.

If you wish to leave a file in a state that you can append to, use NO_BOTTOM_MATTER on the BODY= option on the ODS HTML statement that opens the file. This option, in conjunction with NO_TOP_MATTER makes it possible for you to add output to a file that already exists and to put your own HTML code in the file between pieces of output.

To use NO_BOTTOM_MATTER, you must use a fileref for file-specification. The FILENAME statement that defines the fileref must include the host-specific option that opens the file for appending.

When you are opening a file that ODS has previously written to, you must use ANCHOR= to specify a new base name for the anchors to avoid duplicating anchors that already exist in the file. (See the discussion of ANCHOR=.

NO_TOP_MATTER NOTOP

omits the opening matter for the file. By default, when you open a file for HTML output of any kind, ODS writes some HTML to the top of the file.

If you wish to append ODS output to an existing file, you must open the file with NO_TOP_MATTER on the BODY= option on the ODS HTML statement that opens the file. This option, in conjunction with NO_BOTTOM_MATTER makes it possible for you to add output to a file that already exists and to put your own HTML code in the file between pieces of output.

To use NO_TOP_MATTER, you must use a fileref for file-specification. The FILENAME statement that defines the fileref must include the host-specific option that opens the file for appending.

DYNAMIC

enables you to send HTML output directly to a web server instead of writing it to a file. This option sets the value of the HTMLContentType= attribute.

By default, if you do not specify DYNAMIC, ODS sets the value of HTMLContentType= for writing to a file.

Note: If you specify the DYNAMIC suboption with any file specification in the ODS HTML statement, you must specify it for all the file specifications in the statement. [cautend]

Note: Regardless of how you specify the file, you may need to include the extension .HTML or .HTM on the file name. Some browsers require one of these extensions in order to read the file. [cautend]

Options

ANCHOR='anchor-name'

specifies the base name of the HTML anchor that identifies each piece of output in the body files. An anchor is the name of a link target. Each output object must have an anchor tag for the contents, page, and frame files to link to or to reference. These links and references, which are automatically created by ODS, point to the name of an anchor. Therefore, each anchor name in a file must be unique.

By default, the first anchor name is IDX, and all subsequent anchors generated while the HTML destinations remain open increment that name, for example, IDX1, IDX2, and so forth. Because anchor names continue to increment while the HTML destinations remain open, it can be difficult to predict what the name of a link anchor will be. ANCHOR= enables you to control these names.

You can change anchor names as often as you like by submitting the ANCHOR= option in an ODS HTML statement anywhere in your program. Once you have specified an anchor name, it remains in effect until you specify a new one. Like the default, specified anchor values increment while the ODS HTML destination remains open or until you assign a new value. For example, if you specify ANCHOR='SALESCHART' and submit a procedure that generates three graphs, the anchor names in the body file are SALESCHART, SALESCHART1, and SALESCHART2.

If you open an HTML file to append to it, be sure to specify a new anchor so that you don't write the same anchors to the file again. ODS cannot know about anchors that are already in a file when it opens the file.

See also: the HTML= and HTML_LEGEND= options in the GCHART, GPLOT, and GMAP procedures About Anchors

BASE='Uniform-Resource-Locator'

specifies a URL to use as the first part of all links that ODS creates in the HTML files. Consider this specification:

BASE='http://www.your-company.com/local-url/'

In this case, ODS creates links that begin with the string http://www.your-company.com/local-url/. The appropriate anchor-name completes the link.

GFOOTNOTE | NOGFOOTNOTE GFOOT | NOGFOOT

controls whether the HTML file displays all the titles that are defined by TITLE statements in the SAS/GRAPH program that generates the HTML output. GTITLE is the default and displays all currently defined titles within the SAS/GRAPH output (the GIF file) that is displayed by the HTML. NOGTITLE suppresses all TITLE statements in the GIF files that are created by SAS/GRAPH but displays them as part of the HTML.

GPATH=graphics-destination <(URL='Uniform-Resource-Locator' | NONE)>

specifies the destination for all graphics output generated by the ODS HTML statement. By default, the output is stored in the location that is specified on PATH=. If you do not specify PATH=, the output is stored using the GSFNAME location. If GSFNAME is not specified, the output is stored in the current directory.

graphics-destination

must be an aggregate storage location, such as directory or PDS, as specified by one of the following:

fileref

is a fileref that has been assigned to an aggregate file storage location. Use a FILENAME statement to assign a fileref. For more information, see FILENAME Statement.

If you use a fileref in the GPATH= option, ODS does not use information from GPATH= when it constructs links. (See How ODS Constructs Links and References).

storage-location

is the physical name of an aggregate file storage location. For information on specifying a storage location, see the SAS companion for your operating environment.

libref.catalog

specifies a SAS catalog to write to.

Uniform-Resource-Locator

provides a URL for graphics-destination. ODS uses this URL instead of the file name in all the links and references that it creates to the file. If you specify the keyword NONE, no information from the GPATH= option appears in the links or references.

Operating Environment Information: In the CMS operating environment, you must use the URL= suboption in the GPATH= option because CMS file names do not form valid URLs. [cautend]

Each output GIF file is named automatically using the catalog entry name as the base name and incrementing the name as necessary. For more information on naming catalog entries and external files, see Exporting SAS/GRAPH Output with Program Statements.

Featured in: Example 10. Creating a Bar Chart with Drill-down for the Web

GTITLE | NOGTITLE

Titles that are displayed by ODS HTML support most SAS/GRAPH TITLE statement options. The font must be valid for the browser. Options that ODS cannot handle, such as height and text angle specifications, are ignored. For details, see TITLE, FOOTNOTE, and NOTE Statements.

Featured in: Example 8. Creating a Simple Web Page with the ODS HTML Statement and Example 10. Creating a Bar Chart with Drill-down for the Web

HEADTEXT='HTML-for-document-head'

specifies HTML to place between the <HEAD> and </HEAD> tags in all the HTML files that the HTML destination writes to. Use HEADTEXT= to define programs (for example, java scripts) that you can use later in the file.

Note: ODS cannot parse the HTML that you supply. It should be well-formed HTML that makes sense in the context of the <HEAD> and </HEAD> tags. For information on HTML, refer to one of the many reference books that are available on the subject. [cautend]

METATEXT='HTML-for-document-head'

specifies HTML to use as the <META> tag inside the <HEAD> and </HEAD> tags of all the HTML files that the HTML destination writes to. This HTML provides the browser with information about the document that it is loading. This information could include things like the content-type and the character set to use. For information on HTML, refer to one of the many reference books that are available on the subject.

If you do not specify METATEXT=, ODS writes a simple <META> tag, which includes the content-type of the document and the character set to use, to all the HTML files that it creates. It takes the value of the character set from the SAS registry. If the registry does not specify a character set, ODS writes the HTML only to the contents, frame, and page files.

Note: ODS cannot parse the HTML that you supply. It should be well-formed HTML that makes sense in the context of the <HEAD> and </HEAD> tags. If you are using METATEXT= as it is intended, your HTML should look like this:

<META your-metatext-which-could-be-very-long>

NEWFILE=starting-point

creates a new body file at the specified starting-point. ODS automatically names new files by incrementing the name of the file specified by BODY=. For example, if you specify BODY='REPORT.HTML', ODS names additional body files REPORT1.HTML, REPORT2.HTML, and so forth. If you end the file name with a digit, ODS begins incrementing with that number. For instance, if you specify BODY='MAY5.HTML', ODS names the first body file MAY5.HTML. Additional files are named MAY6.HTML, MAY7.HTML, and so forth. Starting-point can be

NONE	writes all output to the body file that is currently open. This is the default.
PAGE	starts a new body file for each page of output. A page break occurs when a procedure explicitly starts a new page (not because the pagesize was exceeded) or when you start a new procedure.
PROC	starts a new body file each time that you start a new procedure.
OUTPUT	starts a new body file for each piece of output. For SAS/GRAPH this means a new file for each GRSEG or GIF file that the program generates. Alias: TABLE.

PATH=file-location<(URL='Uniform-Resource-Locator' | NONE)>

specifies the location (external storage location or a SAS catalog) for all HTML files. If GPATH= is not specified, also specifies the location for all GIF files.

file-location

identifies the storage location (for example, directory or PDS) or SAS catalog to write to.

file-location can be one of the following:

fileref: is a fileref that has been assigned to an external storage location. Use the FILENAME statement to assign a fileref. If you use a fileref in the PATH= option, ODS does not use information from PATH= when it constructs links. (See How ODS Constructs Links and References).
libname.catalog: specifies a SAS catalog to write to.

URL='Uniform-Resource-Locator' | NONE

provides a URL for file-location. ODS uses this URL instead of the file name in all the links and references that it creates to the file. If you specify the keyword NONE, no information from the PATH= option appears in the links or references.

Operating Environment Information: In the CMS operating environment, you must use the URL= suboption in the PATH= option because CMS file names do not form valid URLs. [cautend]

RECORD_SEPARATOR='string' | NONE
RECSEP='string' | NONE
RS='string' | NONE

specifies an alternate record separator for the HTML files. A record separator is the character or string that separates lines in the HTML files.

Different operating environments use different separator characters. If you don't specify a record separator, the HTML files are formatted for the environment that you run the SAS job in. However, if you are generating files in one operating environment for viewing in another operating environment that uses a different separator character, you can specify a record separator that is appropriate for the target environment.

'string'

is the hexadecimal representation of one or more characters. For example, the following option specifies a record-separator of a carriage-return character and a linefeed character (on an ASCII file system):

RECORD_SEPARATOR='0D0A'x

NONE

produces HTML that is appropriate for the environment that you run the SAS job in. In many operating environments, using a value of NONE is the same as omitting the RECORD_SEPARATOR option. However, in mainframe operating environments, it is not.

Operating Environment Information: In a mainframe environment, by default, ODS produces a binary file that contains embedded record-separator characters. While this approach means that the file is not restricted by the line-length restrictions on ASCII files, it also means that if you view the file in an editor, the lines all run together.

If you want to format the HTML files so that you can read them with an editor, use RECORD_SEPARATOR=NONE. In this case, ODS writes one line of HTML at a time to the file. When you use a value of NONE, the logical record length of the file that you are writing to must be at least as long as the longest line that ODS produces. If it isn't, the HTML may wrap to another line at an inappropriate place. [cautend]

STYLE=style-definition

specifies a style for the HTML output. Styles are created with the Template procedure and contain color, font, and stylistic attributes for the ODS HTML output. For more information on style definitions, see The Complete Guide to the SAS Output Delivery System.

TRANTAB='translation-table'

translate the HTML files to the requested representation. This option is particularly useful if you are creating files -- for example, in an EBCDIC-based operating environment and if the files are destined for an ASCII-based web server. If you use TRANTAB=, you can transfer the files in binary mode as they are already in the appropriate representation. (SAS facilities for changing translation tables are much more flexible than those of FTP, for example).

translation-table can be any translation table that SAS provides or any user-defined translation table.

See also: For information on translation tables, see the documentation of the TRANTAB= system option in the chapter on system options in SAS Language Reference: Dictionary.
For information on creating, editing, and displaying customized translation tables, see "The TRANTAB Procedure" in SAS Procedures Guide. You can also use PROC TRANTAB to view and modify translation tables that are supplied by SAS Institute.

Using the ODS HTML Statement

While the ODS HTML destination is open, you can submit as many ODS HTML statements as you like, and you can place them anywhere in your SAS/GRAPH program. This enables you to open new files, change anchor names, or specify a new location for graphics output whenever you like. At the end of your ODS HTML processing step, submit ODS HTML CLOSE to close the destination and all open files.

<A NAME="IDX"></A>
<HR size=3><P>
<CENTER>
<IMG SRC="totals.gif">

In order for the links from the contents, page, or frame file to work, each piece of output in the body files must have a unique anchor to link to. The anchor for the first piece of output in a body file acts as the anchor for that file. These anchors are used by the frame and contents files, if they are created, to identify the targets for the links that ODS HTML automatically generates.

By default, the first anchor is named IDX and all subsequent anchors generated while the HTML destinations remain open increment that name. Anchor values increment while the ODS HTML destinations remain open unless you use ANCHOR= to assign a new value. Anchor values continue to increment when you open new body files, start new procedures, or produce different types of output.

Controlling the anchor name is useful when you create a graph with drill-down capability. In this case, you must create a variable that contains the names of the anchors that are the targets for the different areas of the graph that the user may click on.

For a complete description, see the ANCHOR= option.

How ODS Constructs Links and References

Several options in the ODS HTML statement affect how ODS constructs the links and references that point from the frame to the table of contents, table of pages, and body file and from the table of contents or table of pages to the body file. Links are made as HREF= attributes on A (anchor) tags inside the HTML files. Each HREF= attribute points to the NAME= attribute on another A (anchor) tag. HREF= must identify both the file that contains the target and the name of the anchor within that file. The value of HREF= must be a valid target in a valid URL. It uses the following form:

<A HREF="URL#anchor-name">
ODS constructs the value of an HREF= attribute based on information that you provide in the ODS HTML statement.

Note: HTML references to files use other tags, but the logic for creating the string that identifies the file is the same as the logic for creating an HREF= attribute. [cautend]

The URL in an HREF= attribute is composed of information from three options in the ODS HTML statement: the BASE= option, the GPATH= or the PATH= option, and the BODY=, the CONTENTS=, or the PAGE= option.

If you specify BASE=, the value of that option is the first part of the URL for every HREF= attribute that ODS writes.

If you specify GPATH= or PATH=, the next part of the URL in an HREF= attribute comes from that option.

If the file that you are linking to is a graphic, ODS uses information from the GPATH= option as the next part of HREF=. If the file that you are linking to is not a graphic, or if GPATH= is not specified, ODS uses information from the PATH= option as the next part of HREF=. (For information on these options, see the discussion of GPATH= and the discussion of PATH=.)

Building an HREF= Attribute from the GPATH= or PATH= Option shows how ODS uses information from a GPATH= or PATH= option in the URL in HREF= attributes.

Building an HREF= Attribute from the GPATH= or PATH= Option

If the file-location in GPATH= or PATH= is a

And the URL= suboption is^* ODS uses this information in the second part of the URL in the HREF= attribute^#

external-location or libref.catalog not specified the specified path

external-location or libref.catalog
specified, but not NONE the value of the URL= suboption

external-location or libref.catalog NONE No information from GPATH= or PATH=

fileref
specified or not specified No information from GPATH= or PATH=

*In the CMS operating environment, you must use the URL= suboption in the GPATH= or PATH= option because CMS file names do not form valid URLs.
#For both GPATH= and PATH=, if you do not specify the option, ODS does not use a default or substitute value for that option in creating the HREF= attribute.

***Building an HREF= Attribute from the GPATH= or PATH= Option***
*If the file-location* in GPATH= or PATH= is a**	And the URL= suboption is^*	ODS uses this information in the second part of the URL in the HREF= attribute^#
external-location or libref.catalog	not specified	the specified path
external-location or libref.catalog	specified, but not NONE	the value of the URL= suboption
external-location or libref.catalog	NONE	No information from GPATH= or PATH=
fileref	specified or not specified	No information from GPATH= or PATH=
*In the CMS operating environment, you must use the URL= suboption in the GPATH= or PATH= option because CMS file names do not form valid URLs. #For both GPATH= and PATH=, if you do not specify the option, ODS does not use a default or substitute value for that option in creating the HREF= attribute.

Note: If you use a fileref as the file specification in the BODY=, CONTENTS=, or PAGE= option in the ODS HTML statement, and you do not use the URL= suboption in that option, ODS does not use information from GPATH= or PATH= when it creates the complete URL for any corresponding HREF= attributes. [cautend]

The last part of the URL that is used in an HREF= attribute is, by default, the name of the file that contains the target. ODS determines the name of the file from the file-specification that you use in the BODY=, CONTENTS=, or PAGE= option. (ODS does not create links or references to frame files.) For more information on these options, see the discussion of HTML-file-specification.)
If you specify the URL= suboption in one of these options, ODS uses the string that you specify instead of the file name.
Note: If you use a fileref as the file specification and do not use the URL= suboption, ODS does not use information from GPATH= or PATH= when it creates the complete URL for the HREF= attribute.

Operating Environment Information: In the CMS operating environment, you must specify the URL= suboption with the BODY=, CONTENTS=, or PAGE= option because CMS file names do not form valid URLs.

The anchor-name comes from the value of the ANCHOR= option.

Chapter Contents
Previous
Next
Top of Page

	BODY=file-specification
	CONTENTS=file-specification
	FRAME=file-specification
	PAGE=file-specification

	CLOSE
	EXCLUDE
	SELECT
	SHOW