ODS PCL Statement

Opens, manages, or closes the PCL destination, which produces printable output for PCL (HP LaserJet) files.
Valid in: Anywhere
Category: ODS: Third-Party Formatted
Note: By default, the ODS PCL statement creates Scalable Vector Graphics. Scalable Vector Graphics (SVG) is an XML language for describing two-dimensional vector graphics. For information about scalable vector graphics, see Using Scalable Vector Graphics in SAS/GRAPH: Reference.
Syntax
Details
Opening and Closing the PCL Destination
The ODS Printer Family of Statements
See Also

Syntax

ODS PCL <(<ID=> identifier)> < action> ;
ODS PCL <(<ID=> identifier)> <option(s)> ;

Summary of Optional Arguments

(<ID=> identifier)
Open multiple instances of the same destination at the same time
CLOSE
Close the destination and the file that is associated with it
COLOR=FULL | GRAY | MONO | NO | YES
Apply a specified color scheme to your output
COLUMNS=n
Specify the number of columns to create on each page of output
CSSSTYLE='file-specification'<(<media-type-10>)>
Specify a cascading style sheet to apply to your output
DPI=
Specify the image resolution in dots per inch for output images
EXCLUDE exclusion(s)| ALL | NONE
Exclude output objects from the destination
FILE='external-file' | fileref
Specify the file to write to
GFOOTNOTE | NOGFOOTNOTE
Specify the location where footnotes are printed in the graphics output
GTITLE | NOGTITLE
Control the location where titles are printed in the graphics output
NEWFILE= starting-point
Create a new file at the specified starting-point
PACKAGE <package-name>
Specify that the output from the destination be added to an ODS package
SELECT selection(s) | ALL | NONE
Select output objects for the destination
SHOW
Write to the SAS log the current selection or exclusion list for the destination
STARTPAGE=NEVER | NO | NOW | YES | BYGROUP
Control page breaks
STYLE=style-definition
Specify the style definition to use in writing the PDF output
TEXT='text-string'
Insert text into your output
UNIFORM
For multi-page tables, provide uniformity from page to page within a single table

Without Arguments

If you use the ODS PCL statement without an action or options, then it opens the PCL destination and creates PCL output.

Actions

The following actions are available for the ODS PCL statement:

CLOSE
closes the destination and any files that are associated with it. For Printer destinations, you cannot print the file until you close the destination.
Tip:When an ODS destination is closed, ODS does not send output to that destination. Closing an unneeded destination conserves system resources.
EXCLUDE exclusion(s)| ALL | NONE
excludes one or more output objects from the destination.
Default:NONE
Restriction:A destination must be open for this action to take effect.
SELECT selection(s) | ALL | NONE
selects output objects for the specified destination.
Default:ALL
Restriction:A destination must be open for this action to take effect.
SHOW
writes the current selection list or exclusion list for the destination to the SAS log.
Restriction:The destination must be open for this action to take effect.
Tip:If the selection or exclusion list is the default list (SELECT ALL), then SHOW also writes the entire selection or exclusion list. For information about selection and exclusion lists, see Selection and Exclusion Lists.

Optional Arguments

COLOR=FULL | GRAY | MONO | NO | YES
applies the specified color scheme to your output.
FULL
creates full color output for both text and graphics.
GRAY
creates gray scale output for both text and graphics.
Alias:GREY
MONO
creates monochromatic output for both text and graphics.
Alias:BW
NO
does not use all the color information that the style definition provides. If you specify COLOR=NO, then the destination does this:
  • generates black and white output
  • creates all text and rules in black
  • sets the SAS/GRAPH device to produce SAS/GRAPH output in gray scale
  • ignores specifications for a background color from the style definition except for the purposes of determining whether to print rules for the table
YES
uses all the color information that a style definition provides, including background color. In order to actually print in color, you must also do the following:
  • use a printer that is capable of printing in color.
  • use the COLORPRINTING SAS system option. For information about the COLORPRINTING system option, see SAS System Options: Reference.
Default:YES
Tip:If you choose color output for a printer that does not support color, then your output might be difficult to read.
COLUMNS=n
specifies the number of columns to create on each page of output.
n
is the number columns per page.
Default:1
CSSSTYLE='file-specification'<(<media-type-10>)>
specifies a cascading style sheet to apply to your output.
file-specification
specifies a file, fileref, or URL that contains CSS code.
file-specification is one of the following:
"external-file"
is the name of the external file.
Requirement:You must enclose external-file in quotation marks.
fileref
is a file reference that has been assigned to an external file. Use the FILENAME statement to assign a fileref.
See:For information about the FILENAME statement, see SAS Statements: Reference.
"URL"
is a URL to an external file.
Requirement:You must enclose external-file in quotation marks.
(media-type-1<.. media-type-10>)
specifies one or more media blocks that corresponds to the type of media that your output will be rendered on. CSS uses media type blocks to specify how a document is to be presented on different media: on the screen, on paper, with a speech synthesizer, with a braille device, and so on.
The media block is added to your output in addition to the CSS code that is not contained in any media blocks. By using the media-type suboption, in addition to the general CSS code, you can import the section of a CSS file intended only for a specific media type.
Default:If no media-type is specified in your ODS statement, but you do have media types specified in your CSS file, then ODS uses the Screen media type.
Range:You can specify up to ten different media types.
Requirements:You must enclose media-type in parentheses.

