TS-432

Producing Hardcopy Output in the UNIX Environment

Dan Lucas and Elizabeth Brownrigg

Elizabeth Brownrigg is a technical writer at SAS Institute in the Host, Database, and Compiler Products department. She has a BA degree in English from the College of William and Mary, an MFA degree in creative writing from Warren Wilson College, and a certificate in software technical writing from Durham Technical Community College. Elizabeth has been a SAS user for three years.

Abstract

You can produce hardcopy SAS text and SAS/GRAPH output under the UNIX operating system by issuing UNIX print commands and SAS commands and statements from within the SAS System. This article discusses how to use UNIX print commands, SAS statements and commands, and the FORM window to format, preview, and print SAS output.

Introduction

You can use UNIX print commands to direct output from the SAS System to a particular hardcopy device. By including print commands and descriptions of the printing devices, you can streamline the printing process by specifying the file reference instead of defining the destination every time you want to print output. You can also use file references to direct graphics output to a graphics device. File references can be specified on the SAS Display Manager System command line or within a SAS program. You can save device driver descriptions for your graphics output in a catalog.

You can modify your text output by specifying SAS options, such as PAGESIZE and LINESIZE, on the command line, or by using the FORM window. Graphical displays, such as the OSF/Motif interface and a Tektronix 4105 terminal, can be used to preview and print SAS/GRAPH output.

UNIX Print Commands

In the UNIX environment, the operating system processes file I/O using device files that are defined in the /dev directory. This device can be a terminal, a floppy drive, a tape, or a printer. One way of printing a file is to direct the file to the output device in the /dev directory. However, this method restricts the use of the device to the printing of a single file at a time and does not allow the device to be shared by more than one user.

Printer spoolers enable several users to share an output device by taking advantage of print queues or spool directories to allow many users to share the same resource.

Before attempting to set up a print facility for use with the SAS System, you should be familiar with the local print window for your environment and the print commands that your environment uses. You should test these print commands in your environment. If a command does not execute when you type it as a shell command, it will not execute from within the SAS System.

System V lp Command

In a System V environment, the print command is lp . When printing a file, the lp command makes a copy of the file in the /usr/spool/lp/destname directory, where destname is the directory that contains the spooled files. The lpsched daemon then moves the file from the destname directory to the appropriate device. A log of all processing performed by lpsched is in the /usr/spool/lp/log file. The syntax of the lp command is as follows:

lp -ddestname -options my.filename

The following example sends the my.output file to the output device identified as hpljr23, with raw specified as an option:

lp -dhpljr23 -oraw my.output

lpadmin

specifies the printer configuration.

accept

flags a printer as available for use.

lpmove

moves files between print devices.

reject

drains a printer and prevents the printer from accepting files for queueing.

disable

drains a printer, but accepts files in queue.

cancel

cancels line printer requests that were made by the lp command.

BSD lpr Command

In a Berkeley Software Distribution (BSD) environment, the lpr command and lpd daemon control access to output devices. When you specify an output destination for a file, the lpr command refers to the /etc/printcap file for printer information and the name of the /usr/spool/destname directory to contain a copy of the file. Once the file is processed by the lpr command, the lpd daemon is notified. This daemon determines if the print device is local and available for use. If the print device is remote, the lpd daemon directs the file to another lpd daemon process running on the remote workstation. The syntax of the lpr command is as follows:

 lpr -
Pdestname -options my.filename 

The following example sends three copies of the my.output file to the output device identified as hpljr23; a link from the spool area to the file is created and then removed.

lpr -Phpljr23 -#3 -s -r my.output

You can use lpq to query the status of a printer. If you have root privileges for your system, you can also use the following BSD print commands:

lpc

makes administrative changes for printers.

lprm

removes queued jobs.

AIX enq Command

In IBM's AIX environment, the print facility is started with the enq print command and controlled by the qdaemon. The qdaemon requests printer information from the /etc/qconfig file. The qdaemon then directs the print file to the appropriate queue in the /usr/lpd/qdir directory and maintains status information about the file in the /usr/lpd/stat directory. The qdaemon process uses the appropriate backend program listed for the specified queue and directs the file to the proper device. The syntax of the enq command is as follows:

enq -Pqueuename -Ncopies -ooptions my.filename

The following example sends the my.output file to ltrhead queue:

 
enq -Pltrhead my.output 

You can use AIX's SMIT (System Management Interface Tool) to administer AIX print devices and queues.

Using a File Reference to Direct Output

You can designate a device for printing SAS output by specifying the PIPE device type in a SAS file reference. The PIPE device type allows you to use the output from the SAS System as input to a UNIX command. For example, the following is a file reference called ascout:

 filename ascout pipe 'lp -dmyljet 
