Base SAS

Preproduction RTF Features in SAS 9.1

Be aware that any preproduction features can change in later releases. Always check the current Output Delivery System User's Guide for the most up-to-date information about production supported features.

New for SAS 9.2: NOTOC_DATA and TOC_DATA options are production for SAS 9.2, and the default is now NOTOC_DATA. The section is highlighted by a yellow background.

Preproduction features often fall by the wayside in documentation. The developers would like to have feedback before features go production, but that can't happen if no one knows about them.

Please consider all these features in SAS 9.1 to be under construction. Some are back-door fixes that directly modify the RTF output, and they might never become production.

When using these preproduction options, the current RTF specification may come in handy: Rich Text Format (RTF) Specification, version 1.6.

Border Color, Width, and Style Can Vary on Each Side

The border can be different on top, botton, left, and right. An example is better than an explanation. This is applied via PROC TEMPLATE:

   proc template;
      define style test;
      parent=styles.default;
      style table from table /
            cellspacing=0 rules=groups
            bordertopwidth=7 bordertopcolor=green bordertopstyle=dashed
            borderbottomwidth=9 borderbottomcolor=red borderbottomstyle=double
            borderleftwidth=12 borderleftcolor=blue borderleftstyle=dotted
            borderrightwidth=3 borderrightcolor=cyan borderrightstyle=groove
            frame=box;
      end;
   run;

BORDERSTYLE= Attribute

The single solid border can be one of

The list was determined by the current CSS standards for HTML. Each RTF viewer will support the style as best it can. When viewed in Word, the values INSET and OUTSET seem to produce the same effect as SOLID.

It is set in the same fashion as the BORDERWIDTH= attribute:

   proc template;
      define style test;
      parent=styles.default;
      style table from table /
            cellspacing=0 rules=groups frame=box
            borderwidth=7 bordercolor=green borderstyle=dashed  ;
      end;
   run;

CONTENTS Option

In Word, you can create a table of contents (TOC) by several methods. SAS 9.1 directly supports one of these methods. ODS RTF can embed, or hide, TOC data in the file. In ODS RTF, when you open a file with the command

   ods rtf file="test.rtf" contents;

a first page is generated that has the title on it but is otherwise empty. The TOC information is embedded in the file.

To create the TOC, you must update an RTF instruction field in the following way: (Try it yourself with an example output file.) With your cursor in the body of the page, select your right mouse button to display a pop-up menu. Select Update Field from the menu, which causes Word to scan the document and build a TOC on that page, below the title. If more ODS RTF output is later appended, you can update the TOC in the same manner. Do not specify CONTENTS for the added output.

To create a different kind of TOC in post-processing, see information elsewhere in this document about WORDSTYLE and PREPAGE.

See also the information about NOTOC_DATA and TOC_DATA options.

HEADERRULESTYLE= Option

This option will probably disappear in the future. It enables RTF to use the new BORDERSTYLE attribute to apply one kind of rule between the header and body of a table and another kind of rule on the outer borders of the table. Cell-specific borders require changes that were too invasive for the SAS 9.1 time span.

The following example code removes the borders from a table and places a double border between the header part of the table and its body.

   proc template;
      define style test;
      parent=styles.default;
      style table from table /
            cellspacing=0 rules=groups frame=void;
      end;
   run;

   ods rtf file="test.rtf"
      headerrulestyle="double";

   proc print data=sashelp.class;
   run;

   proc datasets ;
   run;

   quit;
   ods rtf close;

To remove the option, specify an empty string:

   ods rtf  headerrulestyle=" ";

HEADERY= and FOOTERY= Options

We have had requests for control over the options that determine the locations of the header and footer information. There are a number of considerations and computations that determine the value. If you are a savvy user, specify the locations like this:

   ods rtf file="test.rtf" headery=320 footery=1100 ;

There is no checking on the validity of these values. If they are specified, they are used. The values are in twips.

To remove the use of the options, issue

   ods rtf  headery=0 footery=0;

NOTOC_DATA and TOC_DATA Options

The NOTOC_DATA and TOC_DATA options can stop and start the inclusion of table of contents information.

In SAS 9.2, the two options are production, and NOTOC_DATA is the default. In SAS 9.1.3, the two options are preproduction, and TOC_DATA is the default.

Issuing

   ods rtf notoc_data;

stops the data from being written to the file, and

   ods rtf toc_data;

starts it back up again. TOC_DATA is the default, so you don't need to issue it unless you have issued NOTOC_DATA and want to restart the TOC information.

The data is added as hidden text, and it is not displayed until you create the TOC with the Update Field command as explained above in the CONTENTS section. You can tell Word to show hidden text, which you do as follows: Select the Tools menu and chose Options. Under the View tab, in the Formatting Marks section, select the radio box for Hidden Text. However, you probably do not want to show hidden text, because the TOC information is free-floating text that appears in the closest cell when it is visible. It is not attractive.

PageNo Style

