TS-659

18MAR04

TS-659 Exporting SAS/GRAPH Output to PDF Files
from Release 8.2 and higher

The Portable Document Format is a common format for storing text and graphics in a single document. This format supports high-resolutions and maintains the page layout when transmitted, viewed, and printed. The format was developed by Adobe Systems Incorporated and is based upon the PostScript printer language.

The program most often used to view PDF files is Adobe's Acrobat Reader. Acrobat Reader can be downloaded for free from Acrobat Reader Download Site.

From SAS/GRAPH there are two basic methods for exporting graphs to PDF files:

• The native device drivers: PDF and PDFC

• The Universal Printer: PDF

The native device driver method is useful for exporting output from a single procedure to a PDF document. To combine output from multiple procedures in the same document, the PDF Universal printer is recommended. With this method, it is also easier to combine output from both text and graphic procedures in the same document.

The PDF Universal printer also supports some new features in SAS 9.0. In this release, the PDF Universal printer supports compression to reduce the overall file size. Also included is a new method for defining the page layout using the ODS LAYOUT feature of the Output Delivery System. Sections discussing these new features are highlighted with the "9.0" logo shown on the left. The PDF and PDFC device drivers do not support either compression or ODS LAYOUT.

Support for font embedding was added to the PDF Universal printer in SAS 9.1. Adobe Acrobat installs fourteen fonts that it uses to display PDF documents. Text created in these fonts will always display correctly. If text in the PDF file uses a font that is not available to Acrobat on the recipient's system, a font substitution can occur when the document is displayed. This may affect the look of the document. To prevent font substitutions, fonts must either be installed on the recipient's system, or embedded within the document. Information about the font embedding feature is highlighted with the "9.1" icon shown on the left.

It is also possible to create PDF files indirectly by first generating postscript files from SAS and then converting them to the PDF format. This document only discusses methods for creating PDF files directly from SAS.

Contents

1. The Native Device Drivers: PDF and PDFC
   1. Fonts
   2. Examples
      Sample Data
      1. Producing one graph from one procedure
      2. Producing multiple graphs from one procedure using a BY statement
      3. Producing multiple graphs from one procedure using RUN-group processing
      4. Producing multiple graphs from GREPLAY
2. The Universal Printer: PDF
   1. Fonts
      1. Standard Fonts
      2. Embeddable Fonts
   2. ODS PDF Parameters and Options
      1. Parameters that write document information
      2. Parameters that control the bookmarks
      3. Parameters and options that affect page layout
      4. Compression
   3. Examples
      1. Producing a multi-page PDF file using multiple procedures
      2. Producing a one-page PDF file containing multiple graphs from multiple procedures using STARTPAGE
      3. Producing a one-page PDF file containing multiple graphs from multiple procedures using ODS LAYOUT and ODS REGION
      4. Producing a one-page PDF file containing multiple graphs and tables using ODS LAYOUT and ODS REGION
      5. Changing the Font Embedding Level
3. Resources

Two SAS/GRAPH device drivers, PDF and PDFC, can be used to create PDF documents from a single graphics procedure. The PDF device driver produces monochrome output while the PDFC device driver generates color output. To export graphics using a graphics device driver, both a FILENAME statement and a GOPTIONS statement should be defined. These statements specify the export format, the storage location, and the name of the file. For example:

Parameters in italics can be modified. In this code, the FILENAME statement assigns the fileref OUTPUT to the location MYFILE.PDF. The syntax necessary for the FILENAME may vary by operating system. The GOPTIONS statement sets the output format to color PDF using DEVICE=PDFC. The GOPTIONS statement also directs the output to the defined file location using the GSFNAME= parameter. It is always a good practice to include the QUIT; statement after the last RUN; statement when exporting SAS/GRAPH output to graphics files.

With the PDF and PDFC device drivers, you cannot use the GSFMODE=APPEND option to write multiple graphs to the same file. In order for these files to contain multiple graphs, all the graphs must be written by a single procedure. This can be accomplished using BY-group processing, RUN-group processing, or the GREPLAY procedure. Examples are given below.