2>$HOME/lp.errors'; 

When ascout is used in a SAS window or program, the specified file or contents of the window is piped to the System V lp command. The lp command prints the file or window contents on a device called myljet and redirects print errors to a file called lp.errors in the user's home directory. You can specify this file reference in an autoexec.sas file or within the SAS program.

Note: Redirecting standard error to 2>$HOME/lp.errors is only allowed in the Bourne and Korn shells. The C shell does not allow this redirection.

Using the PIPE Device Type to Print the Contents of a Window

When you use a UNIX pipe to the lp command, a temporary copy of the file is created under the /usr/spool directory. Large print jobs may have a problem printing via the pipe facility. This limitation is based on the size of the /usr file system.

To circumvent this problem, save the print file to disk, and use lp or lpr to print the disk file. You can create the print file from the display manager pull-down menu or by issuing the following statement from the display manager command line:

 print file='my.file.output' 

A copy of the print file is written to disk. You can then print the file by typing the lp or lpr command from the shell.

Note: The file system that contains the file must have sufficient disk space. To ascertain the amount of disk space available to you, refer to your system manpages for the df command. You can also create a file reference that can handle the large print files. The following file reference will save the output file to disk, print the saved file, and then remove the file:

 filename catout pipe 'cat >BIGFILE; lp -dmyljet BIGFILE; rm 
BIGFILE'; 

Using a File Reference to Produce Text Output

The examples in this section illustrate the different ways you can use file references to produce text output. You can use the PRINTTO procedure to redirect your output directly to a file reference, as in the following example:

   proc printto print=ascout;
   run;

To free the print file for printing, you must specify the following:

   proc printto print=print;
   run;

   proc printto;
   run;

This routes the output to its default destination by resetting the default print file. Because PRINT is a keyword, it is not assumed to be a fileref.

You can also direct the contents of your log to the file reference, as in the following example:

proc printto log=ascout;
run;

Another way to send output to a file reference is to use the PRINT command from the display manager command line, as in the following example:

print file=ascout

You can also use the File pull-down menu to specify your file reference. Select Print from the File menu. Then select Print File. Specify the file reference name as the destination filename.

Note: You can also enter a file pathname for the destination filename, and the print file will be saved onto disk.

For more information on using SAS file references in a UNIX environment, refer to SAS Companion for UNIX Environments: Language, Release 6.09, First Edition.

Listing Current File References

You can get a list of specified file references in the following ways:

• From a SAS program, enter

            filename _all_ list;
     

  A list of file references will be printed in the log.
• Select the Globals pull-down menu. Select Data Management and Filename list. A window showing the filename references will be displayed.
• Enter filename on the display manager command line. A window showing the filename references will be displayed.

Releasing the Print File

When printing text output in display manager, Release 6.09 of the SAS System creates print spool files for the work area. By default, these files are automatically released for printing.

In Release 6.07 of the SAS System, if you used the File pull-down menu to specify your file reference, you must enter a FREE command from the command prompt to release a file for printing. If you exit the SAS System, the print file will automatically be released.

Using a File Reference to Produce Hardcopy Graphics

To produce hardcopy graphics, you must create the output in the correct format and direct it to your hardcopy device. The specific statements required to do this depend on the type of printer you are using. Xerox, QMS (QUIC), and PostScript printers require one set of parameters, while other printers (such as Hewlett-Packard LaserJets or PaintJets) and plotters require a different set. You can specify these parameters in a GOPTIONS statement. Refer to SAS/GRAPH Software: Using Graphics Devices in the UNIX Environment and Derivatives, Version 6, First Edition for more information on printing graphics output.

Xerox, QMS, and PostScript Printers

For Xerox, QMS, and PostScript printers, you can use the following file reference statements to produce output:

   filename grafout pipe 'lp -ddest ';   /* for System V   */
   filename grafout pipe 'lpr -Pdest ';  /* for Berkeley   */
   filename grafout printer 'dest';      /* for both systems       */

   goptions dev=drivername gaccess=sasgaedt gsfname=grafout
         gsfmode=replace gsflen=132
         gprolog='25210d0a'x;  /* GPROLOG needed for    */
                               /* postscript only in    */
                               /* Version 6.07  */

dest specifies the printer destination. The GACCESS value of SASGAEDT causes the driver to append a carriage return and line feed to the end of each record, a requirement for Xerox, QMS, and PostScript printers. The GSFNAME and GSFMODE options cause the output to be sent to the fileref GRAFOUT, and the GSFLEN option sets the length of the records that are written. In some cases you may need to specify GSFLEN=80 for PostScript printers.