Many styles are used throughout the RTF ODA. In SAS 9.1, we honor some changes in the PageNo style. This allows the use of pre- and posttext in the style to globally change the appearance of the page number string.

This string must occur in the section information in order to occur at the top of each page. In addition to changing font and color, you can change the text to "Page x of y" or some other language equivalent.

   proc template;
      define style mystyle;
      parent=styles.default;
      Replace PageNo from TitlesAndFooters  /
              font = fonts("strongFont")
              cellpadding = 0 cellspacing = 0
              just=r vjust=t
              posttext= " of  (*ESC*){lastpage}" ;
      ;
      end;
   run;

Notice the use of (*ESC*), which is a universal ODS escape character so that you do not have to specify ESCAPECHAR before using the style.

PREPAGE= Option

To understand the PREPAGE= option, compare it to the TEXT= option, which is useful for embedding text in a document. The TEXT= option is limited to inserting the text after the table for the page, except on the first usage. (For an illustration of TEXT=, see the RTF output that results from some SAS example code.)

The PREPAGE= option inserts its text at the top of the table, after the titles. As with TEXT=, the text appears only once. The PREPAGE= option can also insert raw text instructions into the document in other locations. For an example, see the explanation elsewhere in this document of the WORDSTYLE option.

SASDATE Option

This option causes the standard SAS date to be inserted in the document in place of the default RTF specification that inserts the printing date and time. For example, compare the output from code that uses SASDATE:

   ods rtf file="sasdate.rtf" sasdate;
   proc print data=sashelp.class; run;
   ods rtf close ;

to output with the default date and time:

   ods rtf file="rtfdate.rtf";
   proc print data=sashelp.class; run;
   ods rtf close;

The RTF output destination was originally conceived as a format that would receive editing before final printing. With that in mind, the page and date information were implemented with RTF specifications that would generate the information for the document just before printing.

SUGI users requested an option that would use the date that the SAS System created the document rather than the date the RTF document was rendered by Word into a printed form. SASDATE is preproduction for SAS 9.0 and 9.1 because it has not been formally documented or tested.

SECTIONDATA= Option

This option takes a string and appends it to the section information. In RTF, it overwrites any previous instruction. There is no error checking for valid RTF syntax. The example code

   ods rtf file="test.rtf" ;

   ods rtf sectiondata="\sbknone" ;
      title " SECTIONDATA TEST ON " ;

   proc print data=sashelp.class ;
   run;

   proc print data=sashelp.class ;
   run;

   ods rtf sectiondata=" " ;
      title " SECTIONDATA TEST OFF " ;

   proc print data=sashelp.class ;
   run;

   proc print data=sashelp.class ;
   run;

   ods rtf close ;

places four columns on a page and removes all breaks associated with section data.

TROWDATA= Option

This option takes a string and appends it to the trow information. In RTF, it overwrites any previous instruction.

The TROW information is used by word to repeat the column headers across page breaks. It applies to all the data. Code like

   ods rtf file="test.rtf" trowdata="\rtlrow" ;
      title " TEST of TROWDATA ON" ;

   proc print data=sashelp.class ;
   run;

   ods rtf  trowdata=" " ;
      title " TEST of TROWDATA OFF" ;

   proc print data=sashelp.class ;
   run;

   ods rtf close;

makes the order of columns right-to-left rather than the default left-to-right. This is useful for Arabic and Hebrew displays of tables.

To cut the option off, specify

   ods rtf trowdata=" ";

WORDSTYLE= Option

Some Word styles are indirectly supported in ODS RTF output. You can use the Header style together with post-processing to create a custom TOC in your RTF output. (A more direct method is described elsewhere under the CONTENTS option.)

To enable a customized TOC, specify the WORDSTYLE= and PREPAGE= options. WORDSTYLE simply passes the specified text to the style section of an RTF document. PREPAGE= specifies the text for the TOC entry. Here is some example code:

   ods rtf file='test.rtf'  wordstyle="{\s1 Heading 1;}" ;

   ods escapechar='\';

   ods rtf prepage =  '\R/RTF"\s1 " TESTING 123';
   proc print data=sashelp.class;
   run;

   ods rtf prepage =  '\R/RTF"\s1 " TESTING 456';
   proc print data=sashelp.class;
   run;

   ods rtf close;

To create the TOC, open the output file in Word, and make one of the following choices from the Word menus:

Select Format->Frames->Table of Contents in Frame. This creates a TOC in a frame that is visible throughout the document.
Or select Insert->Reference->Index and Tables->Table of Contents->OK. This creates a traditional TOC. You can make many formatting choices in the Index and Tables dialog box before you select OK.

THIS PRELIMINARY DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. The Institute shall not be liable whatsoever for any damages arising out of the use of this documentation, including any direct, indirect, or consequential damages. The Institute reserves the right to alter or abandon use of this documentation at any time. In addition, the Institute will provide no support for the materials contained herein.

E-mail This Page

FOCUS AREAS