Dictionary of ODS Language Statements

ODS ESCAPECHAR Statement

Defines a representative character to be used in output strings.

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

Syntax
Required Arguments
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
	DAGGER Function
	DATE Function
	DEST Function
	LASTPAGE Function
	LEADERS Function
	NBSPACE Function
	NEWLINE Function
	PAGEOF Function
	RAW Function
	SIGMA Function
	STYLE Function
	SUB Function
	SUPER Function
	THISPAGE Function
	TOCENTRYINDENT Function
	TOCENTRYPAGE Function
	UNICODE Function
Example
	Basic Inline Formatting Functions

Syntax

ODS ESCAPECHAR= 'escape-character';

Required 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. The \ is a special RTF character. Therefore, it is recommended that you use an escape character other than \ for RTF output. [cautionend]

Note: 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. [cautionend]

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.

Details

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. [cautionend]

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 on 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 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 9.2. This chapter contains information on 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. Refer to SAS/GRAPH: Statistical Graphics Procedures Guide and SAS/GRAPH: Graph Template Language User's Guide for information on how to use these functions with ODS Statistical Graphics.

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 listing close;
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. [cautionend]

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:

Syntax

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

escape-character

is the character defined using the ODS ESCAPECHAR statement.

{ }

enclose 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

^{DAGGER}

produces the Greek dagger sign.

Tip:	It is preferable to use the UNICODE function to generate a dagger sign.
Featured in:	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

Syntax

^{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 output. An example is:

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

LASTPAGE Function

^{LASTPAGE}

inserts the total number of pages.

Tip:	This function works with the PRINTER, RTF, and TAGSETS. RTF destinations.
Tip:	You must use Print Preview to view the resolved LASTPAGE function output that is generated by the TAGSETS.RTF destination.

LEADERS Function

Syntax

^{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 Table of Contents. Example code is:

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

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

NBSPACE Function

Syntax

^{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.
Featured in:	Basic Inline Formatting Functions

NEWLINE Function

Syntax

^{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.
Featured in:	Basic Inline Formatting Functions

PAGEOF Function

^{PAGEOF}

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

Tip:	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 "page of" information is not written as expected because the BODYTITLE option removes the titles and footnotes from the header and footer sections of the RTF file. If the desired location of the page numbering is in the title or the footnote, remove the BODYTITLE option.
Tip:	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.
Tip:	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

Syntax

^{RAW <string>}

string

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

Restriction:	The RAW function does not work with PDF or Window's drivers.
Tip:	After this function has been turned on in a session, you cannot turn it off for that session.
Tip:	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.
Featured in:	Basic Inline Formatting Functions

SIGMA Function

^{SIGMA}

generates the Greek SIGMA sign [sigma] .

Tip:	The preferable way to produce a SIGMA sign is to use the UNICODE function.
Featured in:	Basic Inline Formatting Functions

STYLE Function

Syntax

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

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

[cautionend]

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. [cautionend]

SUB Function

Syntax

^{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.

Restriction:	Microsoft Word honors only one level of subscript for RTF and TAGSETS RTF.
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

Syntax

^{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.

Restriction:	Microsoft Word only honors one level of subscript for RTF and TAGSETS.RTF.
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

^{THISPAGE}

inserts the current page number.

Tip:	This function can be used only with the PRINTER, RTF, and TAGSETS.RTF destinations.
Tip:	You must use Print Preview to view the resolved THISPAGE function output that is generated by the TAGSETS.RTF destination.

TOCENTRYINDENT Function

Syntax

^{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

Syntax

^{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. 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 for the PDF destination.
Featured in:	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. 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 for the PDF destination.
Tip:	The unicode-value can be enclosed with single or double quotes.

Example

Example 1: Basic Inline Formatting Functions

ODS features:

ODS RTF statement:

Action:

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. [cautionend]

Program

options nodate nonumber;

ods listing close;

ods escapechar="^";

ods rtf file="rtfInlinFuncs.rtf";
ods rtf 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;

RTF Output

[untitled graphic]

PDF Output

[untitled graphic]

Top of Page