ODS RTF Statement

Opens, manages, or closes the RTF destination, which produces output written in Rich Text Format for use with Microsoft Word 2002.

Valid in:	Anywhere
Category:	ODS: Third-Party Formatted
Interactions:	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="\|----\|+\|---+=\|-/\<>*"; 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.
Tips:	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. When producing large tables, use the ODS TAGSETS.RTF statement. For detailed information, see ODS TAGSETS.RTF Statement .

Syntax

Details

Opening and Closing the RTF Destination

Understanding How RTF Formats Output

ODS RTF and Graphics

Examples

Example 1: Creating a Table of Contents from Embedded Data

Example 2: Justifying Title and Footnotes When You Specify the BODYTITLE_AUX Option

Example 3: RTF Interaction with the ORIENTATION= System Option

Syntax

ODS RTF <(<ID=> identifier)> action;

ODS RTF <(<ID=> identifier)> <option(s)> ;

Summary of Optional Arguments

(ID= identifier)

Open multiple instances of the same destination at the same time

ANCHOR= 'anchor-name'

Specify a unique base name for the anchor tag that identifies each output object in the current body file

AUTHOR= 'author-text'

Specify the text string that identifies the author. This text string is inserted into the metadata of a file.

BASE= 'base-text'

Specify text to use as the first part of all links and references that ODS creates in output files

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

BODYTITLE_AUX

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

Close the destination and the file that is associated with it

COLUMNS= n | MAX

Specify the number of columns to create on each page of output

CONTENTS

Specify whether to produce a table of contents page

CSSSTYLE= 'file-specification'<(media-type-1 …media-type-10>)>

Specify a cascading style sheet to apply to your output

DEVICE= device-driver

Specify a device for the RTF output destination

ENCODING= local-character-set-encoding

Override the encoding for input or output processing (transcodes) of external files

EXCLUDE exclusion(s)| ALL | NONE

Exclude output objects from the destination

FILE= 'external-file' | fileref

Open the ODS RTF destination and specify the name of the file to which to write information

GFOOTNOTE | NOGFOOTNOTE

Specify the location where footnotes are printed in the graphics output

GTITLE | NOGTITLE

Control the location where titles are printed in the graphics output

IMAGE_DPI

Specify the image resolution for the graphical output

KEEPN | NOKEEPN

Control where tables split on a page

NEWFILE= starting-point

Create a new body file at the specified starting point

NOGFOOTNOTE

Suppress currently defined footnotes in the graphics file. They appear in the RTF file instead

NOGTITLE

Suppress currently defined titles in the graphics file. They appear in the RTF file instead

NOTOC_DATA

Specify whether contents data is inserted into the RTF file

OPERATOR= 'text-string'

Insert the text that you specify into the metadata of the RTF file

PACKAGE <package-name>

Specify that the output from the destination be added to an ODS package

PATH= 'aggregate-file-storage-specification' | fileref | libref.catalog (URL= 'Uniform-Resource-Locator' | NONE)

Specify the location of an aggregate storage location or a SAS catalog for all RTF files

PREPAGE='text-string'

Specify a text string that occurs before a table on a page

RECORD_SEPARATOR= 'alternative-separator' | NONE

Specify an alternative character or string to separate lines in the output files

SASDATE

Write to the RTF file the time and date that you started your SAS session

SELECT selection(s) | ALL | NONE

Select output objects for the destination

SHOW

Write to the SAS log the current selection or exclusion list for the destination

STARTPAGE= BYGROUP | YES | NO | NOW

Control page breaks

STYLE= style-definition

Specify a style definition to use in writing the RTF files

TEXT= 'text-string'

Insert text into your RTF output

TITLE= 'title-text'

Insert the text string that you want as your title into the metadata of a file

TOC_DATA | NOTOC_DATA

Specify whether contents data is inserted into the RTF file

TRANTAB= translation-table

Specify a translation table to use when you transcode a file for output

Actions

The following actions are available for the ODS RTF statement:

CLOSE: closes the destination and any files that are associated with it. For Printer destinations, you cannot print the file until you close the destination.

Tip:When an ODS destination is closed, ODS does not send output to that destination. Closing an unneeded destination conserves system resources.

EXCLUDE exclusion(s)| ALL | NONE: excludes one or more output objects from the destination.

Default:NONE