It is recommend that a hardware font, one native to the PDF format, be used to generate the output. Text created in a font that is also available to the program viewing the file will be rendered in the correct font. Font substitutions can occur for any font the viewing software does not have available. Acrobat Reader, for instance, only includes the Base 14 postscript fonts with its default installation. The PDF and PDFC device drivers include these same 14 Postscript fonts. The names of these fonts as they are used with these device drivers are listed in the table below.

Font names are not case-sensitive but they must be referenced in quotes.

Note: If you have an existing program that references these fonts using their hardware names, such as HWPDF001 for the Courier font, these names are still honored in SAS 8.2 and beyond when using the PDF and PDFC device drivers.

2. Examples

Listed here are four common methods for producing output using the native PDF and PDFC device drivers. These include:

Each method is demonstrated in an example below. The following data is used in all examples in this document. The output from this data may vary in appearance because the summary values are calculated randomly.

a. Producing one graph from one procedure

This program generates a PDF file named PIE.PDF that has one page and one graph in it, a pie chart. The Helvetica-Bold font is used for all the text.

Note: the different pages in the PDF files generated by the code are represented in this document as separate JPEG screenshots, not the actual pages in the PDF files. Images are not to scale.

Snapshot of the PIE.PDF file

This program generates a PDF file named BYPIE.PDF that has four pages with one pie chart on each page. The Helvetica-Bold font is used for all text in the document.

Snapshots of Pages 1-2 of the BYPIE.PDF file

This program generates a PDF file named MULTIRUN.PDF that has two pages with one bar chart on each page. The Helvetica-Bold font is used for all the text in the document.

Snapshots of Pages 1-2 of the MULTIRUN.PDF file

This code stores the graphs from each procedure in a graphics catalog, then replays them in one step to the output file. First the catalog is defined and cleared using the first GREPLAY step. The export format is defined on the GOPTIONS statement, and the NODISPLAY option is specified so the graphs are written only to the catalog, not the output file. On each graphics procedure, the GOUT parameter is used to direct the output to the MYCAT catalog. When all the graphs are created, the DISPLAY option is set so the graphs are written to the output file by the GREPLAY procedure.

Snapshots of Pages 1-2 of the GREPLAY.PDF file

In this example, each graph is written to a separate page of the output. You can also specify a template in the GREPLAY procedure to combine multiple graphs on the same page. To do this, each graph must be properly sized to fit in the template. For example:

With these modifications, both graphs are written to the same page, with the pie chart above the plot. For SAS 8.2 and beyond, the ODS PDF method is recommended to create this kind of output.

The PDF Universal printer can be useful for storing the output from multiple procedures in the same PDF file. Once the destination is open, all procedure output, including output from text procedures, is directed to the document. By default each table or graph is written to a separate page.

You can produce output with the Universal PDF printer by specifying the printer for the PRINTERPATH option on the OPTIONS statement, or as the printer on the ODS PRINTER statement.

Specifying the printer on the OPTIONS statement sets the printer as the default printer. You can create PDF files with the printer by using syntax like the following:

Parameters in italics can be modified. The device SASPRTC must be specified to direct the graphics output to the default printer.

For more control over the placement of objects in the output, you can use the Output Delivery System PRINTER destination instead. You may either specify: "ODS PRINTER PRINTER=PDF" or "ODS PDF"; both statements refer to the same destination. The basic code necessary to generate a PDF file with this method is as follows:

Parameters in italics can be modified. The FILE= parameter can point to a predefined file reference or directly to a file as shown. While the ODS destination is open, all procedural output is written to the file FILENAME.PDF. It is important to include the RUN; and QUIT; before the "ODS PDF CLOSE" statement which terminates the destination. Otherwise the output from the last procedure may not be included in the document.

Before creating output to the ODS PDF destination, it is recommended that the ODS LISTING destination be closed. On Windows systems, the SASPRTC device driver refers to the system printers when the LISTING destination is opened; closing LISTING prevents the output from going directly to the printer.

When the ODS PDF destination is open, the SASPRTC device driver produces graphs in the PDF file using PDF commands, and makes available to the graph all the fonts available in the ODS PDF destination. You could also specify device drivers such as PNG or JAVA when producing graphs in the ODS PDF destination, although these device drivers may not recognize the same font set as the text output in the document.