In Version 6.07 of the SAS System, if you are sending output to a PostScript printer, you must also include the GPROLOG option. The GPROLOG string specified here causes a record with '%!' characters to be placed at the beginning of the file; these characters are required for the output to be correctly interpreted as PostScript.

Other Printers and Plotters

You can use the following statements to send output directly to other types of printers, such as Hewlett-Packard LaserJets and PaintJets, as well as to most plotters.

   /* for SYSTEM V      */
filename grafout pipe 'lp -ddest -oraw'; 
goptions dev=drivername gaccess=sasgastd gsfname=grafout
         gsfmode=replace;

   /* for Berkeley systems      */
filename grafout pipe 'lpr -Pdest -oraw';
goptions dev=drivername gaccess=sasgastd gsfname=grafout
         gsfmode=replace;

   /* for both systems  */
filename grafout printer 'dest -oraw';
goptions dev=drivername gaccess=sasgastd gsfname=grafout
         gsfmode=replace;

The FILENAME statement pipes the output to the lp or lpr command as described in the previous section. For these types of printers you must also specify the -oraw option to prevent modification of the data stream or addition of carriage control by the interface program. GACCESS=SASGASTD causes output to be written without carriage control, and the GSFNAME and GSFMODE options direct output to the fileref specified in the FILENAME statement. You do not have to specify the GSFLEN or GPROLOG options when sending output to these printers.

Creating and Modifying Device Driver Entries for Graphics Output

If you have many users sending output to one or more devices, or if you are using SAS/ASSIST software to produce hardcopy graphics, you can create a device catalog entry that contains parameters corresponding to the GOPTIONS specified above. By creating device driver entries you eliminate the need for users to specify GOPTIONS (except for the DEVICE= option) or FILENAME statements in their file reference statements.

The following steps illustrate how to create driver entries to send output directly to hardcopy devices. These steps assume that you are creating a new driver entry in the SASHELP.DEVICES catalog that will be used by all SAS/GRAPH users at your site, and that you have update authority for the SASHELP directory.

1. Invoke the GDEVICE procedure as follows to display a directory window listing all entries in the SASHELP.DEVICES catalog:

           proc gdevice c=sashelp.devices;
   

2. Use the COPY command to create a new driver entry by copying the original SAS/GRAPH driver for your device. For example, you can create a new driver named NEWPS for PostScript printers by copying the PS300 driver. If you are using pull-down menus, you can do this by selecting Copy from the File pull- down menu and entering PS300 in the SOURCE field and NEWPS in the target field. If you are not using pull- down menus, you can issue the following on the command line:

           copy ps300.dev newps.dev
   

   This adds the entry NEWPS to the SASHELP.DEVICES catalog; the directory window is scrolled to that entry.
3. Select the NEWPS entry by placing an S in the selection field and pressing RETURN. This opens the NEWPS entry and displays the DETAIL screen for the entry.
4. Change the following parameters on the DETAIL screen of the entry that you copied. For Xerox, QMS, or PostScript printers, change the GACCESS field to

            SASGAEDT>lp -ddest    (for System V)
   
        or
   
            SASGAEDT>lpr -Pdest    (for Berkeley systems)
   

   Change the GSFLEN value to 80 or 132. In all of the above cases dest should be replaced by the destination name for the printer on your system.
5. For other printers and plotters, after copying the Institute-supplied driver entry, change the GACCESS field to

            SASGASTD>lp -ddest -oraw (for System V)
        
      or
   
            SASGASTD>lpr -Pdest -oraw (for Berkeley systems)
    
     or
   
            SASGASTD>printer 'dest -oraw' (for both systems)
   

   In all of the above cases dest should be replaced by the destination name for the printer on your system.
6. For all devices, change the value of DEVTYPE to PIPE and the value of GSFMODE to REPLACE.
7. For PostScript devices, go to the GPROLOG window by selecting go to gprolog window from the LOCALS pull-down menu (or by entering the command GPROLOG on the command line of the DETAIL window). In the GPROLOG window, enter the string 25210d0a on the first blank line.

After filling in the necessary fields, press the END key (F3) until you return to the SAS PROGRAM EDITOR window. Once you have created the new driver, SAS/GRAPH users at your site need only specify the appropriate driver (NEWPS in this example) to send output directly to this hardcopy device.

Creating Your Own Device Catalog

If you want to create a new driver entry for your own use, you should create your own device catalog, copy the Institute-supplied driver to it, and modify the entry there. For example, you can use the following statements to create your own catalog:

libname gdevice0 'yourdirectory';
   proc gdevice c=gdevice0.devices;

This creates the catalog GDEVICE0.DEVICES in the directory yourdirectory with no entries (unless the catalog existed previously). You can then follow the instructions above to copy and modify members. When copying the Institute- supplied driver to your catalog, you must give the fully-qualified name as the source entry (for example, SASHELP.DEVICES.PS300.DEV). For more information on PROC GDEVICE and the GOPTIONS statement, refer to SAS/GRAPH Software: Using Graphics Devices in the UNIX Environment and Derivatives.

Using SAS Options to Modify Your Text Output

The default physical line size (number of characters per line) and page size (number of lines per page) of the files for the SAS log and procedure output depend on their destinations. If these files will appear on your display, the default line size and default page size are derived from the size of your display. If the files will be written to disk, then the default line size is 132, and default page size is 60. These two attributes can be overridden with the LINESIZE and PAGESIZE system options. You can specify these options in an OPTIONS statement, within the CONFIG.SAS file, or in the OPTIONS window. For example, if you would like your SAS output file to have 40 lines per page, with a line width of 100 characters, specify the following on the command line:

sas -pagesize 40 -linesize 100

Using the FORM Window in the SAS System

You can use the FORM window to print formatted text. The FORM window is similar to the SAS graphics catalog in that it enables you to select various capabilities supported by your printer, such as choosing a special font, printing in portrait or landscape mode, specifying line width and number of lines per page, or choosing a printer paper drawer.

Creating a Form

You can create a form in one of two ways:

1. From a SAS command line, enter

           fsforms libref.catalog-name.form-name
   

2. From the File pull-down menu, select Print and Open a form. Display 1 illustrates the Open a form dialog box.

In the Open a form dialog box, type the following information as shown:

Enter libname:       sasuser
Enter catalog name:  myforms
Enter form name:     hpljletr

• From the command line or the PMENU, enter nextscr and prevscr to go forward and backward.
• From the Locals pull-down menu, choose Next Screen.

If you do not specify a library reference or catalog name, the new form is created by default in the sasuser.profile catalog. You can override this default by specifying a different library reference and catalog name. For more detailed information on the FORM window, refer to SAS Language: Reference, Version 6, First Edition.

Creating Sample Form hpljletr

This section contains an example of creating a form called hpljletr. This form prints letterhead output on a Hewlett-Packard LaserJet IIIsi. The form prints one page of letterhead from the lower drawer and then continues printing the remainder of the job on regular paper from the top drawer. The form is saved in the sasuser.myforms catalog. Enter the following command:

fsforms sasuser.myforms.hpljletr

You should now see on the title of the form hpljletr.form, as in Display 2.
Display 2 Printer Selection Frame

Place the cursor on the type of printer you will be using for output. This selection will be used to define your Font Control Information Frame control and escape sequences for your printer type.

You can edit the HPLJLETR.FORM field. You cannot reselect the printer type without removing the entry and re-creating the form. You cannot continue to the next form frame until you choose a printer.

In Display 3, you can modify the values for lines per page, columns per line, and the margins. These settings override any settings defined in the SAS PAGESIZE and LINESIZE options. On this frame the number of lines and the top margin for the first page have been modified. These changes accommodate the company logo on letterhead paper.

Display 3 Text Body and Margin Information Frame

The Carriage Control Information frame controls the generation of carriage control information, as in Display 4.

Display 4 Carriage Control Information Frame

The FORM window uses the lp print command. Display 5, the UNIX Print File Parameters frame, enables you to set lp command options.

Display 5 UNIX Print File Parameters Frame

You can specify the following -lp options on the UNIX Print File Parameters frame. Refer to your system manpages for information on lp and lpr options.

-t 'this is my special report'

gives the printout a title.

-p7

sets a priority.

-oh

suppresses printing the header page.

-otext

specifies that the print file contains only text and no PCL (Printer Control Language) statements.

-opcl

specifies that the print file contains special control characters.

The attributes defined in Display 6, the Font Control Information frame, are based on the printer chosen in the first frame. The top part of the frame has spaces for you to define up to eight special characters that represent printer control characters. These characters are then used in the bottom of the frame to define text attributes. Refer to your printer documentation for information on control and escape sequences for your printer.

Display 6 Font Control Information Frame

The last blank page of sequence numbers is a screen that allows you to send sequences of printer control language statements with your job stream. The printer control language allows you to control fonts, print orientation, and from which drawer to pull the paper, as shown in Display 7. For a list of the control sequences that are available for your print device, refer to your printer's reference card for the supported control sequences.

