ODS ESCAPECHAR Statement

Defines a representative character to be used in output strings.

Valid in:	Anywhere
Category:	ODS: Output Control
Restrictions:	Affects all open destinations except for the LISTING destination. SAS/GRAPH does not support inline formatting.

Syntax

Details

Basic Inline Formatting

Inline Style Attributes and Nesting

Using Unicode Symbols

Inline Formatting with the PUT Statement

Inline Formatting with ODS Statistical Graphics

Interpreting Inline Formatting Output Strings

Using the ODS ESCAPECHAR Functions

Example

Syntax

ODS ESCAPECHAR= 'escape-character';

Required Argument

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

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.

For a complete list of the inline formatting functions and a detailed description for each, see Using the ODS ESCAPECHAR Functions.

Notes:For RTF output, the ~, *, or # can also be used. The \ is a special RTF character. Therefore, it is recommended that you use an escape character other than \ for RTF output.

There is no default value for the escape character, but you can use the special escape sequence (*ESC*) in the same way as an escape character. The special escape sequence (*ESC*) cannot be used in nested functions.

Details

Basic Inline Formatting

Inline formatting functions enable you to change styles in titles and footnotes, text strings, and table cells. For example, you can perform the following formatting functions.

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
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 styled or attributes that are useful and that can add emphasis are font size, underlining, overlining, and strikethrough.

You can also change the styles. 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. Other style attributes that are useful and that can add emphasis are font size, underlining, overlining, and strikethrough. See the section on style attributes and style attribute values in Detailed Information for All Style Attributes for more details about these style attributes. See the global title style options in TEMPLATE Procedure: Creating a Style Template. See the global footnote style options in FOOTNOTE Statement in SAS Statements: Reference.

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. Nested inline formatting has the following 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 such as Headerfixed or SystemTitle, as needed. Then you can add new attributes such as FONTSTYLE= or COLOR=, within brackets. The syntax ends with the text that you want to format. The following code is an 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.

Note: For information of style elements seeODS Style Elements.

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. See Concepts: Markup Languages and the TEMPLATE Procedure for information about tagsets.

There is a new tagset 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}.

To find out what symbols are available to you for Windows XP, you can select 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 Base.Template.Tagsets tagset contains 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 Base.Template.Tagsets tagset also:

proc template;
 source base.template.tagset. / 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 about 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. For specific details about how to change your font, see Changing SAS Registry Settings for ODS. For information about all the new True Type fonts available in SAS 9.2, see Using Fonts with Universal Printers and SAS/GRAPH Devices in SAS Language Reference: Concepts. This chapter contains information about how to install the TrueType fonts on your computer, too.

Inline Formatting with the PUT Statement

Inline formatting information that is used in the PUT statement is counted as printed space that is needed for the ODS LISTING output destination. Therefore, the LINESIZE= system option might need to be set to prevent wrapping of the output. For example, the inline formatting information shown in the following code defines the font size, font face, and font weight for the 'AAA' and 'BBB' values.

ods escapechar="^";
ods html file='file.html';
ods pdf file='file.pdf';
ods rtf file='file.rtf';
data _null_;
 file print;
put @1 '^{style [fontsize=8pt] ^{style [fontface=courier]
    ^{style [fontweight=bold]}}}'  'AAA';
put +5 '^{style [fontsize=8pt]  ^{stylefontface=courier]
    ^{style [fontweight=bold]}}}' 'BBB';
run;
ods _all_ close;

The line size needed for printed output is three characters. However the inline formatting information is also counted as part of the line size, even though that count only affects the appearance of the output. This increased line size can cause the text to wrap if it exceeds the current value of the LINESIZE= system option.

To prevent wrapping in the ODS LISTING output, increase the value of the LINESIZE= system option or decrease the font size.

Inline Formatting with ODS Statistical Graphics

ODS Statistical Graphics include template-based procedures (SGPLOT, SGPANEL, and SGSCATTER) and some statements that support ODS ESCAPECHAR in conjunction with the UNICODE, SUB, and SUP inline formatting functions. For information about how to use these functions with ODS Statistical Graphics, see SAS ODS Graphics: Procedures Guide and SAS Graph Template Language: User's Guide.

Interpreting Inline Formatting 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[fontstyle=italic]italic}.';
   output;
   run;
ods pdf file="italicFont.pdf";
ods escapechar='^';
proc print data=italic;
run;
ods _all_ close;