You must specify media-type next to the file-specification specified by the CSSSTYLE= option.

Tip:If you specify multiple media types, all of the style information in all of the media types is applied to your output. However, if there is duplicate style information in different media blocks, then the styles from the last media block are used.
Requirement:CSS files must be written in the same type of CSS produced by the ODS HTML statement. Only class names are supported, with no IDs and no context-based selectors. To view the CSS code that ODS creates, you can do one of the following:
  • Specify the STYLESHEET= option.
  • View the source of the HTML file and look at the code between the <STYLE> </STYLE> tags at the top of the file.
Interaction:If both the STYLE= option and the CSSSTYLE= option are specified on an ODS statement, the option specified last is the option that is used.
See:For an example of a valid for ODS CSS file, see Applying a CSS File to ODS Output.
DPI=
specifies the image resolution for output files.
Default:150
Restriction:The DPI= option takes effect only if specified at the opening of a file.
FILE='external-file' | fileref
specifies the file that contains the output.
external-file
is the name of an external file to write to.
Requirement:You must enclose external-file in quotation marks.
fileref
is a file reference that has been assigned to an external file. Use the FILENAME statement to assign a fileref.
Restriction:The FILE=fileref option cannot be used in conjunction with the NEWFILE= option.
See:For information about the FILENAME statement, see SAS Statements: Reference.
Default:If you do not specify a file to write to, then ODS writes to the file that is specified by one of two SAS system options:
SYSPRINT= if you are using the Windows operating environment and do not specify any of the following options: PCL, PDF, PDFMARK, PS, or SAS.
PRINTERPATH= in all other cases.
If the system option does not specify a file, then ODS writes to the default printer. For more information, see the PRINTER= option.
Interaction:In an ODS printer family statement that refers to an open ODS PRINTER destination, the FILE= option forces ODS to close the destination and all files that are associated with it, and to open a new instance of the destination. For more information, see Opening and Closing the PRINTER Destination.
See:For information about the FILENAME statement, see SAS Statements: Reference.
GFOOTNOTE | NOGFOOTNOTE
controls the location of the footnotes that are defined by the graphics program that generates the Printer output.
GFOOTNOTE
includes all of the currently defined footnotes within the graphics output.
NOGFOOTNOTE
prevents all of the currently defined footnotes from appearing in the graphics file. Instead, they become part of the Printer file.
Default:GFOOTNOTE
Restriction:This option applies only to SAS programs that produce one or more device-based graphics, or graphics created by the SGPLOT procedure, the SGPANEL procedure, or the SGSCATTER procedure.
See:For more information, see Customizing Titles and Footnotes.
GTITLE | NOGTITLE
controls the location of the titles that are defined by the graphics program that generates the Printer output.
GTITLE
includes all of the currently defined titles within the graphics output.
NOGTITLE
prevents all of the currently defined titles from appearing in the graphics output. Instead, the titles become part of the Printer file.
Default:GTITLE
Restriction:This option applies only to SAS programs that produce one or more device-based graphics, or graphics created by the SGPLOT procedure, the SGPANEL procedure, or the SGSCATTER procedure.
See:For more information, see Customizing Titles and Footnotes.
(<ID=> identifier)
enables you to open multiple instances of the same destination at the same time. Each instance can have different options.
identifier
can be numeric or can be a series of characters that begin with a letter or an underscore. Subsequent characters can include letters, underscores, and numerals.
Restriction:If identifier is numeric, it must be a positive integer.
Requirement:The ID= option must be specified immediately after the destination name.
NEWFILE= starting-point
creates a new file at the specified starting-point.
starting-point
is the location in the output where you want to create a new file.
ODS automatically names new files by incrementing the name of the file. In the following example, ODS names the first file REPORT.PS. Additional body files are named REPORT1.PS, REPORT2.PS, and so on.
Example: 
FILE= 'REPORT.PS'
starting-point can be one of the following:
BYGROUP
starts a new file for the results of each BY group.
NONE
writes all output to the file that is currently open.
OUTPUT
starts a new file for each output object. For SAS/GRAPH this means that ODS creates a new file for each SAS/GRAPH output file that the program generates.
Alias:TABLE
PAGE
starts a new file for each page of output. A page break occurs when a procedure explicitly starts a new page (not because the page size was exceeded) or when you start a new procedure.
PROC
starts a body file each time you start a new procedure.
Default:NONE
Restrictions:The NEWFILE= option cannot be used in conjunction with the FILE=fileref option.