Restriction:A destination must be open for this action to take effect.

See:ODS EXCLUDE Statement

SELECT selection(s) | ALL | NONE: selects output objects for the specified destination.

Default:ALL

Restriction:A destination must be open for this action to take effect.

See:ODS SELECT Statement

SHOW: 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.

Tip:If the selection or exclusion list is the default list (SELECT ALL), then SHOW also writes the entire selection or exclusion list. For information about selection and exclusion lists, see Selection and Exclusion Lists.

See:ODS SHOW Statement

Optional Arguments

ANCHOR= 'anchor-name'

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.

anchor-name: 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.

Alias:NAMED_DEST= | BOOKMARK=

Tips:It is useful to specify new anchor names at various points in your program when you want other RTF files to link to specific parts of your RTF output. Because you can control where the anchor name changes, you know in advance what the anchor name will be at those points.

You can change anchor names as often as you want by submitting the ANCHOR= option in an ODS RTF statement anywhere in your program. After you specify an anchor name, it remains in effect until you specify a new one.

AUTHOR= 'author-text'

inserts the text string that you specify as the author into the metadata of a file.

author-text: is the text in the metadata of an open file that indicates the author.

Requirement:You must enclose author-text in quotation marks.

BASE= 'base-text'

specifies the text to use as the first part of references that ODS creates in the output file.

base-text

is the text that ODS uses as the first part of all references that ODS creates in the file.

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/.

Requirement:You must enclose base-text in quotation marks.

BODYTITLE: 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.

Interactions: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.

When you specify the BODYTITLE option, Microsoft Word no longer controls the placement of the header and footer text. However, 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: BODYTITLE_AUX option. Use the BODYTITLE_AUX option when you want titles and footnotes placed in tables in the body of the RTF document.

BODYTITLE_AUX: 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.

Interactions: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.

When you specify the BODYTITLE_AUX option, Microsoft Word no longer controls the placement of the header and footer text. However, Microsoft Word still controls other header and footer information, such as page number and date.

See: BODYTITLE option

Example:Justifying Title and Footnotes When You Specify the BODYTITLE_AUX Option

COLUMNS= n | MAX

specifies the number of columns to place across each page of output.

n: is the number of one-inch columns that you want on the page.

MAX: 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.

Default:The number of one-inch columns that fit on the page

Interaction:When you specify the COLUMNS= option, the STARTPAGE=NO option will not be honored.

Tips:Titles are considered tables and not RTF instructions in Measured RTF (ODS TAGSETS.RTF statement). When you use the COLUMNS= option with Measured RTF, titles will appear at the top of each column. However, ODS truncates the titles to fit the column width.

If you specify a value greater than the maximum number of one inch columns that can fit on the page, a note is printed to the SAS log that states what the maximum value can be for that page.

CONTENTS: 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.

Tips: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 ToolsOptionsEdit and checking Use CTRL + Click to follow hyperlink.

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:TOC_DATA option

Example:Creating a Table of Contents from Embedded Data

CSSSTYLE= 'file-specification'<(media-type-1 …media-type-10>)>

specifies a cascading style sheet to apply to your output.

file-specification

specifies a file, fileref, or URL that contains CSS code.

file-specification is one of the following:

"external-file": is the name of the external file.

Requirement:You must enclose external-file in quotation marks.

fileref: 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 Statements: Reference.

“URL”: is a URL to an external file.

Requirement:You must enclose external-file in quotation marks.

(media-type-1<… media-type-10>): 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.

Requirements:You must enclose media-type in parentheses.

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.

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 do one of the following:

Specify the STYLESHEET= option.
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.

Interaction:If you specify both the STYLE= option and the CSSSTYLE= option on an ODS statement, ODS uses the last option that you specified.

Example:Applying a CSS File to ODS Output

DEVICE= device-driver

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.

The following table lists the default devices for the most common ODS output destinations. These default devices are used when graphics are created using SAS/GRAPH or ODS Graphics. For a complete list of supported devices and file types, see Supported File Types for Output Destinations.

Default Devices for ODS Output Destinations

Output Destination	Default Device
HTML	PNG
LISTING	PNG
Measured RTF	PNG
RTF	PNG
PCL	Scalable Vector Graphics (SVG)
PDF	Scalable Vector Graphics (SVG)
POSTSCRIPT	PNG
PRINTER	Host Specific Default Printer
Markup Tagsets	All markup family tagsets have the default value built in.