Using the ODS ESCAPECHAR Functions

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. Here is the syntax for the ODS ESCAPECHAR functions:

escape-character{function-name <<arg-1 <arg-2<arg-n>>>> }

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

escape-character: is the character defined using the ODS ESCAPECHAR statement.

{ }: enclose the inline formatting grouping characters.

arg-1, arg-n: are arguments that are given to the function. The number of arguments depends on the function. Some functions have no arguments.

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
TOCENTRYINDENT	Length
TOCENTRYPAGE	None
UNICODE	Unicode value

DAGGER Function: ^{DAGGER}

produces the Greek dagger sign.

Tip:It is preferable to use the UNICODE function to generate a dagger sign.

See:Basic Inline Formatting Functions

DATE Function: ^{DATE}

inserts the RTF to express the date.

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

DEST Function

^{DEST <[output-destination]> text

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 write to the output. An example is:

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

LASTPAGE Function: ^{LASTPAGE}

inserts the total number of pages.

Tips:This function works with the PRINTER, RTF, and TAGSETS. RTF destinations.

You must use Print Preview to view the resolved LASTPAGE function output that is generated by the TAGSETS.RTF destination.

LEADERS Function

^{LEADERS <string>}

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 a table of contents. Example code is:

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

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

NBSPACE Function

^{NBSPACE <number>}

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.

See:Basic Inline Formatting Functions

NEWLINE Function

^{NEWLINE <number>}

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.

See:Basic Inline Formatting Functions

PAGEOF Function: ^{PAGEOF}

inserts RTF syntax to express all the controls for Page X of Y.

Tips:You can use the PAGEOF function in the TITLE and FOOTNOTE statements. However, if the BODYTITLE option is also specified with the ODS RTF statement, the titles and footnotes are removed from the header and footer sections of the RTF file. As a result, the "page of" information is not written as expected. If the desired location of the page numbering is in the title or the footnote, remove the BODYTITLE option.

When the \ character is specified as the ODS ESCAPECHAR character, the PAGEOF function will not be interpreted properly for the TAGSETS.RTF destination. Instead, specify a different escape character.

You can use the PAGEOF function only with the RTF and TAGSETS. RTF destinations. You must use Print Preview to view the resolved PAGEOF function output that is generated by the TAGSETS.RTF destination.

RAW Function

^{RAW <string>}

string: is inserted directly without translation. This function enables you to insert control characters. This function works for markup destinations such as HTML and RTF.

Restriction:The RAW function does not work with PDF or Windows drivers.

Tips:After this function has been turned on in a session, you cannot turn it off for that session.

The \ is a special RTF character. The { and } are special function characters. When you use these special characters with the RAW function, ODS might generate unexpected output.

See:Basic Inline Formatting Functions

SIGMA Function: ^{SIGMA}

generates the Greek SIGMA sign σ.

Tip:The preferable way to produce a SIGMA sign is to use the UNICODE function.

See:Basic Inline Formatting Functions

STYLE Function

^{STYLE <style-element-name><[style attribute-specification]> formatted text}

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

^{style rowheader my text};

Tip:

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 Detailed Information for All Style Attributes.

formatted-text: specifies the text to which to apply the styles.

Notes: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
                                       [fontweight=bold] BOLDED} ^{sub a} NOT bolded}'

You can nest inline styles. The following example illustrates nesting inline styles. For an explanation of nesting styles, see Inline Style Attributes and Nesting.

SUB Function

^{SUB <subscript-character>}

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

Restrictions:Microsoft Word honors only one level of subscript for RTF and TAGSETS.RTF.

The PRINTER destination does not recognize nesting of the SUB function. The subscript-value must immediately follow the SUB function.

See:Basic Inline Formatting Functions

SUPER Function

^{SUPER <superscript-value>}

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

Restrictions:Microsoft Word only honors one level of subscript for RTF and TAGSETS.RTF.

Nesting of the SUPER function is not recognized by the PRINTER destination. The subscript-value must immediately follow the SUPER function.

See:Basic Inline Formatting Functions

THISPAGE Function: ^{THISPAGE}

inserts the current page number.

Tips:This function can be used only with the PRINTER, RTF, and TAGSETS.RTF destinations.

You must use Print Preview to view the resolved THISPAGE function output that is generated by the TAGSETS.RTF destination.

TOCENTRYINDENT Function

^{TOCENTRYINDENT <len>}

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

^{TOCENTRYPAGE}