The recommended statements for creating PDF documents with the ODS PDF method are as follows:

The remainder of this document focuses on using the ODS destination with the PDF Universal printer to create PDF output files.

1. Fonts

a. Standard Fonts

The fonts available with the ODS PDF destination are listed in the SAS Registry under the [CORE\PRINTING\PRINTERS\PSL\FONT FAMILIES] key. Remember that these fonts are not included in the PDF file, so only the fonts installed with the Reader will be rendered correctly. Therefore, unless you are certain a non-standard font will be available on the recipient's system, it is recommended that the Base 14 fonts, those included with the default installation of Reader, be used. For the PDF Universal printer, these fonts are referenced as follows:

Font names must be enclosed in quotes but they are not case-sensitive. The parameters listed after the slashes may come in any order. Notice that these names vary from the names used with the PDF and PDFC device drivers.

b. Embeddable Fonts

Using the FreeType library, SAS 9.1 can embed TrueType fonts in PDF files created with the PDF Universal printer. When a font is embedded, font information is carried in the document, and the viewer does not require that the font be installed on the system in order for the text to display properly. Embedding fonts can prevent font substitutions, and ensure that the document always has the same look.

The new FONTREG procedure is used to add information about font files on the system to the SAS Registry. This step must be performed before the ODS PDF destination can embed these fonts. Information about two TrueType fonts, SAS Monospace and SAS Monospace/bold, is already added for you. To make other fonts available, follow the steps discussed in the paper, Using TrueType fonts with Universal Printing in SAS 9.1.

Three levels of font embedding are supported: none, partial, and full. The default level for the PDF Universal Printer is partial. You can change these settings using the instructions in Changing the Embedding Value below.

2. ODS PDF Parameters and Options

a. Parameters that write document information

TThese parameters provide general information about the document. They should be specified on the first ODS PDF statement that designates the FILE that is created. The values of these parameters can be viewed in the "General" section of the "Document Info" dialog when the document is viewed in Acrobat Reader.

• AUTHOR="name"
• KEYWORDS="word1 word2 <wordlist>"
• SUBJECT="subject"
• TITLE="title"

b. Parameters that control the bookmarks

Each procedure that writes output to the PDF file creates bookmarks including headings that describe the procedure and subheadings that describe the graphs or tables created by the procedure. These bookmarks can be used to easily navigate to different sections of the document.

• ODS PROCLABEL="text"

  Lets you change the label used for the procedure (bookmark heading). Graph descriptions (bookmark subheadings) can be controlled using the DESCRIPTION= option within the graphics procedure. Text procedures, such as PROC PRINT, generally support the CONTENTS= option to define bookmark subheadings.

  If the bookmarks are missing or incorrect, you may wish to consult the following SAS Notes:

  • SN 5089: Duplicate bookmarks exist.
  • SN 5777: Bookmark for GREPLAY has the wrong name.
  • SN 7389: Bookmarks are missing.

c. Parameters and options that affect page layout

• ORIENTATION=<PORTRAIT/LANDSCAPE>

  This option controls the page orientation. The default is usually portrait. The same orientation must be used throughout the entire document.

  The size of the graph on the page is set with the HEIGHT and WIDTH parameters on the GOPTIONS statement.

• PAPERSIZE=<LETTER/LEGAL/ISOA4>

  Controls the size of the page. A list of all the available pre-defined sizes is in the SAS Registry under the CORE\PRINTING\PAPER SIZES key.

  In SAS 9.0, you can also set a customized paper size such as: PAPERSIZE=("8in","8in").