Restriction:When you specify a device in an ODS destination statement, do not specify the ACTIVEX, ACTXIMG, JAVA, or JAVAIMG devices.

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 System Options: Reference. For information about selecting device drivers, see Using Graphics Devices in SAS/GRAPH: Reference.

ENCODING= local-character-set-encoding: 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.

FILE= 'external-file' | fileref

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:

Close the RTF destination with ODS RTF CLOSE or ODS _ALL_ CLOSE.
Specify a different file to which to write.

external-file: is the name of an external file to which to write.

Requirement:You must enclose external-file in quotation marks.

fileref: is a file reference that has been assigned to an external file. Use the FILENAME statement to assign a fileref.

Restriction:You cannot use the FILE=fileref option with the NEWFILE= option.

See:The section on statements in SAS Statements: Reference for information about the FILENAME statement.

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:NEWFILE= option

GFOOTNOTE | NOGFOOTNOTE

controls the location of the footnotes that are defined by the graphics program that generates the RTF output.

GFOOTNOTE: includes all of the currently defined footnotes within the graphics output.

NOGFOOTNOTE: prevents all of the currently defined footnotes from appearing in the graphics file. Instead, they become part of the RTF file.

Default:GFOOTNOTE

Restriction:This option applies only to SAS programs that produce one or more device-based graphics, or graphics created by the SGPLOT procedure, the SGPANEL procedure, or the SGSCATTER procedure.

GTITLE | NOGTITLE

controls the location of the titles that are defined by the graphics program that generates the RTF output.

GTITLE: includes all of the currently defined titles within the graphics output that is called by the body file.

NOGTITLE: prevents all of the currently defined titles from appearing in the graphics output. Instead, the titles become part of the RTF file.

Default:GTITLE

Restriction:This option applies only to SAS programs that produce one or more device-based graphics, or graphics created by the SGPLOT procedure, the SGPANEL procedure, or the SGSCATTER procedure.

(ID= identifier)

identifier: can be a number or a series of characters that begin with a letter or an underscore.

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.

Example:Opening Multiple Instances of the Same Destination at the Same Time

IMAGE_DPI: specifies the image resolution for graphical output.

Default:96

KEEPN | NOKEEPN

controls where tables split on a page.

KEEPN: ODS allows table splits only if the entire table cannot fit on one page.

NOKEEPN: ODS lets a table split at a page break.

Tip:Although KEEPN minimizes page breaks in tables, it might use substantially more paper than NOKEEPN. This is because the KEEPN option issues a page break before starting to print any table that does not fit on the remainder of the page.

NEWFILE= starting-point

creates a new file at the specified starting-point.

starting-point can be one of the following:

BYGROUP: starts a new file for the results of each BY group.

NONE: writes all output to the body file that is currently open.

OUTPUT: starts a new file for each output object. For SAS/GRAPH this means that ODS creates a new file for each SAS/GRAPH output file that the program generates.

Alias:TABLE

PROC: starts a new file each time you start a new procedure.

Default:NONE

Restrictions:You cannot use both the NEWFILE= and TEXT= options in the same ODS RTF statement. You must use a separate ODS RTF statement for each of these options.

You cannot use the NEWFILE= option with the FILE=fileref option.

Tip:If you end the filename with a number, then ODS begins incrementing with that number. In the following example, ODS names the first body file MAY5.XML, and names additional body files MAY6.XML, MAY7.XML, and so on.

NOGFOOTNOTE: See the description of GFOOTNOTE | NOFOOTNOTE in this section.

NOGTITLE: See the description of GTITLE | NOGTITLE in this section.

NOTOC_DATA: See the description of TOC_DATA in this section.

OPERATOR= 'text-string'

inserts the text that you specify into the metadata of the RTF file.

text-string: is the text in the metadata of a file that indicates the author.

Requirement:You must enclose text-string in quotation marks.

PACKAGE <package-name>

specifies that the output from the destination be added to a package.

package-name: 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:ODS PACKAGE Statement

PATH= 'aggregate-file-storage-specification' | fileref | libref.catalog (URL= 'Uniform-Resource-Locator' | NONE)

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.

'aggregate-file-storage-location': specifies an aggregate storage location such as directory, folder, or partitioned data set.

