Dictionary of ODS Language Statements |
Valid: | anywhere |
Category: | ODS: Third-Party Formatted |
Interaction: | By default, when you execute a procedure
that uses the FORMCHAR system option (for example, PROC PLOT or PROC CHART),
ODS formats the output in SAS Monospace font. If you are creating output that
will be viewed in an operating environment that does not have SAS software
installed, this output will not be displayed correctly. The SAS Monospace
font is not recognized if SAS is not installed. For the correct display of
your document, include the following statement before your SAS program:
OPTIONS FORMCHAR="|----|+|---+=|-/\<>*"; |
Interaction: | To change the page orientation of the RTF output, specify the system option ORIENTATION=. To change the orientation, you will need to trigger the change by issuing the ODS RTF statement after the global options statement. See RTF Interaction with the ORIENTATION= System Option for details. |
Tip: | Microsoft Word 2002 is the current, official, minimum level that is supported. However, no problems have been found with Microsoft Word 2000 and SAS RTF files. |
Tip: | When producing large tables, use the ODS TAGSETS.RTF statement. For detailed information, see ODS TAGSETS.RTF Statement. |
Syntax |
ODS RTF <(<ID=> identifier)> action; |
ODS RTF <(<ID=> identifier)> <option(s)>; |
The following table lists the actions that are available for the ODS RTF statement.
Task | Action |
---|---|
Close the RTF destination and the file that is associated with it |
CLOSE |
Exclude output objects from the RTF destination |
EXCLUDE |
Select output objects for the RTF destination |
SELECT |
Write to the SAS log the current selection or exclusion list for the RTF destination |
SHOW |
closes the RTF destination and any files that are associated with it.
Tip: | When you close an ODS destination, ODS does not send output to that destination. To free more system resources, close destinations that you do not need. |
excludes output objects from the RTF destination.
Restriction: | The destination must be open for this action to take effect. |
Default: | NONE |
See also: | ODS EXCLUDE Statement |
selects output objects for the RTF destination.
Default: | ALL |
Restriction: | The destination must be open for this action to take effect. |
See also: | ODS SELECT Statement |
writes the current selection list or exclusion list for the destination to the SAS log.
Restriction: | The destination must be open for this action to take effect. |
See also: | ODS SHOW Statement |
Tip: | If the selection or exclusion list is the default list (SELECT ALL), then SHOW also writes the entire selection or exclusion list. |
The following table lists the options that are available for the ODS RTF statement.
Task | Option |
---|---|
Specify a unique base name for the anchor tag that identifies each output object in the current body file |
ANCHOR= |
Specify the text string that identifies the author. This text string is inserted into the metadata of a file. |
AUTHOR= |
Specify text to use as the first part of all links and references that ODS creates in output files |
BASE= |
Specify that the titles and footnotes are to be placed into the body of the RTF document and not into the header and footer sections |
BODYTITLE |
Specify that the titles and footnotes are to be placed into the body of the RTF document and not into the header and footer sections. The titles and footnotes will also be placed into cells or tables. |
BODYTITLE_AUX |
Specify the number of columns to create on each page of output |
COLUMNS= |
Specify whether to produce a table of contents page |
CONTENTS |
Specify a cascading style sheet to apply to your output |
CSSSTYLE= |
Specify a device for the RTF output destination |
DEVICE= |
Override the encoding for input or output processing (transcodes) of external files |
ENCODING= |
Open the ODS RTF destination and specify the name of the file to which to write information |
FILE= |
Specify the location where footnotes are printed in the graphics output |
GFOOTNOTE
| NOGFOOTNOTE |
Control the location where titles are printed in the graphics output |
GTITLE
| NOGTITLE |
Open multiple instances of the same destination at the same time |
ID= |
Specify the image resolution for the graphical output |
IMAGE_DPI= |
Control where tables split on a page |
KEEPN
| NOKEEPN |
Create a new body file at the specified starting point |
NEWFILE= |
Suppress currently defined footnotes in the graphics file. They appear in the RTF file instead. |
NOGFOOTNOTE |
Suppress currently defined titles in the graphics file. They appear in the RTF file instead. |
NOGTITLE |
Specify whether contents data is inserted into the RTF file |
NOTOC_DATA
|TOCDATA |
Insert the text that you specify into the metadata of the RTF file |
OPERATOR= |
Specify that the output from the destination be added to an ODS package |
PACKAGE |
Specify the location of an aggregate storage location or a SAS catalog for all RTF files |
PATH= |
Specify an alternative character or string to separate lines in the output files |
RECORD_SEPARATOR= |
Write to the RTF file the time and date that you started your SAS session |
SASDATE |
Control page breaks |
STARTPAGE= |
Specify a style definition to use in writing the RTF files |
STYLE= |
Insert text into your RTF output |
TEXT= |
Insert the text string that you want as your title into the metadata of a file |
TITLE= |
Specify a translation table to use when you transcode a file for output |
TRANTAB= |
specifies the base name for the RTF anchor tag that identifies each output object in the current file.
Each output object must have an anchor tag to which other files will link or reference. The references, which ODS automatically creates, point to the name of an anchor. Therefore, each anchor name in a file must be unique.
is the base name for the RTF anchor tag that identifies each output object in the current file.
ODS increments the name that you specify and creates unique anchor names. For example, if you specify ANCHOR= 'tabulate', then ODS names the first anchor tabulate. The second anchor is named tabulate1; the third is named tabulate2, and so on.
Requirement: | You must enclose anchor-name in quotation marks. |
inserts the text string that you specify as the author into the metadata of a file.
Requirement: | You must enclose author-text in quotation marks. |
specifies the text to use as the first part of references that ODS creates in the output file.
is the text that ODS uses as the first part of all references that ODS creates in the file.
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/.
Requirement: | You must enclose base-text in quotation marks. |
specifies that SAS titles and footnotes are placed into the body of the RTF document instead of into the headers and footers section of the RTF document.
Restriction: | The BODYTITLE option can be specified only when you create a new RTF file. |
Interaction: |
When you set the STARTPAGE= option
to YES (the default), ODS inserts a new page at the start of each procedure.
ODS relies on Word to place headers and footers correctly before and after
the procedures. When you specify BODYTITLE, titles and footnotes are removed
from the header and footer sections of the RTF document. Titles and footnotes
are then placed into the body of the document, and are appended to every
TABLE. Therefore, when you set the STARTPAGE= option to YES and specify the
BODYTITLE option, the titles and footnotes might not repeat on every page.
For example, if there is a table that spans multiple pages, the title will
be on the first page only, and the footnote will be on the last page only.
Note: When you specify the BODYTITLE option, Microsoft Word no longer controls the placement of the header and footer text, but Microsoft Word still controls other header and footer information, such as page number and date. |
Tip: | The background is not honored on the title cells. |
See also: | BODYTITLE_AUX option. Use the BODYTITLE_AUX option when you want titles and footnotes placed in tables in the body of the RTF document. |
specifies that SAS titles and footnotes be placed into the body of the RTF document instead of into the headers and footers section of the RTF document. These titles and footnotes are put into cells, which allows titles and footnotes to be centered, left-justified, or right-justified.
Restriction: | You can specify the BODYTITLE_AUX option only when you are creating a new RTF file. |
Interaction: |
When you set the STARTPAGE= option
to YES (the default), ODS inserts a new page at the start of each procedure
and relies on Word for the correct placement of headers and footers before
and after the procedures. When you specify BODYTITLE_AUX, titles and footnotes
are removed from the header and footer sections of the RTF document. Titles
and footnotes are then placed into the body of the document, and they are
appended to every TABLE. Therefore, when you set the STARTPAGE= option to
YES and you specify the BODYTITLE_AUX option, the titles and footnotes might
not repeat on every page. For example, if there is a table that spans multiple
pages, then the title will be on the first page only, and the footnote will
be on the last page only.
Note: When you specify the BODYTITLE_AUX option, Microsoft Word no longer controls the placement of the header and footer text, but Microsoft Word still controls other header and footer information, such as page number and date. |
See also: | BODYTITLE option |
Featured in: | Justifying Title and Footnotes When You Specify the BODYTITLE_AUX Option |
specifies the number of columns to place across each page of output.
is the number of one-inch columns that you want on the page.
specifies the maximum number of one-inch-wide columns for the paper size and margin setting. This value is dependent upon the paper size and page orientation.
produces a table of contents page for RTF documents that are opened in Microsoft Word. The table of contents page contains a Table of Contents field, which puts all of the contents information that is embedded in the document into a table of contents. To expand the table of contents, right-click under the title in Microsoft Word and select Update Field from the selection list.
Restriction: | Do not use the CONTENTS option with the NEWFILE option. |
Tip: | To go to a specific topic in the document, you can double-click or hold down the CTRL key and click on the topic in the table of contents. You might have to configure Microsoft Word to use the CTRL-click method by selecting Tools Options Edit and checking Use CTRL + Click to follow hyperlink. |
Tip: | You must specify the TOC_DATA option to view the text that is captured in the Table of Contents. If not, the Table of Contents page displays the error message "Error! No table of contents entries found." NOTOC_DATA is the default option that is used. |
See also: | TOC_DATA option |
Featured in: | Creating a Table of Contents from Embedded Data |
specifies a cascading style sheet to apply to your output.
specifies a file, fileref, or URL that contains CSS code.
file-specification is one of the following:
is the name of the external file.
Requirement: | You must enclose external-file in quotation marks. |
is a file reference that has been assigned to an external file. Use the FILENAME statement to assign a fileref.
See: | For information about the FILENAME statement, see SAS Language Reference: Dictionary. |
is a URL to an external file.
Requirement: | You must enclose external-file in quotation marks. |
specifies one or more media blocks that correspond to the type of media to which your output will be rendered. CSS uses media type blocks to specify the different media on which a document is to be presented: on the screen, on paper, with a speech synthesizer, with a braille device, and so on.
ODS adds the media block to your output in addition to the CSS code that is not contained in any media blocks. By using the media-type suboption and the general CSS code, you can import the section of a CSS file intended only for a specific media type.
Default: | If you do not specify a media-type in your ODS statement, but you do specify media types in your CSS file, ODS uses the Screen media type. |
Range: | You can specify up to ten different media types. |
Requirement: | You must enclose media-type in parentheses. |
Requirement: | You must specify media-type next to the file-specification specified by the CSSSTYLE= option. |
Tip: | If you specify multiple media types, ODS applies all of the style information in all of the media types to your output. However, if there is duplicate style information in different media blocks, then ODS uses the styles from the last media block. |
Interaction: | If you specify both the STYLE= option and the CSSSTYLE= option on an ODS statement, ODS uses the last option that you specified. |
Requirement: | CSS files must be written in the same type of CSS produced by the ODS HTML statement. Only class names are supported, with no IDs and no context-based selectors. To view the CSS code that ODS creates, you can specify the STYLESHEET= option, or you can view the source of an HTML file and look at the code between the <STYLE> </STYLE> tags at the top of the file. For an example of a valid ODS CSS file, see Applying a CSS File to ODS Output. |
Featured in: | Applying a CSS File to ODS Output |
specifies the name of a device driver. ODS automatically selects an optimal default device for each open output destination.
The following table lists default devices for the most common ODS output destinations.
Tip: | Specifying a device on the ODS DEVICE= option takes precedence over the SAS global option and the graphics option. |
See: | DEVICE= System Option in SAS Language Reference: Dictionary. Also refer to Device Drivers in SAS/GRAPH: Reference for information on selecting device drivers. |
overrides the encoding for input or output processing (transcodes) of external files.
See: | For information about the ENCODING= option, see SAS National Language Support (NLS): Reference Guide. |
opens the RTF destination and specifies the RTF file or SAS catalog to which to write. This file remains open until you do one of the following actions:
is the name of an external file to which to write.
Requirement: | You must enclose external-file in quotation marks. |
is a file reference that has been assigned to an external file. Use the FILENAME statement to assign a fileref.
See also: | The section on statements in SAS Language Reference: Dictionary for information about the FILENAME statement. |
Restriction: | You cannot use the FILE=fileref option with the NEWFILE= option. |
Alias: | BODY= |
Interaction: | In an ODS RTF statement that refers to an open RTF destination, the FILE= option forces ODS to close the destination and all files that are associated with it, and to open a new instance of the destination. For more information, see Opening and Closing the RTF Destination. |
See also: | NEWFILE= |
controls the location of the footnotes that are defined by the graphics program that generates the RTF output.
includes all of the currently defined footnotes within the graphics output.
prevents all of the currently defined footnotes from appearing in the graphics file. Instead, they become part of the RTF file.
controls the location of the titles that are defined by the graphics program that generates the RTF output.
includes all of the currently defined titles within the graphics output that is called by the body file.
prevents all of the currently defined titles from appearing in the graphics output. Instead, the titles become part of the RTF file.
Restriction: | If identifier is a number, the number must be positive. |
Requirement: | You must specify the ID= option immediately after the destination name. |
Tip: | You can omit the ID= option, and use a name or a number instead to identify the instance. |
Featured in: | Opening Multiple Instances of the Same Destination at the Same Time |
specifies the image resolution for graphical output.
Default: | 200 |
Restriction: | The IMAGE_DPI= option affects template-based graphics only. |
controls where tables split on a page.
creates a new file at the specified starting-point.
starting-point can be one of the following:
writes all output to the next file that you open, and then stops incrementing.
starts a new file for the results of each BY group.
Alias: | TABLE |
starts a new file each time that you start a new procedure.
Default: | NONE |
See the description of GFOOTNOTE | NOFOOTNOTE in this section.
See the description of GTITLE | NOGTITLE in this section.
See the description of TOC_DATA in this section.
inserts the text you specify into the metadata of the RTF file.
specifies that the output from the destination be added to a package.
specifies the name of a package that was created with the ODS PACKAGE statement. If no name is specified, then the output is added to the unnamed package that was opened last.
See also: | ODS PACKAGE Statement |
specifies the location of an aggregate storage location or a SAS catalog for all RTF files. If the GPATH= option is not specified, all graphics output files are written to the "aggregate-file-storage-specification" or libref.
specifies an aggregate storage location such as directory, folder, or partitioned data set.
Requirement: | You must enclose aggregate-file-storage-location in quotation marks. |
is a file reference that has been assigned to an aggregate storage location. Use the FILENAME statement to assign a fileref.
Interaction: | If you use a fileref in the PATH= option, then ODS does not use information from PATH= when it constructs links. |
See: | For information about the FILENAME statement, see SAS Language Reference: Dictionary. |
specifies a SAS catalog to write to.
See: | For information about the LIBNAME statement, see SAS Language Reference: Dictionary. |
specifies a URL for the file-specification.
is the URL you specify. ODS uses this URL instead of the filename in all the links and references that it creates to the file.
specifies that no information from the PATH= option appears in the links or references.
Tip: | This option is useful for building output files that can be moved from one location to another. The links from the contents and page files must be constructed with a single-name URL, and the contents, page, and body files must be in the same location. |
Interaction: | If you use the BODY= or FILE= external file option in conjunction with the PATH= option, the external file specification should not include path information. |
specifies an alternative record separator, which is a character or string that separates lines in the output files.
Different operating environments use different separator characters. If you do not specify a record separator, ODS formats the RTF files for the environment in which you run the SAS job. However, if you are generating files in one operating environment to view in another operating environment that uses a different separator character, you can specify a record separator that is appropriate for the target environment.
represents one or more characters in hexadecimal or ASCII format. 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
Operating Environment Information: In a mainframe environment, the option that specifies a record separator for a carriage-return character and a linefeed character for use with an ASCII file system is:
RECORD_SEPARATOR= '0D25'x
Requirement: | You must enclose alternative-separator in quotation marks. |
produces RTF output that is appropriate for the environment in which you run the SAS job.
Operating Environment Information: In many operating environments, using a value of NONE has the same result as omitting the RECORD_SEPARATOR option.
Operating Environment Information: In a mainframe environment, by default, ODS produces a binary file that contains embedded record-separator characters. This approach means that the file is not restricted by the line-length restrictions on ASCII files, but it also means that the lines are concatenated if you view the file in an editor.
If you want to format the RTF files in a manner that allows you to read them with an editor, use RECORD_SEPARATOR= NONE. In this case, ODS writes one line of RTF at a time to the file. When you use a value of NONE, the logical record length of the file to which you are writing must be at least as long as the longest line that ODS produces. Otherwise, RTF might wrap to another line at an inappropriate place.
Alias: |
|
writes to the RTF file the time and the date that you started your SAS session.
Restriction: | You can specify SASDATE only when you open a new file. If you specify the option at any other time, ODS writes a warning message to the SAS log. |
Interaction: | To reset the SAS session time that is input into the RTF file, use the DTRESET system option. |
See: | For information about the DTRESET system option, see SAS Language Reference: Dictionary. |
inserts a new page at the start of each procedure and within certain procedures, as is requested by the procedure code.
instructs ODS not to insert any new pages at the start of each procedure or within certain procedures, even if the procedure code requests new pages. A new page begins only when a page is filled or when you specify STARTPAGE= NOW.
forces the immediate insertion of a new page.
Tip: | This option is useful primarily when the current value of the STARTPAGE= option is NO. Otherwise, each new procedure forces a new page automatically. |
Tip: | Specifying STARTPAGE= NO prevents forced page breaks. You can turn on forced page breaking again by specifying STARTPAGE=YES. You can insert a page break at any time by specifying STARTPAGE=NOW. |
Default: | YES |
specifies the style definition for ODS to use to write the RTF files.
describes how to display the presentation aspects (color, font face, font size, and so on) of your SAS output. A style definition determines the overall appearance of the documents that use that style definition. Each style definition consists of style elements.
Main discussion: | For a complete discussion of style definitions, see TEMPLATE Procedure: Creating a Style Template (Definition). |
inserts text into your RTF output.
is the text that you want to insert into your RTF output. You can also use TEXT= to annotate other output.
inserts the text string that you specify as the title into the metadata of a file.
Requirement: | You must enclose a title-text in quotation marks. |
specifies whether contents data is embedded in the RTF file as hidden text.
instructs ODS not to insert contents data into the RTF file.
instructs ODS to insert contents data into the RTF file.
Tip: |
Insertion of table of contents data can
be resumed in the middle of a SAS program by including the following statement:
ods rtf toc_data; |
Default: | NOTOC_DATA |
Tip: | To create a visible table of contents from the inserted table of contents data, specify the CONTENTS option. |
See also: | CONTENTS option |
Featured in: | Creating a Table of Contents from Embedded Data |
specifies the translation table for ODS to use when it transcodes a file for output.
See: | For information about the TRANTAB= option see SAS National Language Support (NLS): Reference Guide. |
Details |
You can modify an open RTF destination with many ODS RTF options. However, the FILE= option automatically closes the open destination that is referred to in the ODS RTF statement and closes any files that are associated with it, and then opens a new instance of the destination. If you use one of these options, you should explicitly close the destination yourself.
RTF produces output for Microsoft Word 2002. Although other applications can read RTF files, the RTF output might not work successfully with the other applications.
The RTF destination enables you to view and edit the RTF output. ODS does not define the "vertical measurement," which means that SAS does not determine the optimal place to position each item on the page. For example, page breaks are not always fixed because you do not want your RTF output tables to split at inappropriate places when you edit your text. Your tables remain intact on one page, or break where you specify.
However, Microsoft Word needs to know the widths of table columns; and Microsoft Word cannot adjust tables if they are too wide for the page. Therefore, ODS measures the width of the text and tables (horizontal measurement). All of the column widths can be set properly by SAS and the table can be divided into panels if it is too wide to fit on a single page.
In short, when producing RTF output for input to Microsoft Word, SAS determines the horizontal measurement and Microsoft Word controls the vertical measurement. Because Microsoft Word can determine how much room there is on the page, your tables display consistently even after you modify your RTF file.
However, in SAS version 9.2, the ODS Measured tagset is introduced. This tagset enables users to specify how and where page breaks occur and when to place titles and footnotes into the body of a page. Refer to ODS TAGSETS.RTF Statement for information on using Measured RTF.
Note: Complex tables that contain a large number of observations can reduce system efficiencies and take longer to process.
ODS RTF produces output in rich text format, which supports three formats for graphics that MS Word can read.
Format for Graphics | Corresponding SAS Graphics Driver |
---|---|
emfblips | SASEMF |
pngblips | PNG |
jpegblips | JPEG |
When you do not specify a target device, the default target is SASEMF. You can also use the ACTIVEX, ACTXIMG, JAVAIMG graphics drivers to generate graphics in your RTF documents. The ACTIVEX driver generates an ActiveX control. The ACTXIMG and JAVAIMG drivers generate PNG files with the ACTIVEX Control or JAVA Applets appropriately. For more information about graphics devices, see SAS/GRAPH: Reference.
Note: When you specify the JAVA device in the ODS RTF statement, the JAVAIMG driver is used.
Examples |
ODS RTF statement:
|
#BYVAL parameter in titles | |
NOBYLINE|BYLINE system option | |
OPTIONS statement | |
PROC FORMAT | |
PROC PRINT | |
PROC SORT | |
PROC REPORT | |
PROC TABULATE | |
TITLE statement |
The following example creates a table of contents page that contains embedded table of contents data for some procedures but not for others. The insertion of the table of contents data can be turned on and off in the middle of a program.
proc sort data=Grain_Production; by year country type; run; |
ods listing close; |
ods rtf file='Grain.Rtf' contents toc_data; |
options nobyline; title 'Leading Grain-Producing Countries'; title2 'for #byval(year)'; |
options byline; title2; |
ods rtf notoc_data; |
ods rtf toc_data; |
proc print data=Grain_Production; run; |
ods rtf close; |
ODS RTF statement:
|
OPTIONS statement | |
PROC PRINT | |
TITLE statement |
When you want to place the titles and footnotes in the body of the RTF output, you usually specify the BODYTITLE option. However, to center your titles and footnotes or to justify them, you need to specify the BODYTITLE_AUX option. The following example shows how to left justify, right justify, and center titles and footnotes in the body of the output.
Note: The preferred way to accomplish this functionality is to use the measured ODS TAGSETS.RTF statement that was introduced in 9.2. Refer to ODS TAGSETS.RTF Statement.
OPTIONS NODATE NOSTIMER LS=78 PS=60; |
ods listing close; |
ods rtf file="bodytitle_aux.rtf" bodytitle_aux; |
proc print data=sashelp.class; run; |
title j=l "left" j=c "center" j=r "right"; title2 j=l "left"; title3 j=c "center"; title4 j=r "right"; footnote j=l "left" j=c "center" j=r "right"; run; |
ods rtf close; |
ODS RTF statement:
|
OPTIONS statement:
| |||
PROC PRINT | |||
TITLE statement |
When you want to change the RTF page orientation, specify the ORIENTATION= system option. To activate or trigger this change of the page orientation, the ODS RTF statement needs to follow the ORIENTATION= option. The following example provides example code for specifying a page orientation change within an RTF file.
OPTIONS NODATE NOSTIMER LS=78 PS=60; |
ods listing close; |
title 'Page Orientation'; title2 'Default'; |
ods rtf file="ChgOrientation.rtf"; |
proc print data=sashelp.class (obs=1); run; |
title 'Page Orientation'; title2 'Landscape'; |
options orientation=landscape; |
ods rtf; |
proc print data=sashelp.class (obs=1); run; |
ods rtf close; |
Copyright © 2008 by SAS Institute Inc., Cary, NC, USA. All rights reserved.