Chapter Contents
Previous
Next
|
Chapter Contents |
Previous |
Next |
| SAS/GRAPH Software: Reference |
Operating Environment Information: On mainframes, you must also
use PATH= or GPATH= to direct the graphics output. 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. ![[cautionend]](../common/images/cautend.gif)
This section describes the ODS HTML statement
as it relates to SAS/GRAPH procedures.
|
ODS HTML HTML-file-specification(s)
|
action
<ANCHOR='string'> <ARCHIVE='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> <PARAMETERS=('parameter-name1'='parameter-value-1' ... 'parameter-name-n'='parameter-value=n')> <PATH=file-location <(URL='Uniform-Resource-Locator' | NONE )>> <RECORD_SEPARATOR='string' | NONE> <STYLE=style-definition> <TRANTAB='translation-table'>; |
| CLOSE | |
| EXCLUDE | |
| SELECT | |
| SHOW |
Note: For information on EXCLUDE, SELECT,
and SHOW, see The Complete Guide to the SAS Output Delivery System.
| 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=.
One of these arguments is required.
| Featured in: | Example 8. Creating a Simple Web Page with the ODS HTML Statement |
HTML-file-specification can be one or more of the following arguments. Values for file-specification follow the arguments.
| 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 |
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.
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.
File-specification identifies the file or SAS catalog to write to and can be one of the following:
where
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.
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.
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=.
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.
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=.
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.
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.
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 |
If you specify DEVICE=JAVA in a GOPTIONS statement, ARCHIVE= provides the argument for the ARCHIVE attribute in an <APPLET> tag. In this case, string specifies the location of the archive file that contains the class files that are necessary to run the applet. (Class files are binary Java files that the browser runs.) If you specify DEVICE=ACTIVEX in a GOPTIONS statement, ARCHIVE= provides the argument for the CODEBASE attribute in the <OBJECT> tag. This attribute should point to an executable file that installs the ActiveX control on your machine. This attribute is not necessary for generating dynamic SAS/GRAPH output if the ActiveX control is already installed on your machine. However, if you wish to publish your output on the Web or to mail the HTML results to someone else, it is wise to include the ARCHIVE= option so that the ActiveX control can, if necessary, be installed on the machine that is reading the results.
The string must be one that the browser can interpret. For instance, if the archive file is local to the machine that you are running SAS on, you can use the FILE protocol to identify the file. If you want to point to an archive file that is on a web server, use the HTTP protocol.
If you do not specify ARCHIVE= and you are using the JAVA device driver, ODS uses the value of the SAS system option APPLETOC=. This value points to the location of the Java archive files that ship with the SAS system. To find out what the value of this option is, you can either look in the Options window in the Files folder under Environment Control, or you can submit the following procedure step:
proc options option=appletloc;
run;There is no default if you are using the ACTIVEX device
driver.
The ARCHIVE attribute is a feature of Java 1.1. Therefore, if you are using the Java device driver, your browser must support this version of Java. Both Internet Explorer 4.01 and Netscape 4.05 support Java 1.1.
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.
Footnotes that are displayed by ODS HTML support most SAS/GRAPH FOOTNOTE 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.
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).
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.
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.
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 |
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 |
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.
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>
| 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. |
file-location can be one of the following:
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.
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.
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.
RECORD_SEPARATOR='0D0A'x
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.
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.
When you use the ODS HTML statement, you must do the following:
For more information about the output files generated
for use with the Web, see About the Output Files Generated for the Web.
When you are using ODS, it is wise to specify a QUIT
statement at the end of every procedure that supports RUN-group processing.
If you end every procedure step explicitly, rather than waiting for the next
PROC or DATA step to end it for you, the QUIT statement will cause the selection
list to clear, and you will be be less likely to encounter unexpected results.
ODS HTML automatically creates an anchor for every
piece of output generated by the SAS procedures. An anchor specifies a particular
location within an HTML file. In SAS/GRAPH,
an anchor usually defines a link target such as a graph whose location is
defined in an IMG element. The following generated HTML output shows how
the default anchor name
IDX is associated with the graph stored
in the file named
totals.gif:
<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.
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"> |
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.
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 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.
| 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.
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 |
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.