Requirement:You must enclose aggregate-file-storage-location in quotation marks.

fileref: 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:FILENAME Statement in SAS Statements: Reference.

libref.catalog: specifies a SAS catalog to write to.

See:LIBNAME Statement in SAS Statements: Reference.

URL= 'Uniform-Resource-Locator' | NONE

specifies a URL for the file-specification.

Uniform-Resource-Locator: is the URL that you specify. ODS uses this URL instead of the filename in all the links and references that it creates to the file.

NONE: 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.

PREPAGE='text-string'

specifies a text string that occurs before a table on a page.

text-string: is the text at the top of the table, after the titles. The text is placed before any tables created by the procedure.

Requirement:You must enclose text-string in quotation marks.

RECORD_SEPARATOR= 'alternative-separator' | NONE

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.

alternative-separator

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 following option specifies a record separator for a carriage-return character and a linefeed character for use with an ASCII file system:

RECORD_SEPARATOR= '0D25'x

Requirement:You must enclose alternative-separator in quotation marks.

NONE: 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. However, this 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 enables 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.

Aliases:RECSEP=

RS=

SASDATE: 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 System Options: Reference.

STARTPAGE= BYGROUP | YES | NO | NOW

controls page breaks.

BYGROUP: specifies to insert page breaks after each BY group.

YES: inserts a new page at the start of each procedure and within certain procedures, as is requested by the procedure code.

Alias:ON

Interactions:When the STARTPAGE= option is set 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, 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 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 appear on only the first page, and the footnote will appear on only the last page.

Note that when you specify the BODYTITLE= option, Microsoft Word no longer controls the placement of the headers and footers text. However, Word still controls other header and footer information, such as page number and date.

NO: 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.

Alias:NEVER

Interaction:When you specify the COLUMNS= option, the STARTPAGE=NO option is not honored.

Tip:This option prints only the first set of titles and the first set of footnotes to the RTF file.

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.

Default:YES

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.

STYLE= style-definition

specifies the style definition for ODS to use to write the RTF files.

style-definition: 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.

See:For a complete discussion of style definitions, see TEMPLATE Procedure: Creating a Style Template.

Default:If you do not specify a style definition, ODS uses the file that is specified in the SAS registry subkey: ODS

DESTINATIONS

RTF. By default, this value specifies RTF for traditional RTF and Measured RTF.

TEXT= 'text-string'

inserts text into your RTF output.

text-string: is the text that you want to insert into your RTF output. You can also use TEXT= to annotate other output.

Restriction:You cannot use both the NEWFILE= and TEXT= options in the same ODS RTF statement. You must use a separate ODS RTF statement for each of these options.

Requirement:You must enclose a text-string in quotation marks.

TITLE= 'title-text'

inserts the text string that you specify as the title into the metadata of a file.

title-text: is the text in the metadata of a file that indicates the title.

Requirement:You must enclose a title-text in quotation marks.

TOC_DATA | NOTOC_DATA

specifies whether contents data is embedded in the RTF file as hidden text.

NOTOC_DATA: instructs ODS not to insert contents data into the RTF file.

TOC_DATA

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: CONTENTS option

Example:Creating a Table of Contents from Embedded Data

TRANTAB= translation-table: specifies the translation table for ODS to use when it transcodes a file for output.

See:For more information, see TRANTAB= System Option in SAS National Language Support (NLS): Reference Guide.

Details

Opening and Closing the RTF Destination

You can modify an open RTF destination with many ODS RTF options. However, the FILE= option performs the following actions on an open RTF destination:

close the open destination referred to in the ODS RTF statement
close any files associated with the open RTF destination
open a new instance of the RTF destination

If you use the FILE= option, you should explicitly close the destination yourself.

Understanding How RTF Formats Output

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. For information about using Measured RTF, see ODS TAGSETS.RTF Statement .

Note: Complex tables that contain a large number of observations can reduce system efficiencies and take longer to process.

ODS RTF and Graphics

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

Example 1: Creating a Table of Contents from Embedded Data

Features:	ODS RTF statement action:: CLOSE ODS RTF statement options:: CONTENTS NOTOC_DATA TOC_DATA
Other features:	#BYVAL parameter in titles NOBYLINE\|BYLINE system option OPTIONS statement PROC FORMAT PROC PRINT PROC SORT PROC REPORT PROC TABULATE TITLE statement
Data set:	Grain_Production
Format:	$CNTRY.

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.

