ODS ESCAPECHAR Statement

Arguments

escape-character

specifies the special character that identifies the inline formatting symbol. The escape-character should be one of the following rarely used characters: @, ^, or \.

Note:   For RTF output, the ~, *, or # can also be used.  

With the ODS ESCAPECHAR statement, you can define an escape character for use with the inline formatting functions. These functions provide the ability to enhance and interpret text strings that are used by statements and variables. You can use these functions to modify text strings within table cells and title and footnotes.

Refer to Using the ODS ESCAPECHAR Functions for a complete list of the inline formatting functions and a detailed description.

Basic Inline Formatting

Inline formatting functions enable you to change styles in title and footnotes, text strings, and table cells. You can insert subscript or superscript into SAS output, underline text, justify text, insert page X of Y numbers into output, insert line feeds into long text strings, and insert destination-specific, raw text into HTML or RTF output.

Existing style elements and style attributes can be used with the STYLE functions. See the explanation of using styles in Inline Style Attributes and Nesting.

Inline Style Attributes and Nesting

You can use the ODS ESCAPECHAR statement and inline formatting syntax to justify text or change the color of titles, footnotes, and text. Other style attributes that are useful and that can add emphasis are font size, underlining, overlining, and strikethrough.

You can change the styles, too. For example, ODS PRINTER now supports two style settings for underlining. ODS PRINTER recognizes the SAS/GRAPH syntax UNDERLIN=1,2,3 for underlining text. However, this option does not change the thickness of the line. The new style element in SAS 9.2 is TextDecoration, which allows you to set the underline, overline, or strike-through styles on titles, footnotes, and text strings. Refer to ODS Style Elements and Style Attributes and Their Values for more details on these functions. See the global title and footnote style options in the TITLES and FOOTNOTE statements in SAS Language Reference: Dictionary.

Nested inline formatting is also supported. This feature enables you to set several style attributes for a string without resetting the previously used style. You can start a string with one set of style attributes and add to them later in the string. The first thing to notice is the new syntax:

^{style <style-element-name><[style-attribute-specification(s)]> formatted text}

The syntax begins with the function name STYLE. Next you can add a style element like Headerfixed, SystemTitle, and so on, as needed. Then you can add new attributes such as fontstyle, color, and so on, within brackets. The syntax ends with the text you want to format. The following code is a good example of nested formatting for RTF output:

title "test of ^{super ^{style [color=red] red ^{style [color=green] green} and
 ^{style [color=blue] blue }formatting }} and such" ;