The NEWFILE= option cannot be used if you are sending output to a physical printer.

Tips:If you end the filename with a number, then ODS begins incrementing with that number. In the following example, ODS names the first file MAY5.PS. Additional body files are named MAY6.PS, MAY7.PS, and so on.

Example: 

FILE= 'MAY5.PS'

PACKAGE <package-name>
specifies that the output from the destination be added to a package.
package-name
specifies the name of a package that was created with the ODS PACKAGE statement. If no name is specified, then the output is added to the unnamed package that was opened last.
STARTPAGE=NEVER | NO | NOW | YES | BYGROUP
controls page breaks.
BYGROUP
specifies to insert page breaks after each BY group.
NEVER
specifies not to insert page breaks, even before graphics procedures.
CAUTION:
Each graph normally requires an entire page. The default behavior forces a new page after a graphics procedure. STARTPAGE=NEVER turns off that behavior, so specifying STARTPAGE= NEVER might cause graphics to overprint.
NO
specifies that no new pages be inserted at the beginning of each procedure, or within certain procedures, even if new pages are requested by the procedure code. A new page will begin only when a page is filled or when you specify STARTPAGE=NOW.
CAUTION:
Each graph normally requires an entire page. The default behavior forces a new page after a graphics procedure, even if you use STARTPAGE=NO. STARTPAGE=NEVER turns off that behavior, so specifying STARTPAGE= NEVER might cause graphics to overprint.
Alias:OFF
Tip:When you specify STARTPAGE=NO, system titles and footnotes are still produced only at the top and bottom of each physical page, regardless of the setting of this option. Thus, some system titles and footnotes that you specify might not appear when this option is specified.
NOW
forces the immediate insertion of a new page.
Tip:This option is useful primarily when the current value of the STARTPAGE= option is NO. Otherwise, each new procedure forces a new page automatically.
YES
inserts a new page at the beginning of each procedure, and within certain procedures, as requested by the procedure code.
Alias:ON
Default:YES
STYLE=style-definition
specifies the style definition to use in writing the printer output.
Default:If you do not specify a style definition, then ODS uses the style definition that is specified in the SAS registry subkey: ODSthen selectDESTINATIONSthen selectPRINTER. By default, this value is Printer for the PRINTER, PDF, and PS destinations and MonochromePrinter for the PCL destination.
See:For a complete discussion of style definitions, see Working with Styles .

For instructions on making your own user-defined style definitions, see TEMPLATE Procedure: Creating a Style Template.

TEXT='text-string'
inserts a text string into your output.
text-string
is the text that you want to insert into your output.
Requirement:You must enclose text-string in quotation marks.
Tip:If you are submitting more than one procedure step and you do not specify the STARTPAGE=NO option, each procedure will force a new page before the output. Therefore, any text that you specify with TEXT= will be on the same page as the previous procedure.
UNIFORM
for multiple page tables, ensures uniformity from page to page within a single table. When the UNIFORM option is in effect, ODS reads the entire table before it starts to print it so that it can determine the column widths that are necessary to accommodate all the data. These column widths are applied to all pages of a multiple page table.
Default:If you do not specify the UNIFORM option, then ODS prints a table one page at a time. This approach ensures that SAS does not run out of memory while processing very large tables. However, it can also mean that column widths vary from one page to the next.
Note:With BY-group processing, SAS writes the results of each BY group to a separate table, so the output might not be uniform across BY groups.
Tip:The UNIFORM option can cause SAS to run out of memory if you are printing a very large table. If this happens, then you can explicitly set the width of each of the columns in the table, and then print the table one page at a time. To do so, you must edit the table definition that you use. For more information, see What You Can Do with a Table Template .

Details

Opening and Closing the PCL Destination

You can modify an open PCL destination with many ODS PCL options. However, the FILE= and SAS options will perform the following actions on an open PCL destination.
  • close the open destination referred to in the ODS PCL statement
  • close any files associated with the open PCL destination
  • open a new instance of the PCL destination
If you use one of these options, it is best if you explicitly close the destination yourself.

The ODS Printer Family of Statements

The ODS PCL statement is part of the ODS printer family of statements. Statements in the printer family open the PCL, PDF, PRINTER, or PS destination, producing output that is suitable for a high-resolution printer. The ODS PDF, ODS PRINTER, and ODS PS statements are also members of the ODS printer family of statements.

See Also

The Third-Party Formatted Destinations
Statements
ODS PDF Statement
ODS PRINTER Statement
ODS PS Statement
Copyright © SAS Institute Inc. All rights reserved.