ODS TAGSETS.RTF Statement

OPTIONS FORMCHAR="|----|+|---+=|-/\<>*"; 

Actions

The following table lists the actions that are available for the ODS RTF statement and for the ODS TAGSETS.RTF statement. For a complete description, see Actions in the ODS RTF Statement.

Options

The following table lists a subset of the options that traditional ODS RTF statement also supports. For a complete description of these options, see Options in the ODS RTF Statement.

Note:   The BODYTITLE and SAS DATE options are supported options for the traditional ODS RTF statement. However, they are not supported options for the ODS TAGSETS.RTF statement because their functionality is built into the ODS TAGSETS.RTF statement.  

The following table lists the options available exclusively for the ODS TAGSETS.RTF statement. You can use the ODS RTF options and the ODS TAGSETS.RTF options together.

OPTIONS (CONTENTS= | DOC= | SECT= | TABLES_OFF= |TOC_DATA= |TROWD= |TRHDR= | TROWHDRCELL= )

specifies ODS TAGSETS.RTF specific suboptions and a named value.

(CONTENTS= 'YES')

produces a table of contents (TOC) page for RTF documents that are opened in Microsoft Word. The table of contents page contains a Table of Contents field that puts all of the contents information that is embedded in the document into a table of contents. To display the captured TOC data, you must turn on the TOC_DATA option. To expand the table of contents right-click under the title in Microsoft Word and select Update Field from the selection list.

Note:   From Microsoft Word, you might need to right-click lower on the page to get the Update Field value to appear in the selection list.   

YES	adds a table of contents page to the top of the RTF file. This table of contents page is followed by a page break. Alias: ON

Requirement:	All values must be enclosed in quotation marks.
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. Select Tools  Options  Edit and then check Use CTRL + Click to follow hyperlink.
Tip:	The TOC_DATA option must be set to YES to capture TOC data. If you specify CONTENTS=YES, but you do not specify TOC_DATA, no Table of Contents data is captured. The error displayed on the Table of Contents page is "Error! No table of contents entries found".
See:	Suboption TOC_DATA for details on displaying the contents embedded in the document.
Featured in:	Creating a Table of Contents

(DOC='QUICK' | 'HELP' | 'SETTINGS')

provides information about the tagset.

QUICK

describes the options available for this tagset.

HELP

provides generic help and information with a quick reference.

SETTINGS

provides the current option settings.

Requirement:	All values must be enclosed in quotation marks.
Featured in:	Using the DOC Suboption to Get ODS TAGSETS.RTF Information

(SECT='rtf_control_string' | 'OFF' | 'NONE')

inserts RTF control words into the section data specifications.

rtf_control_string	specifies RTF control words used to format the section data.
OFF	turns off the usage of RTF control words for the section data and resets the rtf_control_string to null. Alias: NO
NONE	stops new RTF control words from being inserted into the file for the section data. ODS continues to use the section data information that was set before the use of NONE until it is reset.

Requirement:	All values must be enclosed in quotation marks.
Tip:	To reset the rtf_control_string, assign a different value or use the OFF or NO values.
See:	Rich Text Format (RTF) Specification, version 1.6 available on the MSDN home Web page for information on RTF control words. Simply search for the document.

(TABLES_OFF='style_elements' | 'STYLE_ELEMENTS' | 'OFF' )

determines whether tables will be used. A table can consist of one cell or many cells. SAS puts all of the text that you create into tables for RTF output. Use this suboption for tables that are text holders like titles, footnotes, and TEXT=. You should not use this suboption for tables produced by reporting procedures.

Note:   To view the gridlines of tables in Microsoft Word, select Show Gridlines from the Table drop-down menu.  

style_elements

specifies the style element for formatting. For example, the following statement turns off tables that use the USERTEXT style element. The text specified by the TEXT= option is not placed in the table..

ods tagsets.rtf options (Tables_OFF='usertext');
ods tagsets.rtf text="Text is not placed in a table");

STYLE_ELEMENTS

lists the output style elements in the SAS log.

OFF

turns the option off. Therefore, ODS places the information output next into the RTF file inside a table. This action is the default option.

Alias:

NO

Requirement:	You must enclose all values in quotation marks.
See:	General ODS Style Elements for information about style elements
Featured in:	Using the TABLES_OFF Suboption

(TOC_DATA ='ON' | 'OFF')

specifies whether to show the contents data in the RTF file.

OFF	instructs ODS not to display the table of contents data in the RTF file. Alias: NO
ON	instructs ODS to display the hidden text of the table of contents in the RTF file. Alias: YES

Requirement:	You must enclose all values in quotation marks.
Featured in:	Creating a Table of Contents

(TROWD='rtf_control_string' | ' OFF')

inserts raw RTF specifications directly into header descriptions of the table row.