Program

proc sort data=Grain_Production;
   by year country type;
run;

ods html close;

ods rtf file='Grain.Rtf' contents toc_data;

options nobyline;
title 'Leading Grain-Producing Countries';
title2 'for #byval(year)';

proc report data=Grain_Production nowindows;
   by year;
   column country type kilotons;
   define country  / group width=14 format=$cntry.;
   define type     / group 'Type of Grain';
   define kilotons / format=comma12.;
   footnote 'Measurements are in metric tons.';
run;

options byline;
title2;

ods rtf notoc_data;

proc tabulate data=Grain_Production format=comma12.;
   class year country type;
   var kilotons;
   table year,
         country*type,
         kilotons*sum=' ' / box=_page_ misstext='No data';
   format country $cntry.;
   footnote 'Measurements are in metric tons.';
run;

ods rtf toc_data;

proc print data=Grain_Production;
run;

ods rtf close;
ods html;

Program Description

Sort the data set Grain_Production. PROC SORT sorts the data, first by values of the variable Year, then by values of the variable Country, and finally by values of the variable Type.

proc sort data=Grain_Production;
   by year country type;
run;

Close the HTML destination so that no HTML output is produced.The HTML destination is open by default. The ODS HTML statement closes the HTML destination to conserve resources.

ods html close;

Create RTF output and create a new body file for each page of output.The ODS RTF statement opens the RTF destination and creates RTF output. The CONTENTS option creates a table of contents page that contains a Table of Contents field. All of the contents information that is embedded in the document is placed in the table of contents. However, the table of contents information is not embedded by default into your RTF file. The default is NOTOC_DATA. The embedded TOC data is not shown until you specify the option TOC_DATA.

ods rtf file='Grain.Rtf' contents toc_data;

Replace the default BY line with a new value in the BY line.The NOBYLINE option suppresses the default BY line variable. The #BYVAL parameter specification inserts the current value of the BY variable Year into the title.

options nobyline;
title 'Leading Grain-Producing Countries';
title2 'for #byval(year)';

Produce a report.This PROC REPORT step produces a report on grain production. Each BY group produces a page of output, and ODS creates a new body file for each BY group. The NOWINDOWS option instructs PROC REPORT to run without the REPORT window and to send its output to the open output destinations.

proc report data=Grain_Production nowindows;
   by year;
   column country type kilotons;
   define country  / group width=14 format=$cntry.;
   define type     / group 'Type of Grain';
   define kilotons / format=comma12.;
   footnote 'Measurements are in metric tons.';
run;

Restore the default BY line and clear the second TITLE statement.The BYLINE option restores the default BY line. The TITLE2 statement clears the second TITLE statement.

options byline;
title2;

Suppress the insertion of table of contents data into the RTF file.The NOTOC_DATA option instructs ODS not to insert the table of contents data into the RTF file. There will be no entry for the TABULATE procedure in the table of contents page.

ods rtf notoc_data;

The TABLE statement in the PROC TABULATE step uses three dimensions. Year defines pages, Country and Type define the rows, and Kilotons defines the columns. Therefore, PROC TABULATE explicitly produces one page of output for 1995 and one page for 1996, based on the years specified in the Grain_Production data set. ODS also starts a new body file for each page.

proc tabulate data=Grain_Production format=comma12.;
   class year country type;
   var kilotons;
   table year,
         country*type,
         kilotons*sum=' ' / box=_page_ misstext='No data';
   format country $cntry.;
   footnote 'Measurements are in metric tons.';
run;

Enable the insertion of table of contents data into the RTF file.The TOC_DATA option instructs ODS to insert the table of contents data into the RTF file. There will be an entry for the PRINT procedure in the table of contents page.

ods rtf toc_data;

Print the Grain_Production data set.

proc print data=Grain_Production;
run;

Close the RTF destination.The ODS RTF CLOSE statement closes the RTF destination and all the files that are associated with it. If you do not close the destination, you cannot view the files in a browser window.

ods rtf close;
ods html;

RTF Output

By default the table of contents is collapsed on the table of contents page. To expand the table of contents, right-click under the title in Microsoft Word and select Update Field from the selection list.