• LEFTMARGIN=
• RIGHTMARGIN=
• TOPMARGIN=
• BOTTOMMARGIN=

  Each of these parameters sets a margin size for the page. Sizes such as "1 in" or "2 cm" can be specified for each margin.

  There is a difference in the method used to calculate the graph placement in SAS 9.0 and beyond. In SAS 8.2, the HORIGIN and VORIGIN options were calculated from the LEFTMARGIN and BOTTOMMARGINS, respectively. In SAS 9.0 and beyond, these parameters measure from edge of the page instead. The table below compares the affect of the LEFTMARGIN and HORIGIN options on the horizontal placement of a graph. Units of IN are assumed for this illustration.

  LEFTMARGIN	HORIGIN	Position of left edge of the graph from the left edge of the page
  		SAS 8.2	SAS 9.0 and above
  .25	.5	.75	.5
  .25	.25	.5	.25
  1	.25	1.25	1*

  *In SAS 9, if the HORIGIN is less than the left margin, the left margin is used.

  Note that HORIGIN=0 is a special case. This value will reset the HORIGIN to the default value, which in all releases is the left margin setting.

  STYLE=<STYLESHEET NAME>

  Styles sheets are used to specify colors, fonts, and other aspects of the document. See documentation for style sheets and the TEMPLATE procedure in the OnlineDoc. The FAQ site may also be helpful.

  ODS LAYOUT <START/END> HEIGHT=<value> WIDTH=<value>

  ODS REGION X=<value> Y=<value> HEIGHT=<value> WIDTH=<value>

  

  Together the ODS LAYOUT and ODS REGION statements define areas on the page where output is placed. Multiple regions can be defined in the same layout to position different outputs on the same page. To insert a page break, close the current LAYOUT and then open a new one.

  The ODS LAYOUT feature is experimental in SAS 9. For an introduction see: http://support.sas.com/rnd/base/topics/odsprinter/new9.html#LAYOUT

  Designing the graph placement with REGIONS is different than using HORIGIN and VORIGIN in two ways:

  • The X and Y values for a REGION are measured from the margin, not the edge of the page.

  • X values are measured left to right, just like HORIGIN. However Y values are measured from the top-down, whereas VORIGIN measures from the bottom-up.

  For example, the following GOPTIONS would place a 6.5x4in graph on a LETTER-size page with one inch margins on the top and left, and right:

  goptions horigin=1 in vorigin=6 in vsize=4 hsize=6.5;

  To position the same graph using the ODS LAYOUT and ODS REGION statements, the following code could be used:

  ods layout x=1 in y=1 in height=9 in width=6.5 in;
  ods region x=0 in y=0 in height=4 in width=6.5 in;

  STARTPAGE=<YES/NOW/NO/NEVER>

  This parameter is used on the ODS PDF statement to control pagination in the file. The values are as follows:

  • YES: Insert a page break after each output or graph. This is the default.

  • NOW: Insert a page break now, then resume the previous behavior.

  • NO: Keep output from multiple text procedures on the same page if possible.

  • NEVER: Keep output from multiple text and graphics procedures on the same page.

  The STARTPAGE parameter can be used in conjunction with the HSIZE, HORIGIN, VSIZE, and VORIGIN values on the GOPTIONS statement to place multiple graphs or combine graphs and text output on a single page. The ODS LAYOUT method is recommended instead in SAS 9.

  There is a difference in the way STARTPAGE creates page breaks in SAS 8.2 and SAS 9.0 and above. In SAS 8.2, you could insert a page break between procedures using one of the following methods:

  /* Method 1 */
  

  ods pdf startpage=never;
  /* code for graph 1 on page 1 */ RUN;
  /* code for graph 2 on page 1 */ RUN;
  ods pdf startpage=now;
  /* code for graph 1 on page 2 */ RUN;
  /* code for graph 2 on page 2 */ RUN;
  

  /* Method 2 */
  

  ods pdf startpage=never;
  /* code for graph 1 on page 1 */ RUN;
  /* code for graph 2 on page 1 */ RUN;
  ods pdf startpage=yes;
  ods pdf startpage=never;
  /* code for graph 1 on page 2 */ RUN;
  /* code for graph 2 on page 2 */ RUN;
  

  For SAS 9.0, a step-boundary must occur for the page break to be recognized:

  ods pdf startpage=never;
  /* code for graph 1 on page 1 */ RUN;
  /* code for graph 2 on page 1 */ RUN;
  ods pdf startpage=yes;
  /* code for graph 1 on page 2 */ RUN;
  ods pdf startpage=never;
  /* code for graph 2 on page 2 */ RUN;
  

d. Compression

• COMRESS=<value>

Be aware that setting compression to high levels, such as 8 or 9, may greatly increase the processing time required to create the output.

3. Examples

Four examples are given below for generating graphics to the ODS PDF destination. The last example shows how to create a PDF printer to fully embed all fonts, or embed no fonts.