rtf_control_string	specifies RTF control words and symbols.
OFF	RTF controls are no longer inserted. Alias: NO

Requirement:	You must enclose all values in quotation marks.
See:	Rich Text Format (RTF) Specification, version 1.6 available on the MSDN home Web page for information on RTF control words. Search for the RTF 1.6 document.
Featured in:	Column Heading Rotation Using the TRHDR, TROWHDRCELL, and TROWD Options

(TRHDR='rtf_control_string' | 'OFF')

inserts raw tablerow RTF specifications directly into the header description of the table row.

rtf_control_string	specifies Microsoft RTF control words or symbols.
OFF	RTF controls are no longer inserted. Alias: NO

Requirement:	You must enclose all values in quotation marks.
See:	Rich Text Format (RTF) Specification, version 1.6 available on the MSDN home Web page for information on RTF control words. Search for the RTF 1.6 document.
Featured in:	Column Heading Rotation Using the TRHDR, TROWHDRCELL, and TROWD Options

(TROWHDRCELL='text_string' | 'OFF')

inserts raw text into the table row cells. If the RTF Reader does not recognize this text_string, it applies the raw text to the location where the RTF is being written in the documentation. Otherwise, the RTF Reader interprets the text_string as RTF control words.

text_string	any text specified.
OFF	inserts a null string. Text is no longer inserted. Alias: NO

Requirement:	You must enclose all values in quotation marks.
See:	Rich Text Format (RTF) Specification, version 1.6 available on the MSDN home Web page for information on RTF control words. Search for the RTF 1.6 document.
Featured in:	Column Heading Rotation Using the TRHDR, TROWHDRCELL, and TROWD Options

Requirement:

The OPTION suboption's must be enclosed in parentheses.

PAGEPANELS= n | NONE

specifies the number of panels permitted per page before ODS inserts a page break.

n

specifies a positive integer.

Default:	0
Tip:	Setting the value to 0 resets the action to the default action.

NONE

specifies that paneling will be handled the way that it has always been handled by traditional ODS RTF. That is, all of the first panel is written, then all of the second panel, and so on, until all of the table information is written.

Default:

If you do not specify paneling, ODS tries to fit the full set of panels on a single page. ODS measures the width of the text and tables (horizontal measurement) and determines what the column widths should be. ODS then divides the page into panels if it is too wide to fit on a page. ODS always determines the column widths and determines whether panels are required. When there are multiple panels, ODS attempts to place a reasonable number of rows in each panel.

Featured in:

Paneling Using the TABLEROWS and PAGEPANELS Options

TABLEROWS= n

specifies the number of rows in each table before ODS inserts a page break. If the table is narrow enough to fit on a page, n lines will be written to the table before a page break. If the table is too wide for a page, the page is broken into panels. In each panel, n rows will be written. When all the panels for n rows have been written, a page break is inserted before the next group of panels is written.

Note:   Page breaks are not forced between panels.  

n

is a positive integer.

Alias:	0 | NONE
Default:	Allow SAS to determine the number of rows per table.
Tip:	0 or NONE returns to the default, which allows SAS to determine the number of rows per table.
Featured in:	Paneling Using the TABLEROWS and PAGEPANELS Options

UNIFORM

ensures uniformity from page to page within a single table that requires multiple pages. When the UNIFORM option is in effect, ODS reads the entire table before it starts to print it and determines the column widths that are necessary to accommodate all of the data. ODS applies these column widths to all pages of a multiple page table.

Note:   With BY-group processing, SAS writes the results of each BY group to a separate table, so the output might not be uniform across BY groups.  

Default:	If you do not specify the UNIFORM option, ODS prints a table one page at a time. This approach ensures that SAS does not run out of memory while it processes very large tables. However, column widths might vary from one page to the next.
Tip:	After this option is turned on, you cannot turn it off for that SAS session.
Tip:	The UNIFORM option can cause SAS to run out of memory if you are printing a very large table. If this happens, you can specify the width of each of the columns in the table. Then print the table one page at a time. To do so, you must edit the table definition that you use. For more information, see What You Can Do With a Table Template.
Featured in:	Repeating Headers Using the UNIFORM Option

Opening and Closing the ODS TAGSETS.RTF Destination

You can modify and open an RTF destination with many ODS TAGSETS.RTF options. However, the FILE= option automatically closes the open destination that is referred to by the ODS TAGSETS.RTF statement. The option also closes any files associated with it and opens a new instance of the destination. If you use one of the ODS TAGSETS.RTF options, you should close the destination yourself.

Understanding How Traditional 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 them.

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. Your tables can remain intact on one page, or can have logical breaks where you specify.

Microsoft Word needs to know the widths of table columns, and it cannot adjust tables if they are too wide for the page. However, ODS measures the width of the text and tables (horizontal measurement). Therefore, all 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 will display consistently even after you modify your RTF file.