is the page number of the current TOC entry. Example code is:

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

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

UNICODE Function < | > }

^{UNICODE <unicode-value | 'unicode-value'X>}

unicode-value: can be an actual four-place hexadecimal Unicode value or one of the names listed in the Base.Template.Tagsets template. For example, 03B2 is the Unicode value for the Alpha symbol. For details about Unicode values, see Using Unicode Symbols.

Tip:Thorndale Duospace WT J is the default font used in the inline style Unicode function for the PDF destination.

See:Basic Inline Formatting Functions

'unicode-value'X: is syntax used with STAT/GRAPH. A hexadecimal value is enclosed in single or double quotes followed by an X. The X specifies that the value in quotes is a hexadecimal value. This quoted value must be an actual four-place hexadecimal Unicode value or one of the names listed in the Base.Template.Tagsets template. For example, 03B2 is the Unicode value for the Alpha symbol. For details about Unicode values, see Using Unicode Symbols.

Tips:Thorndale Duospace WT J is the default font used in the inline style Unicode function for the PDF destination.

The unicode-value can be enclosed with single or double quotes.

Example: Basic Inline Formatting Functions

Features:

ODS RTF statement::: Actions: CLOSE; Options: FILE=

Other features:

OPTIONS statement

PROC PRINT

TITLE statement

Details

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

ods escapechar="^";

ods rtf file="rtfInlinFuncs.rtf";
ods pdf file="pdfInlinFuncs.pdf";


title "Examples of Inline Formatting 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, Alpha ^{super ^{unicode ALPHA}
       ^{style [foreground=green] Nested}} Formatting} and Scoping";

title7 "Example of SUB, ^{sub
         ^{style [foreground=red] red
         ^{style [foreground=green] green } and
         ^{style [foreground=blue] blue styles }}} and SIGMA Functions";

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

ods _all_ close;

Program Description

Turn off the Date and Page number. The NODATE option turns off the output of the date and time. The NONUMBER option tells SAS not to print the page number on the first title line of each page of output.

options nodate nonumber;

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;

Set the escape character for inline formatting.

ods escapechar="^";

Create RTF and PDF output. The ODS RTF statement opens the RTF destination and creates RTF output. The ODS PDF statement opens the PDF destination and creates PDF output.

ods rtf file="rtfInlinFuncs.rtf";
ods pdf file="pdfInlinFuncs.pdf";

Set the TITLE statement. This TITLE statement provides the topic title for the RTF output.


title "Examples of Inline Formatting Functions";

Show the NBSPACE function. The non-breaking spaces function, NBSPACE, puts the number of spaces that you specified in the output of the title.

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

Show the NEWLINE function. The NEWLINE function puts the specified number of additional line feeds in the output of the title.

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

Show the RAW function. The RAW function puts the escaped text that you specified into the file exactly as it is shown. Each ODS destination has special instructions that are recognized. In the following code, \cf12 is an instruction that the RTF destination recognizes and can display. The PDF destination does not recognize this instruction.

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

Show the UNICODE function. This TITLE statement shows how the UNICODE function works.

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

Show the STYLE function and the nesting of functions.This TITLE statement shows the STYLE function using style attribute FOREGROUND=. This example also shows the nesting of the STYLE, SUPER, and UNICODE functions.

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

Show the SUPER function and the nesting of functions. This TITLE statement shows the STYLE function using style attribute FOREGROUND=. This example also shows the nesting of the STYLE, SUB, and SIGMA functions.

title7 "Example of SUB, ^{sub
         ^{style [foreground=red] red
         ^{style [foreground=green] green } and
         ^{style [foreground=blue] blue styles }}} and SIGMA Functions";

Print the data set.

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

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

ods _all_ close;

RTF Output

PDF Output

This output shows the basic inline formatting functions and how you can use them with the TITLE statement, starting with the non-breaking line function (NBREAK). The other functions used in the code and shown in the following output are NEWLINE, RAW, UNICODE, STYLE, SUPER, SUB, and SIGMA. Nesting functions are also demonstrated in this PDF output. Note that the SUB and SUPER functions are not honored when nested in the PDF destination. Notice that the SUPER function is not recognized in title6 because of where it is nested. The PDF destination does not recognize the SUB function properly because the subscript-value does not immediately follow the SUB function.

Also note that in title4, the PDF destination cannot display the special instruction provided in the RAW function. The \cf12 instruction is an RTF instruction.