Data for the first four examples is created here.

This code generates a two-page, landscape-oriented PDF file named VBAR.PDF. Each page contains one vertical bar chart. The Times font is used for all the text in the output.

The following bookmarks are produced in the file:

Each bookmark would navigate to the corresponding page in the file.

Snapshots of Pages 1-2 of the VBAR.PDF file

This code combines four graphs in one PDF file named FOURVBARS.PDF. The STARTPAGE=NEVER parameter keeps all the output on one page. Each graph is positioned on the page using the HORIGIN and VORIGIN parameters on the GOPTIONS statement. The size of each graph is set using the HSIZE and VSIZE parameters on the GOPTIONS statement. The first graph, GSLIDE, creates the common title over all the graphs. The LSPACE parameter on the TITLE statement inserts a line space above the title. The Courier/oblique font is used for all the text in the output.

Snapshot of the FOURVBARS.PDF file

This example will only run in SAS 9.0 or higher.

This code combines four graphs in one PDF file named LAYOUT1.PDF. Each graph is positioned on the page using the X and Y values on the ODS REGION statement. The HEIGHT and WIDTH parameters define the size of each region. The size of each graph is set automatically to fit within the region. The first graph, the GSLIDE, creates the common title over all the graphs. The LSPACE parameter on the TITLE statement inserts a space above the title. The Helvetica font is used for all the text in the output.

Note: Remember that the values for X and HORIGIN work similarly: they both increase from left to right. The values for Y and VORIGIN are opposites.

Snapshot of the LAYOU1.PDF file

d. Producing a one-page PDF file containing multiple graphs and tables using ODS LAYOUT

This example will only run in SAS 9.0 or higher.

This code combines two graphs and two tables on a document named LAYOUT2.PDF. Each output is positioned on the page using the X and Y values on the ODS REGION statement. The HEIGHT and WIDTH parameters define the size of each region. The size of each graph is set automatically to fit within the region. The first graph, the GSLIDE, creates the common title over all the graphs. The LSPACE parameter on the TITLE statement inserts a line space above the title. The Helvetica font is used for all the text in the graph.

options orientation=portrait;
goptions reset=all dev=sasprtc ftext="Helvetica";
ods listing close;
ods pdf file="LAYOUT2.pdf";
ods layout start;
ods region x=0 in y=0 in height=10.5 in width=8 in;

proc gslide;
title1 'Sales by Region and Season' lspace=.5in;
run;quit;ods region x=0 in y=1.5 in height=4 in width=5 in;
title1 'Sales by Region';
pattern1 value=solid color=cx33aacc;
proc gchart data=sample;
vbar Region /sumvar=Sales discrete
coutline=black
midpoints="North" "East" "Central" "West" "South";run;quit;ods region x=4 in y=1.5 in height=4 in width=3 in;
proc report data=sample nowd;
column region sales;
define region / group;run;quit;ods region x=0 in y=6 in height=4 in width=5 in;
title1 'Sales by Season';
proc gchart data=sample;
vbar season /sumvar=Sales discrete
coutline=black
midpoints="Spring" "Summer" "Fall" "Winter";run;quit;ods region x=4 in y=6 in height=4 in width=3 in;
proc report data=sample nowd;
column season sales;
define season / group;run;quit;ods layout end;
ods pdf close;
ods listing;

Snapshot of the LAYOUT2.PDF file

e. Changing the Font Embedding Level

The level of font embedding for a given printer is set in the SAS Registry under the "Font Embedding Level" key. In the SAS Registry, the "Font Embedding Level" key can have one of the following values:

All TrueType fonts used in the document are embedded according to this setting. Embedding of other font types is not yet supported in this release.

The Universal PDF printer has a value of 1 for this key, so it supports partial embedding by default. You can create documents that fully embed or do not embed TrueType fonts by defining additional printers with the REGISTRY procedure. One easy method for creating a new printer from an existing printer is to export the keys for an existing printer to a file, modify the file, and re-import it. The steps are as follows:

• Acrobat Reader
• FreeType Project
• Introduction to ODS LAYOUT
• The TEMPLATE Procedure FAQ
• ODS PRINTER FAQ