Note:   The creation of complex tables that contain a large number of observations can reduce system efficiencies and increase processing time.  

ODS Measured RTF Versus Traditional ODS RTF

The ODS RTF tagset (ODS TAGSETS.RTF), which is also referred to as the measured tagset, is new for SAS 9.2. 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. Traditional ODS RTF relies on Microsoft Word to make implicit page breaks for tables that are too long to fit on a single page. Traditional RTF also places titles and footnotes in the RTF instructions that enable Microsoft Word to apply them to pages as they are needed. In contrast, the RTF tagset enables SAS to place titles and footnotes into the body of the document so that it is outside of the control of Microsoft Word. Therefore, SAS becomes responsible for the implicit page breaks.

RTF Tagset Features

The new "measured" RTF tagset does the following:

• controls page breaks on very large tables

• supports RTF readers other than Microsoft Word

• controls titles, footnotes, and other page elements

Controlling Page Breaks in Long Tables

Multiple-page tables can be a problem for ODS RTF. Like the ODS PRINTER destinations, SAS determines where to wrap a wide table. But for a long table, the entire table is loaded into memory before being rendered. When tables become longer than a physical page, Microsoft Word determines the page break. Microsoft word re-creates the column heading information in the table and applies titles and footnotes as needed. If a table is later edited in Microsoft Word, the information remains valid.

Unfortunately, a lot of information is associated with each cell of a table. No matter how much memory is added to the system, it is possible to create a table that can exceed it. Furthermore, an exhausted memory condition cannot be anticipated because it varies with the machine setup and with the table that you are creating.

However, with the ODS RTF tagset, SAS determines where to break the page and puts the titles and footnotes in the body of the document. When the table is broken into pages and SAS controls the page breaks, approximately a page of data is needed in memory at any one time. Therefore, a much smaller memory footprint is consumed and extremely large tables can be created. The ODS RTF tagset accommodates users who need large tables and users who want the old style RTF behavior. Both RTF implementations can be supported simultaneously.

Supporting RTF Readers Other than Word

Before SAS version 9.2, the traditional RTF architecture supported only the Microsoft Word RTF. The problem with supporting multiple readers is that RTF readers interpret the RTF specification in different ways. Now with the RTF tagset, you can enable subtle changes in one reader without impacting another RTF reader.

Controlling Titles, Footnotes, and Other Page Elements

Measured RTF uses a tagset that places the titles and footnotes on the page as tables instead of as RTF control words that are passed to Microsoft Word. With traditional RTF, the titles and footnotes are placed in the RTF header and footer information unless you specify the BODYTITLE option. Because the headers and footers are automatically placed in the body of the document with measured RTF, the TAGSET.RTF destination does not need the BODYTITLE option.

Measured RTF and Graphics

Measured RTF produces output in rich text format, which supports three formats for graphics that MS Word can read.

When you do not specify a target device, the default target is PNG. You can also use the ACTIVEX, ACTXIMG, JAVAIMG graphics drivers to generate graphics in your measured 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 TAGSET.RTF statement, the JAVAIMG driver is used.  

Note:   You cannot use UTF-8 encoding with the ACTIVEX device in RTF. When UTF-8 encoding is used, the ACTXIMG (activex image) device is used.   

Example 1: Creating a Table of Contents

ODS features:

ODS TAGSETS.RTF statement: Action: CLOSE Options: CONTENTS TOC_DATA

Other SAS features:

	OPTIONS statement
	PROC FORMAT
	PROC PRINT
	PROC SORT
	PROC REPORT
	PROC TABULATE

Data set:

Grain_Production.

Format:

$CNTRY..

Program Description

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 listing close;

ods tagsets.rtf file='Grain_Tagset.rtf' options(contents='yes' toc_data='yes');

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 tagsets.rtf options(toc_data='no');

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 tagsets.rtf options(toc_data='yes');

proc print data=Grain_Production; run;

ods tagsets.rtf close;

RTF Output

Example 2: Using the DOC Suboption to Get ODS TAGSETS.RTF Information

ODS features:

ODS TAGSETS.RTF statement: Action: CLOSE Options: OPTIONS (DOC="HELP") FILE=

Other SAS features:

PROC PRINT

Program Description

The following example prints to the SAS log the OPTIONS suboptions and a description of each available suboption.

Program

ods tagsets.rtf file='Help.rtf' options (doc="help");

proc print data=Sashelp.Class; run;

ods _all_ close;

RTF Output

Example 3: Using the TABLES_OFF Suboption

ODS features:

ODS TAGSETS.RTF statement: Action: CLOSE Options: OPTIONS (TABLES_OFF="OFF") (TABLES_OFF="USERTEXT") (TABLES_OFF="STYLE_ELEMENTS") FILE= TEXT=

Other SAS features:

PROC PRINT

Program Description

The following example turns on and off the tables in RTF output and applies the style element specified by the TABLES_OFF suboption.

Program

ods tagsets.rtf file="tablesOff.rtf" options(TABLES_OFF='STYLE_ELEMENTS'); proc print data=sashelp.class(obs=1) ; run; ods tagsets.rtf text="TEXT is placed in a table by default" ;

ods tagsets.rtf options(TABLES_OFF='usertext' ); ods tagsets.rtf text="TEXT is not placed in a table (table is removed when style element is specified)" ;

ods tagsets.rtf options(TABLES_OFF='off' ); ods tagsets.rtf text="TEXT is placed in a table (returned to default when tables_off is set to off)" ;

ods _all_ close;

RTF Output

Example 4: Column Heading Rotation Using the TRHDR, TROWHDRCELL, and TROWD Options

ODS features:

ODS TAGSETS.RTF statement: Action: CLOSE Options: OPTIONS TRHDR= TROWHDRCELL= TROWD=

Other SAS features:

	PROC PRINT
	OPTIONS statement

Program Description

The following example creates an RTF file in which the headers and contents of the row and column headings are rotated within the table.

Program

options orientation=landscape nodate nonumber;

ods listing close;

ods tagsets.rtf file='Mrotate.rtf' OPTIONS (TRHDR="\trrh750" TROWHDRCELL="\cltxbtlr" TROWD="\rtlrow");

proc print data=Sashelp.Class(obs=5); run;

ods _all_ close;

RTF Output

Example 5: Paneling Using the TABLEROWS and PAGEPANELS Options

ODS features:

ODS TAGSETS.RTF statement: Action: CLOSE Options: TABLEROWS PAGEPANELS

Other SAS features:

	OPTIONS statement
	PROC PRINT
	DATA statement

Program Description

The following program provides various examples of how ODS creates panels when a table is wider than a page and presents some different choices for controlling the paneling.

Program

option nodate nonumber;

ods listing close;

ods tagsets.rtf file="Panel.rtf";

data temp; array values val1-val50; do j = 1 to 6; do i = 1 to dim(values); values(i) = i; end; output; end; run;

ods tagsets.rtf; title "Default Paneling"; proc print data=Temp; run;

ods tagsets.rtf tablerows=5 pagepanels=4; title 'Paneling with TABLEROWS=5 and PAGEPANELS=4'; proc print data=Temp; run;

ods tagsets.rtf close; ods listing;

RTF Output with Default Page Paneling

RTF Output with Options PAGEPANELS and TABLEROWS

Example 6: Repeating Headers Using the UNIFORM Option

ODS features:

	ODS TAGSETS.RTF statement: Action: CLOSE Options: UNIFORM FILE=
	ODS RTF statement

Other SAS features:

	OPTIONS statement
	PROC FORMAT
	PROC TABULATE
	DATA statement

Program Description

The following example creates a multi-page table that is uniform across several pages. The row and column heading labels are also carried over to each page.

Program

options orientation=landscape; ods rtf file="RtfTab.rtf";

ods tagsets.rtf file="MrtfTab.rtf" uniform;

ods listing close;

data one; do a=1 to 2; do b=1 to 2; do c=1 to 3; do d=1 to 3; do e=1 to 5; output; end; end; end; end; end; run;

proc format; value cars 1='DATSUN 200SX' 2='PONTIAC FIERO'; value colors 1='RED' 2='LIGHT BLUE' 3='YELLOW' 4='GREEN' 5='BROWN'; value luxury 1='ALL THE WAY' 2='STANDARD OPTIONS' 3='STRIPPED DOWN'; value opts 1='POWER STEERING' 2='SUN ROOF' 3='AUTOMATIC' 4='T-TOP' 5='HATCHBACK' 6='FUEL-INJECTION' 7='HUBCAPS' 8='AM/FM STEREO' 9='FLOOR MATS' 10='CASSETTE PLAYER'; value perform 1='VERY SLOW' 2='SLOW' 3='AVERAGE' 4='FAST' 5='VERY FAST'; run;

data two (keep=model color luxury options perform); length model color luxury options perform $ 20; set one; model=put(a,cars.); color=put(b,colors.); luxury=put(c,luxury.); options=put(d,opts.); perform=put(e,perform.); run;

title2 'My Favorite Cars'; title3 '(large data set)';

proc tabulate data=two order=data ; class model color luxury options perform; table model*color*luxury*options*perform,n / indent=4 condense; label model='MODEL CAR' color='COLOR OF CAR' luxury='CONDITION OF CAR' perform='SPEED'; keylabel n='NUMBER'; run;

ods _all_ close;

Measured RTF Output

Traditional RTF Output

Copyright © 2008 by SAS Institute Inc., Cary, NC, USA. All rights reserved.