The table of contents contains only entries for PROC REPORT and PROC PRINT. By default the table of contents data is not embedded in the RTF document. To embed the table of contents data, specify the TOC_DATA option, which results in an entry for PROC REPORT. If you specify the NOTOC_DATA option before the TABULATE procedure, ODS does not insert contents information into the RTF document, and no entry for PROC TABULATE appears in the table of contents. If you specify the TOC_DATA option before the PRINT procedure, ODS inserts contents data, and an entry for PROC PRINT appears in the table of contents.

RTF Table of Contents for PROC REPORT and PROC PRINT

Example 2: Justifying Title and Footnotes When You Specify the BODYTITLE_AUX Option

Features:

ODS RTF statement action:: CLOSE

ODS RTF statement options::: BODYTITLE_AUX; FILE=

Other features:

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 preferred way to accomplish this functionality is to use the measured ODS TAGSETS.RTF statement. For more information, see ODS TAGSETS.RTF Statement .

Program

OPTIONS NODATE NOSTIMER LS=78 PS=60;

ods html 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 html;

Program Description

The following example shows how to left-justify, right-justify, and center titles and footnotes in the body of the output.

Specify the layout of the output.Instruct ODS not to print the date or time on the page and not to write any SAS statistics to the SAS log. Set the page size to 60 and the line size to 78.

OPTIONS NODATE NOSTIMER LS=78 PS=60;

Close the HTML destination so that no HTML output is producedThe HTML destination is open by default. The ODS HTML statement closes the HTML destination to conserve resources.

ods html close;

Create RTF output.The ODS RTF statement opens the RTF destination and creates RTF output. The BODYTITLE_AUX option tells SAS to place the titles and footnotes in the body of the output. In addition, this option places the titles and footnotes into cells.

ods rtf file="bodytitle_aux.rtf" bodytitle_aux;

Print the Sashelp.Class data set.

proc print data=sashelp.class;
run;

Add titles and footnotes to the output.Because you have specified the BODYTITLE_AUX option, ODS adds the titles and footnotes to the body of the output and places the text into cells. The J= style specifies the position of the title and footnote text on the page: left, center, or right.

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 html;

The following output shows how ODS places the titles and footnotes into the body of the output when you specify the BODYTITLE_AUX option. The text of the titles and footnotes are then placed into cells and tables. The JUSTIFY style element is then used to center, right-justify, or left-justify the title and footnote text.

Using the BODYTITLE_AUX Option to Place Titles and Footnotes

Example 3: RTF Interaction with the ORIENTATION= System Option

Features:

ODS RTF statement action:: CLOSE

ODS RTF statement option:: FILE=

Other features:

OPTIONS statement: ORIENTATION option

PROC PRINT

TITLE statement

When you want to change the page orientation for RTF, 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.

Program

OPTIONS NODATE NOSTIMER LS=78 PS=60;

ods html 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;
ods html;

Program Description

Specify the layout of the output.Instruct ODS not to print the date or time on the page and not to write any SAS statistics to the SAS log. Set the page size to 60 and the line size to 78.

OPTIONS NODATE NOSTIMER LS=78 PS=60;

Close the HTML destination so that no HTML output is produced.The HTML destination is open by default. The ODS HTML statement closes the HTML destination to conserve resources.

ods html close;

Add titles and footnotes to the output.Add a title for the overall file output and then titles that describe the changing orientation.

title 'Page Orientation';
title2 'Default';

Create RTF output.The ODS RTF statement opens the RTF destination and creates RTF output. In this case, the statement also triggers the change in the page orientation from the default.

ods rtf file="ChgOrientation.rtf";

Print the Sashelp.Class data set with only one observation.The page orientation is the default orientation, which is portrait.

proc print data=sashelp.class (obs=1);
run;

Add a title to change the page orientation in the output file.Add a title to change the page orientation to landscape.

title 'Page Orientation';
title2 'Landscape';

Specify the system option that will change the page orientation.

options orientation=landscape;

Trigger the page orientation change.This RTF statement triggers the change of the page orientation from protrait to landscape.

ods rtf;

Print the Sashelp.Class data set with only one observation.

proc print data=sashelp.class (obs=1);
run;

ods rtf close;
ods html;

RTF Output

The following shows the RTF output for the first page. The orientation is portrait, which is the default.

The following shows the RTF output for the second page. The orientation was changed to landscape.