In the example code, the ^{super<text> is invoked to start using the superscript function. Then the style function is used to add another style attribute, ^{style [color=red]<text> for your text.

To understand this nesting, think of a stack in which the first item that is placed on the stack is the last item to come off of the stack (FILO). The superscript function is pushed onto the stack first. Then the style function is used to push a red color onto the stack, resulting in a text string that is superscripted and red in color. Next, the green color is pushed onto the stack. Because the new style attribute is a color, the text changes to the new color. Continuing the string processing, this style attribute is then closed with a close bracket. After the green color is closed or popped off the stack, the red color becomes the active style attribute for the text. Next the blue color is pushed onto the stack, and the text string uses that color. After the blue color is closed, the red and superscript are closed. Now the stack is empty, so ODS uses the default style attributes to finish processing the text string.

Note:   Each output destination has limitations. When you use the Printer destination, you can only nest styles. The SUB and SUPER functions cannot be nested with the STYLE function. However, the HTML and RTF destinations can nest the STYLE function with the SUB and SUPER functions.  

Using Unicode Symbols

ODS now supports the ability to incorporate Unicode symbols such as Greek symbols into your output. The new inline formatting function is UNICODE, and the syntax is ^{unicode < value>). The syntax is similar to other inline formatting functions in that you can use a four-digit Unicode value that is predefined in a list. Another way to use the UNICODE function is to predefine a list that is stored as a tagset template. See Concepts: Markup Languages and the TEMPLATE Procedure for information on tagsets.

There is a new tagset template that contains a predefined list of common Greek symbols and their Unicode values. You can update this template as needed. The template increases the flexibility of the new inline style function. You can still use existing inline style functions, ^{dagger} and ^{sigma}. There are also other values in the template that you can use with the syntax ^ {<value>}.

To find out what symbols are available to you for Windows XP, you can click on Start -> Programs -> Accessories -> System Tools -> Character Map. The window that appears shows you the font and all of the symbols available for a given font. For the font displayed, you can highlight a symbol and see the Unicode value for that symbol. The Unicode value is displayed at the bottom of the Character Map window. You can use that Unicode value in the argument to the UNICODE function. For example, Unicode value 216b displays a Roman Numeral 12. The following code illustrates the use of this value:

title 'Roman Numeral twelve is ^{unicode 216b}';

The TAGSETS.CORE tagset contain a table of Unicode values and their mnemonics. To add or change a mnemonic, you must SOURCE the tagset, make the desired changes, and then run the modified tagset. The following code creates a file called core.tpl in the current directory that contains the TAGSETS.CORE tagset also:

proc template;     
 source tagsets.core / file="core.tpl";
run;

If you open the core.tpl file, you notice some text that appears similar to the following text:

set $unicodeMap["ALPHA" ] "03B1"; 
set $unicodeMap["BETA" ] "03B2"; 
set $unicodeMap["DAGGER" ] "2020";

To update the file with a new mnemonic and corresponding Unicode value, use the following syntax and add it to the file:

set $unicodeMap["<new function name>" ] "<unicode value";

Save the file and compile the modified tagset using PROC TEMPLATE as follows:

proc template;
     %inc "core.tpl";
run;

The modified tagset is stored in the first writable template store in your ODS path. See Concepts: Markup Languages and the TEMPLATE Procedure for more information on PROC TEMPLATE and using tagsets.

A new registry setting holds the Unicode font value. You can change this Unicode font value to any valid font that is installed on your computer and recognized by SAS. Refer to Changing SAS Registry Settings for ODS for specific details on how to change your font. Refer to Using TrueType Fonts with Universal Printers and SAS/GRAPH Devices in SAS 9.2 in SAS Language Reference: Concepts for information on all the new True Type fonts available in SAS version 9.2. This chapter contains information on how to install the TrueType fonts on your computer, too.

Interpreting Output Strings

ODS ESCAPECHAR controls the interpretation of output strings by ODS, except for the Listing, the Output, and the Document destinations. Whenever ODS destinations encounter the specified character in their output, regardless of the source of the output, ODS interprets the character as a special "escape" character that enables special formatting options. For example, the following program produces output in italics.

data italic;
   x='This font is ^{style[font_style=italic]italic}.';
   output;
   run;
ods listing close;
ods pdf file="italicFont.pdf";
ods escapechar='^';
proc print data=italic;
run;
ods _all_ close;

This section describes the use of the defined ODS ESCAPECHAR character value to perform inline formatting. After you define the ODS ESCAPECHAR character value, you can use the available inline formatting functions to change the style within cells, text, titles, and footnotes. You can use these functions to insert page numbers, line feeds, destination-specific raw data, additional spaces and formatting into your output.

Note:   For traditional RTF output, you must use Print Preview to view your output. Some of the formatting will not show up in the SAS results viewer window.  

The inline functions available are shown in Valid Functions That Can Be Used with ODS ESCAPECHAR.

where

escape-character

is the character defined using the ODS ESCAPECHAR statement.

{ }

is the inline formatting grouping characters

function-name

is the name of the inline formatting function.

Valid Functions That Can Be Used with ODS ESCAPECHAR

Function-name	Argument
DAGGER	none
DATE	none
DEST	output destination
LASTPAGE	none
LEADERS	string
NBSPACE	optional number
NEWLINE	optional number
PAGEOF	none
RAW	string
SIGMA	none
STYLE	style elements, style attributes, and style= option formats
SUB	arguments to subscript
SUPER	arguments to superscript
THISPAGE	none
TOCENTURYINDENT	length
TOCENTURYPAGE	none
UNICODE	unicode value

arg-1, arg-n

arguments that are given to the function. The number of arguments depends on the function. Some functions have no arguments.

CAUTION:

A space between the escape character and left bracket of the inline formatting style function will produce undesired results. Here is an example of how the code should look: "^{style [color=green] title green}";   

DAGGER Function

DATE Function

DEST Function

output-destination

is one of the ODS output destinations, RTF, PRINTER family, or HTML. This is the destination that will be used by the inline-formatting-function.

Tip:	You can specify more than one output-destination.

text

is text that you want to output. An example is:

^{dest [rtf html] ^{raw rawtext string} };

LASTPAGE Function

LEADERS Function

where

string

is the string that is repeated to fill the space between the leading text and the following text. This function is often used when generating Table of Contents. Example code is:

PostText = " ^{leaders .  }^{tocentrypage}

Tip:	You can use this function only with the PRINTER destination.

NBSPACE Function

where

number

is the number of spaces that you want to insert. A single space is inserted if you do not specify a number argument.

Default:	The NBSPACE value defaults to 1. A single space is inserted if a number is not specified.
Featured in:	Basic Inline Formatting Functions

NEWLINE Function

where

number

is the number of lines that you want to insert.

Default:	The newline value defaults to 1. A single line is inserted if you do not specify a number.
Featured in:	Basic Inline Formatting Functions

PAGEOF Function

RAW Function

string

is inserted directly without translation. This function allows you to insert control characters. This function works for markup destinations like HTML and RTF.

Tip:	Once this function has been turned on in a session, you cannot turn it off for that session.
Featured in:	Basic Inline Formatting Functions

SIGMA Function

STYLE Function

where

style-element-name

specifies the style element. For the STYLE function, you can use the same format that is available for the STYLE= option in all of the templates. For example:

^{style rowheader [color=red] my text};

or

^{style rowheader my text};

See:	ODS Style Elements

style-attribute-specification

specifies the style attribute. For the STYLE function, you can use the same format that is available for the STYLE= option in all the templates. For example:

^{style [color=red] my text};

See:	the list of Style Attributes and their values in Style Attributes and Their Values

formatted-text

specifies the text to which to apply the styles.

Note:   The style attributes or elements remain in effect until they are overridden by another style. A default style can also reset the style. The following code illustrates that the bolded text style is reset by the sub functions default style.

ods pdf text='^{style [font_weight=bold] BOLDED} ^{sub a} NOT bolde}'

Note:   You can nest inline styles. The following example illustrates nesting inline styles.

^{style [color=red] red  ^{style [fontsize=18pt] big}}

Refer to Inline Style Attributes and Nesting for an explanation of nesting styles.  

SUB Function

subscript-value

can be a numeric, alphanumeric, or a character value. This value is written below and immediately to one side of another character.

Restriction:	Microsoft Word honors only one level of subscript for RTF, TAGSETS RTF, and PRINTER.
Restriction:	The PRINTER destination does not recognize nesting of the SUB function. The subscript-value must immediately follow the SUB function.
Featured in:	Basic Inline Formatting Functions

SUPER Function

where

superscript-value

can be a numeric, alphanumeric, or a character value. This value is written above and immediately to one side of another character.

Restriction:	Microsoft Word only honors one level of subscript for RTF, TAGSETS.RTF, and PRINTER.
Restriction:	Nesting of the SUPER function is not recognized by the PRINTER destination. The subscript-value must immediately follow the SUPER function.
Featured in:	Basic Inline Formatting Functions

THISPAGE Function

TOCENTRYINDENT Function

where

len

is the amount to be indented per level. Example code is:

PreText = "^{tocentryindent 2em}"

Tip:	This function can be used only with the PRINTER destination.

TOCENTRYPAGE Function

PostText = " ^{leaders .  } ^{tocentrypage}"

UNICODE Function

where

unicode-value

can be an actual four-place hexadecimal Unicode value or one of the names listed in the tagsets.core template. For example, 03B2 is the Unicode value for the Alpha symbol. Refer to Using Unicode Symbols for details about Unicode values.

Tip:	Thorndale Duospace WT J is the default font used in the inline style Unicode function.
Featured in:	Basic Inline Formatting Functions

Example 1: Basic Inline Formatting Functions

ODS features:

ODS RTF statement: Action: CLOSE Options: FILE=

Other SAS features:

	OPTIONS statement
	PROC PRINT
	TITLE statement

Program Description

The following example highlights inline formatting functions that are supported for all destinations. It also shows how to nest inline formatting functions. In this example, RTF is the destination used.

Note:   To see all of the styles and colors displayed properly, use Print Preview to view the output.  

Program

options nodate nonumber;

ods listing close;

ods escapechar="^";

ods rtf file="rtffuncs.rtf";

title "Examples of Functions";

title2 'Example of ^{nbspace 3} Non-Breaking Spaces Function';

title3 'Example of ^{newline 2} Newline Function';

title4 'Example of ^{raw \cf12 RAW} RAW function';

title5 'Example of ^{unicode 03B1} UNICODE function';

title6 "Example ^{style [foreground=red] of ^{super ^{unicode ALPHA} ^{style [foreground=green] Nested}} Formatting} and Scoping";

title7 "Example of ^{super ^{style [foreground=red] red ^{style [foreground=green] green } and ^{style [foreground=blue] blue}}} formatting";

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

ods rtf close;

RTF Output

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