Display 7 Printer Control Language Frame

The following specifications are valid in this frame:

PRINT INIT

uses the following control sequences at the initialization of the print job. This example specifies that the top drawer be used for the cover sheet, normally the header page of printer output.

PAGE 1

loads the next control sequence before printing the first page of output and uses these settings until the next PAGE statement or PRINT TERM. This sequence instructs the printer to get the first page of paper from the bottom paper drawer, where the letterhead is kept.

PAGE 2

loads the next control sequence before printing the second page of output and for the remainder of the print job. The example given tells the printer to go back to regular paper for pages 2-n.

PRINT TERM

uses the last sequence on the termination of the print job. The sequence shown in the example is resetting the printer back to the initial settings.

Use the END or SAVE command or FILE/END from the pull-down menus to save the completed form. Now you are ready to use your new form.

Printing with a Form

If you are working with SAS LOG and OUTPUT windows and attempting to use a form with this type of text, you can set a form by one of the following methods:

• Issuing the statement

       options forms=sasuser.myforms.hpljletr;   

• Selecting Print and Set Form from the File pull-down menu. Enter the name of the form.

Once the form has been set, the next output file that is printed uses this form for the print characteristics and destination.

If you are using the FSLETTER procedure and forms, you can set the form name for your letter in the following ways:

• On the command line of the letter, enter

     form sasuser.myform.formname
     

• Using the Locals pull-down menu, select Assign a Form, and enter the form name.
• From the File pull-down menu, select Print and Set Form Name. Enter the form name.

The SAS FORM window uses lp as the default print command. To override the default, you can create an alias of your system's print command. Files are directed to the command referenced by the alias and passed the lp print options from the Print File Parameter frame. For example, if your system uses the C shell and a print command called nlp, you can add the following to your .cshrc file:

alias lp 'nlp' 

From a Bourne and Korn shell, you can create a symbolic link to your systems print command, as in the following example:

ln -s /usr/local/bin/nlp $HOME/bin/lp 

Obtaining a List of Forms

You can display a list of available forms by using the CATALOG procedure to display the contents of the catalog, as in the following example:

catalog libname.catname  

Common Problems with Form Setup and Usage

The following sections describe some common problems associated with using the FORM window and how to resolve them.

Unrecognized File Type

If the only line of your print file is unrecognized file type, you may be trying to send control sequences to the printer without having specified the correct printer option to specify a mixture of ASCII and control sequences. Check the UNIX Print File Parameters FORM window and your specified -o options.

Unwanted Page Breaks

If blank pages are appearing in the middle of your output, you may have specified the wrong settings on the Carriage Control frame for your form. By default, SAS writes page ejects at the end of each page; therefore, if you highlight on the Carriage Control frame to send page ejects after pages, you may be receiving extra blank pages in your output. Confirm the top margin and page length specifications. Your job may be writing past the end of a page.

Output Title and No Text

If your output contains only the job header page and title line, reconfirm the print options on the UNIX Print File Parameters frame. If your form is printing SAS log and output windows that contain carriage control characters, and you are sending additional PCL statements to the printer via the Printer Control Language frame, you must add the appropriate print command option.

Output Printed in Duplex Mode

If your printer supports duplex printing and you want to print in simplex mode, specify the appropriate option in the UNIX Print File Parameters frame. Consult your UNIX system administrator for the appropriate option.

Previewing and Printing Graphs

If you are using the X Window System to preview hardcopy graphics, specify your hardcopy driver with the TARGETDEVICE= option, as in the following example:

goptions targetdevice=newps; 

The graph displays on your monitor using the default colors, orientation, and text size for the NEWPS driver. To print the graph, select Print from the File pull-down menu (or enter PRINT on the command line of the GRAPH window), and output is sent to the printer, using the parameters specified in the NEWPS entry in your device catalog.

If you have used GOPTIONS and FILENAME statements instead of creating a new device entry, you can also use the TARGETDEVICE= option and PRINT command to preview and print your graphs. Just supply the FILENAME and GOPTIONS statements before you produce the graph. When you issue the PRINT command, the information provided in those statements is used to send the graph to your printer.

Conclusion

By combining UNIX print commands with the flexibility of the SAS System, you can easily control the format and destination of your printed output. Filerefs and the PRINT device type can be used to print the contents of windows or text and graphics files. SAS options and the FORM window enable you to modify your text output and, with the X Window System, you can preview your graphs before sending them to an output device.

SAS, SAS/ASSIST, and SAS/GRAPH are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. AIX is a registered trademark or trademark of International Business Machines Corporation.
Other brand and product names are registered trademarks or trademarks of their respective companies.