50
Paper 092-31
PDF Can be P
retty D
arn F
ancy -
Tips and Tricks for the ODS PDF Destination
Pete Lund
Looking Glass Analytics, Olympia, WA
Abstract
We're not too far removed from the days when presentation-ready SAS® output meant lots of cutting and
pasting or retyping. Now, the ODS PDF destination enables you to produce high quality output the first time,
without other tools or applications.
This paper explores a number of ODS options in general and, more specifically, their use in creating PDF
output. We will cover ODS ESCAPECHAR, which allows for inline formatting of titles, footnotes and other text;
ODS LAYOUT, which lets you place output wherever you want it on the page - even output from more than one
procedure; inline formatting in PROC REPORT; overlaying output from SAS/Graph procedures on top of other
output and more.
We'll work from real life examples and see how you can produce output that looks like it took hours to create.
Introduction
This paper could be called “A Tale of Five Reports” – a series of real world examples that demonstrate a
number of techniques that can be used with the PDF destination to make your reports crisper, cleaner and more
useful than ever before.
All too often it seems that the examples presented in conference papers are difficult to translate to “real” code
and the reader is forced to bridge the gap between concept and reality. All the examples shown here are copied
directly from production code – the only exception being some macro variable references have been “resolved”
to show the real values. The hope is that these annotated examples will give some ideas to use in your own
jobs and see the breadth of options available to make your output look the way you want it to – without any
after-the-fact intervention.
PROC REPORT, ODS PDF and Inline Styles
Many of the examples presented in the paper use PROC REPORT. This procedure has the most flexibility in its
use of ODS-related options and can best demonstrate the possibilities of creating PDF output. However, there
are similar techniques that can be used with PROC PRINT and PROC TABULATE, as well as a number of
techniques we’ll see that are procedure independent.
C
REATING
G
ROUPS OF
D
ATA
C
OLUMNS
We’ll start with something simple – simple that is with ODS and PDF, not so simple just a few short years ago.
Notice in Exhibit 1/Item 2 that there is a little extra space between some of the columns. Not quite a full data
column worth, but enough to offset groups of data columns.
This is easy to do in PROC REPORT with some in-line formatting and a computed column. The pertinent code
is shown below:
1
Data Presentation
SUGI 31
1
41
Note in the report that the columns with yearly data (thisyear, lastyear and diff) are placed under a common
column header (the “across” variable locationgroup). To visually separate the columns we can include a fourth
variable, blank. Blank does not exist in the incoming dataset – it is computed in the procedure and set to
missing (note the COMPUTE block). This could be done prior to ODS and you’d get a blank column in your
output. However, notice the STYLE= parameter on the DEFINE statement for blank: we can specify the width of
the column with the CELLWIDTH parameter and create a gap as large or small as we need.
We’ll see a number of other examples of style parameters. The syntax is simple:
STYLE=[<style option=style value> <style option=style value >]
You can enclose as many option=value pairs as you need, separated by spaces. A complete list of style options
is included in Appendix A at the end of the paper.
C
REATING
G
ROUPS OF
D
ATA
R
OWS
We’ve seen how to add and control the appearance of blank columns in a report. We can use another
technique to add blank rows to a report. Again, this technique could be used prior to ODS, but with the addition
of STYLE we can control the appearance of those blank rows. Take a look at Exhibit 2/Item 2. Note that the
blank line every five rows is a different color than the data rows and that it’s not as tall as the data rows. The
blank lines are created in the following COMPUTE block.
The variable LineGroup is a non-printing GROUP variable that changes values every five observations. So,
this COMPUTE code executes at the beginning of each group of five observations and writes a blank row to
the table. However, it’s size and color are different from the surrounding rows because of the STYLE= option.
D
IFFERENTIAL
S
TYLES ON
D
ATA
R
OWS
Another use of inline styles can be seen in Exhibit 3. Item 1 points out that we have different text styles on
different rows of the table, depending on the type of data displayed. The total lines are italicized for added
emphasis.
2
Data Presentation
SUGI 31
1
39
There is one other trick to note from Exhibit 3. We just alluded to the fact that the header row has a background
color. It’s hard to see in the black and white copy in the paper, but the background color of the header rows are
the same color as the bars in the corresponding graph on the bottom of the page. The Adult rows in the table
and bars on the Adult graph are green. The background and bars for the youth are blue. We can use another
style trick to make this easy.
We start out by defining a SAS format that has RGB color codes as the labels for the data values.
The format will be used in an unusual place. As we saw above, the dataset used in the report contains a
variable called TreatmentDetail that contains the type of treatment received (i.e., OPA=outpatient adult). We’re
going to reference the format we’ve just created, which defined the colors we want to use based on the type of
treatment received, in the DEFINE statement for TreatmentDetail.
So, using the format in a STYLE= option on the DEFINE statement allows us to control the appearance of the
data cell based on the value of the data.
We’ll have one more example of inline STYLE= options when we discuss methods for putting output from more
than one procedure on a page. For now, let’s look at the greatest thing to happen to ODS since…. Well, it’s
just the greatest thing ever to happen to ODS.
ODS
E
SCAPECHAR
–
T
HE
G
REATEST
T
HING
S
INCE
S
LICED
B
READ
The ODS ESCAPECHAR statement, while not specific to PDF, is one of most powerful new features of the
Output Delivery System. The statement defines a character that is used to designate the beginning of a series
of formatting commands.
ODS ESCAPECHAR=’^’
3
Data Presentation
SUGI 31
1
31
That character will be used to designate sequences of text to be treated as “instructions” for the text that follows
them. You can use the escaped sequences to change the style of titles and footnotes, add page numbers and
superscripts, highlight single words in your output, and much more. You’ll want to choose a character that is not
likely to be used in your data so as not to “confuse” ODS. Common choices are carets (^) and tildes (~).
We’ll look at a number of examples of using escape sequences to enhance your output. For all the examples
we’ll use assume that we’re using the command above and use a caret to denote our escape sequences.
Inline Formatting
We’ve seen a number of examples of formatting with the STYLE= option in PROC REPORT. A major use of
ESCAPECHAR is to allow formatting of output almost anywhere – either from procedures, titles and footnotes.
The escape sequence “^S={}” allows you to embed style parameters in the brackets anywhere in your text. It’s
required to use a capital S and, like STYLE=, any number of style parameters can be placed inside the brackets.
The following example is from Exhibit 4/Item 2. Note in the exhibit that the leading part of the text is bold and
the number part of the text is not. The code uses two S={} sequences in the value to be displayed by a LINE
statement.
Notice also that there is a STYLE= option on the COMPUTE statement which left justifies the text. You can use
both methods for assigning styles. In this case, the ^S={} gives us control over portions of the text.
This same exhibit (4), item 1 points to another use of inline styles. The leading line of each section contains a
name, booking number, booking date, etc. for inmates in a jail. (The names have been obscured or changed for
confidentiality reasons.) Notice that the name is a larger, bold font and that the header text for the other items
on the row are bold.
All the information on this row is actually contained in one big text variable. The value of the variable contains
all the formatting information, along with the actual data values. Here is the datastep code that creates the
variable (Key).
When this value is printed in PROC REPORT, the formatting information does not print but is applied to the
other parts of the value.
This method of inline formatting can be used anywhere text is displayed: titles, footnotes, variable values, etc. It
gives you a great deal of control over the appearance of your output.
4
Data Presentation
SUGI 31
1
32
Special Escape Sequences
In addition to S={}, the ESCAPECHAR can also be used to add some special values to your output.
In Exhibit 1/Item 3 we see a superscript on the footnote at the bottom of the page. Superscripting is achieved
with the escape sequence {super nn}, where nn is the value to be superscripted. The code used in Item 3
shows that we can just add the escape sequence to the footnote text.
footnote1 '^{super 1}Totals may include contract beds';
The 1 is superscripted at the beginning of the text and, again, the escape sequence does not print. As you can
guess, there is also a {sub nn} sequence to subscript values.
Exhibit 1 also shows another use of superscripts. Item 1 shows a superscript in a column header. The
superscript value is actually contained in the label of the format for these values.
As we’ve already seen, anywhere text can be generated the escape sequences can be used.
A topic which has generated a number of SUGI papers is putting dynamic page numbers on your output. This is
a paper topic no more as it now only an escape sequence added to your titles or footnotes. There are two
escape sequences that we’ll demonstrate for included page numbers on your output.
A number of the exhibits included in this paper have page numbers – we’ll look at those shown on Exhibit 4/Item
3.
We can use the {thispage} and {lastpage} sequences together to get the nice “page x of y” that we’ve struggled
so many years for.
One last special escape sequence to note is wrapping to a marker. Exhibit 5/Item 2 shows a nice set of
footnotes indented under a header. All of the footnotes in this example are done with a single footnote
statement.
We will use two escape sequences here to get the footnotes looking this way. First, the -2n sequence produces
a line break in the text. (A quick side note here – does the fact that there are a whole bunch of nicely arranged
footnote lines generated from a single footnote statement give you a clue that you’ll never have to worry about
the 10 footnote limit again!). But, we can use -2n in conjunction with another escape sequence (m) to get the
indented effect that we see.
The m escape sequence sets a “marker” that the -2n will wrap to. This is more easily explained with the code
that generated the example.
5
Data Presentation
SUGI 31
1
33
First, notice that this is all one footnote statement. Second, if you look between the code and the exhibit you will
see that the individual physical line in the code do not affect the output – they are there only to make them fit on
my screen when I’m writing the code. Now, let’s look at the use of the two escape sequences.
ODS
PDF
T
EXT
There is new way you can embed text in a document. The ODS PDF TEXT command is like a PUT statement
that you can use anywhere. The syntax is simple,
ods pdf text=’<text goes here>’;
The output of the command will be placed on the page immediately following the last procedure output. It would
be a relatively useless command if all it did was place plain text. I bet you’ve already figured out that all the
inline style functionality provided by ESCAPECHAR can be used in PDF TEXT.
Exhibit 6 shows an entire page generated using nothing but PDF TEXT. This offers a wonderful method of
adding explanatory text to your reports without having to edit them after the fact.
O
UTPUT FROM
M
ORE THAN
O
NE
P
ROCEDURE ON A
P
AGE
With SAS/Graph we’ve had PROC GREPLAY and the VPOS/HPOS/VSIZE/HSIZE options that have allowed
putting output from more than one graphic procedure on the page at one time. This has always been more of a
challenge with output from text-based reporting procedures. We’ll look at two methods now available with ODS
which allows us to do just that.
6
Data Presentation
SUGI 31
1
26
STARTPAGE=NEVER
By default, any time a new procedure is run a new page will be created in the output document. There is an
option (STARTPAGE=) on the ODS PDF statement which controls that page generation.
The STARTPAGE=NEVER option tells ODS that you don’t want a page generated between procedures. You
still get a new page when the current page fills up, but new procedure output will start immediately following
previous output.
Exhibit 5 shows an example of how this works. The data at the top of the page is generated from a PROC
REPORT. The data at the bottom of the page is from a second PROC REPORT. The ODS PDF statement
contained a STARTPAGE=NEVER so that the output from both procedures showed up on the same page.
There is s STARTPAGE=NOW option you can use to force a new page whenever you want it, which is handy if
you’ve turned the startpage off. You can set the startpage to NOW with a ODS PDF statement that does not
reference a file, so will be applied to the current PDF file being created. For example,
ods pdf file=’my pdf file.pdf’ startpage=never;
<procedure 1>
<procedure 2>
ods pdf startpage=now;
<procedure 3>
There would be no page break between the output from procedures 1 and 2 above, but output from procedure 3
would begin on a new page.
It was noted earlier that there would be one more STYLE= example when we discussed multiple outputs on a
page. In Exhibit 5, the single columns in the upper report need to be centered over the groups of three columns
in the lower report. We can do this with STYLE= options on the DEFINE statements in the two procedures.
7
Data Presentation
SUGI 31
1
35
Notice also that we’ve made one more use of -2n. In the variable labels for ResolutionCode and MedianDays,
we’ve added a -2n to split the label. Note: in order to fit this all on the page some code has been removed that
is part of those labels. This additional information makes the use of the PROC REPORT SPLIT= option
unusable in this case.
ODS LAYOUT
Another method of putting more than one piece of output on the page is with ODS LAYOUT. LAYOUT enables
you to specify regions on the page that output will be written to. Exhibit 7 shows a report with output from one
PROC SQL, three PROC REPORTS and six PROC GCHARTS. How did we do this one?
The first table is generated with PROC SQL with nothing special added, except that STARTPAGE=NEVER is
set so that all the other output shows up on the same page. Then we start with LAYOUT. There are three
commands necessary to use ODS LAYOUT.
ODS LAYOUT START;
ODS REGION X=xxx Y=yyy WIDTH=www HEIGHT=hhh;
ODS LAYOUT END;
START and END turn on and off the LAYOUT and REGION specifies the size and position of the page region to
write output to. There can be as many regions as you want on the page. There are some important region rules
to be aware of:
• regions are not transparent. If they overlap, the first one defined has that space on the page and will
overwrite the output beneath it.
• the size of the region is determined by the WIDTH and HEIGHT parameters, not the amount of data
sent to the region. If you have a large region set and only one row of data, the region is still large (and
may overlay other regions).
• output is not sized to the region. If if doesn’t fit, it is truncated. There is a log note warning you of this.
• LAYOUT is limited to one page. There is no spanning of regions or output to additional pages.
With those rules in mind, let’s look at the code for Exhibit 7.
Notice that our regions do not overlap, the X value on each region is greater than the width of the previous
region. Also, as noted above, the Y value is set from the top of the page (0=top of printable area). This is
opposite of the Y position values in SAS/Graph, where 0 is the bottom of the page.
ODS LAYOUT is still in it’s infancy. There are a number of other options that are experimental and may change.
There are examples and news on the SAS web site of other features that are coming that you may want to play
with.
8
Data Presentation
SUGI 31
1
43
O
VERLAYING
G
RAPHIC
O
UTPUT ON
T
ABULAR
D
ATA
There are occasions where it’s nice to augment tabular output with some graphical elements. With some
techniques we’ve already looked at we can do this. Exhibit 8 shows a PROC REPORT output that has vertical
lines setting off groups of columns. This isn’t possible to do with PROC REPORT and ODS alone.
The technique used here is to generate the REPORT output and then use an annotate dataset and PROC
GSLIDE to create the lines. We can use the STARTPAGE=NEVER option to put the table and “graphic” on the
same page.
C
ONCLUSION
This paper has presented a number of tips and tricks that you can use to enhance to look of your SAS output.
There are a number of other options available for ODS in general and PDF output in particular. I’d encourage
you to go to the SAS website where there is a wealth of information. Go to support.sas.com and click on
Communities and Base SAS. There you’ll find FAQs, white papers, news and other information on ODS.
A
UTHOR
C
ONTACT
I
NFORMATION
Pete Lund
Looking Glass Analytics
215 Legion Way SW
Olympia, WA 98501
(360) 528-8970
pete.lund@lgan.com
A
CKNOWLEDGEMENTS
SAS® and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS
Institute, Inc. in the USA and other countries. ® indicates USA registration.
Other brand and product names are registered trademarks or trademarks of their respective companies.
9
Data Presentation
SUGI 31
1
11
Exhibit 1
1– Superscript in
column headers
2– Gaps between
data columns
3– Superscript in
footnote text
10
Data Presentation
SUGI 31
1
Documents you may be interested
Documents you may be interested
